网关

能力

能力是一个动作(如“代币价格”),由多个路径和参数各不相同的提供方提供。你只需传一组参数;网关选择最健康的提供方,调用失败时自动切换到下一个。

GET/cap/{slug}

鉴权

与 /gw 相同:Authorization: Bearer pk-…。每次尝试都走标准代理流程(余额、限流、计费、日志),你只按实际返回结果的那个提供方的价格付费。失败的尝试不收费。

参数

路径参数

slugstring必填

能力 slug,如 token-price、token-search、trending-tokens、wallet-balances、gas-price、token-security、swap-quote、x-profile。

查询参数

{param}string

能力自身的参数(由下面的能力列表接口给出),如 token-price 的 token。缺少必填参数时返回带 missing 列表的 400。

providerstring

可选。用 API slug 指定某个提供方,不做自动路由。

请求示例

bash

curl -i "https://gw.pikeway.ai/cap/token-price?token=WBTC" \
  -H "Authorization: Bearer $PIKEWAY_API_KEY"

响应

响应 body 是实际提供服务的提供方的原始响应,结构取决于是哪个提供方返回的。请查看 X-Pikeway-Routed-To。

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
X-Pikeway-Capability: token-price
X-Pikeway-Routed-To: pikeway-crypto
X-Pikeway-Attempts: pikeway-crypto:200
X-Pikeway-Call-Id: 0192f6a4-08d2-7c11-8a3e-2b6f0c9d1e47
X-Pikeway-Cost: 0.001

{ ...provider response... }

响应头

X-Pikeway-Capabilitystring

能力 slug。

X-Pikeway-Routed-Tostring

返回结果的提供方的 API slug。

X-Pikeway-Attemptsstring

按顺序列出尝试过的每个提供方,格式 api:状态码(参数填不满路径时为 api:skipped),如 dexscreener:502,pikeway-crypto:200。

X-Pikeway-Call-Id · X-Pikeway-Cost

来自最终返回的那次尝试,与 /gw 相同。

路由规则

只有已上线、公开的提供方才是候选。
候选按近 1 小时成功率排序(调用少于 5 次的视为健康),其次按 p50 延迟,再按能力的默认顺序。
某次尝试返回 5xx、429 或业务码失败的 2xx 时,换下一个提供方。其他响应(包括 4xx)原样返回。

错误

400 missing required parameters (带 missing)。
400 no provider could be called with these parameters 所有提供方都被跳过。
404 unknown capability: {slug} · 404 no live provider for capability {slug}
405 GET only
以及最终返回的那次尝试产生的 /gw 错误(401、402、429…)。

能力列表

GET/papi/capabilities

能力目录由 Pikeway 网站(control API)提供,而不是网关:GET /papi/capabilities 获取全部,GET /papi/capabilities/{slug} 获取单个。无需 key。每条记录列出参数,以及在线提供方的价格和近 30 天统计。也可以在能力页面浏览。

bash

curl https://<your-pikeway-site>/papi/capabilities

200 OK

[
  {
    "slug": "token-price",
    "title": "Token price",
    "group": "Market data",
    "description": "Current USD price of a token by symbol or address.",
    "params": [
      { "name": "token", "label": "Symbol or contract address", "example": "WBTC", "required": true }
    ],
    "providers": [
      {
        "api": "pikeway-crypto",
        "name": "Pikeway Crypto",
        "category": "Crypto",
        "note": "median across sources",
        "price": 0.001,
        "billingType": "PER_CALL",
        "successRate30d": 0.997,
        "p50Latency30d": 240
      }
    ]
  }
]

能力不存在、已停用或没有在线提供方时,GET /papi/capabilities/{slug} 返回 404(capability not found)。