网关

调用 API

把请求代理到市场里的任意 API。Pikeway 验证你的身份、注入提供方凭据、转发请求,只在调用成功时按端点价格扣费。

ANY/gw/{slug}/{path}

/gw/{slug} 之后的一切(路径、查询参数、方法、body 和大部分请求头)都会转发到提供方的基础地址。路径与 API 市场页面上显示的一致;/v1/inspect 也会返回。

鉴权

以 Authorization: Bearer pk-…(或 X-API-Key)发送 key。

参数

路径参数

slugstring必填

API 的 slug,如 birdeye、coingecko(见其市场页面)。

pathstring

上游路径,原样转发。%2F 等百分号编码字符保持编码状态。

查询参数与 body

…any

上游端点需要的任意参数。端点上标记为必填的查询参数会先被检查:有空值时直接返回带 missing 列表的 400,不转发也不扣费。

请求头

AuthorizationBearer pk-…

你的 Pikeway key,转发前会被去掉。

Idempotency-Keystring ≤ 255

可选。同一个值网关最多转发并扣费一次,重复会返回 409。在提供方标记为可安全重试时,也允许 POST/PATCH 请求切换到备用上游。

其他请求头会传给上游,但 Cookie、Origin、Referer、X-Forwarded-*、sec-fetch-* / sec-ch-* 和 Accept-Encoding 除外。

请求示例

bash

curl "https://gw.pikeway.ai/gw/birdeye/defi/price?address=So11111111111111111111111111111111111111112" \
  -H "Authorization: Bearer $PIKEWAY_API_KEY" -i

POST、PUT、PATCH 和 DELETE 用法相同,发送上游需要的 body 即可:

bash

curl -X POST "https://gw.pikeway.ai/gw/{slug}/{path}" \
  -H "Authorization: Bearer $PIKEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-7781" \
  -d '{"...": "..."}'

响应

原样返回提供方的状态码、响应头和 body,外加 Pikeway 的响应头。API 没有配置响应规则或缓存时,SSE 和大响应会边收边转发。

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
X-Pikeway-Call-Id: 0192f6a1-3c1e-7b5a-9d2e-5c4f1a7e8b90
X-Pikeway-Cost: 0.001

{
  "success": true,
  "data": { "value": 172.41, "updateUnixTime": 1761297120 }
}

Pikeway 响应头

X-Pikeway-Call-Idstring

调用 id(也是 GET /v1/runs/{id} 的 runId)。成功和上游失败时都会返回。

X-Pikeway-CostUSD

扣费金额。未计费时为 0(非 2xx、业务码失败、套餐含量内、使用自己的 key)。

X-Pikeway-CacheHIT | MISS

提供方开启响应缓存时返回(仅 GET)。命中按原价计费。

X-Pikeway-Plan · X-Pikeway-Quota-Remainingstring · int

本次调用使用了你的套餐时返回。

X-Pikeway-Volume-Discountpercent

本次调用适用的阶梯折扣。

X-Pikeway-Upstream-Errorstring

2xx 被判为失败时返回 business-code、graphql-errors 或 grpc-status-N(不计费)。

X-Pikeway-Upstream-Attemptsint

网关故障切换时实际尝试的上游个数。

X-Pikeway-Byok1

使用了你自己的上游 key;不扣费。

每次调用的处理流程

按 slug 找到 API,验证 key(吊销、IP 和来源限制)。
执行限流:先是每秒突发限制,再是 API 的单 key 限制(或套餐的每分钟限制)。
按方法和路径匹配端点得到价格;应用套餐含量、阶梯折扣或你自己的上游 key。
校验:必填查询参数,以及提供方开启时的请求 schema。
检查余额和 key 的消费上限,然后冻结本次价格。
转发给提供方(可安全重试的请求会切换到备用上游),判断是否成功。
成功则扣除冻结金额,否则退回,然后返回响应。

错误

400 missing required query parameters(带 missing)、schema 校验失败。
401 缺少 key 或 key 无效。 402 余额不足或 key 消费上限已到。
403 key 限制、需要套餐、key/账户被暂停、缺少自己的上游 key。 404 API 不存在或为私有。
409 Idempotency-Key 重复。 429 限流和套餐额度(见 Retry-After)。
502 上游不可达(不扣费)。 503 计费暂不可用或 API 被暂停(不扣费)。

完整列表见错误码。

免费 Mock 响应

ANY/mock/{slug}/{path}

路径与 /gw 相同,但返回端点的示例响应,而不是调用提供方。无需 key、不收费、不访问上游。适合在付费前先把解析代码写好。每个 IP 每分钟最多 30 次。

bash

curl -i "https://gw.pikeway.ai/mock/birdeye/defi/price?address=So11111111111111111111111111111111111111112"

响应 body 取端点的第一个 2xx 示例:优先已发布的 example,其次 examples[*].value,否则按响应 schema 生成样例。响应带 X-Pikeway-Mock: true 和 X-Pikeway-Cost: 0。

404 no endpoint matches GET /… 没有该方法和路径的端点。
404 no example response yet for this endpoint … 提供方还没有发布示例(若开启了自动示例,会在第一次成功的真实调用后出现)。
429 mock rate limit exceeded (30/min)

WebSocket

带 WebSocket 端点的 API 通过 /ws/{slug}/{path} 代理。必须带 key(请求头,浏览器可用 ?key=pk-…);按连接、消息或分钟计费。见 WebSocket 指南。

不知道 slug 或路径?先用 /v1/discover 和 /v1/inspect,或者让 /v1/run 根据结构化输入帮你构造请求。