集成 · 直连

直连接入步骤

创建 key,把它锁定到你的服务器,然后从后端调用任意 API。给每个 agent 或租户单独的预算,避免一个失控的循环花光你的余额。

1

创建一把服务端 key

先在控制台 → 账单充值,再到控制台 → API Key 创建 key。key 以 pk- 开头,明文只显示一次。把它作为密钥保存,比如放进服务器环境变量或密钥管理器里的 PIKEWAY_API_KEY。

以 Authorization: Bearer pk-… 发送,也接受 X-API-Key 请求头。

2

给 key 加上限制

在控制台 → API Key 中打开这把 key,按它的运行环境设置限制。网关会在扣费之前校验这些限制。

额度USD

这把 key 累计最多能花多少。达到后付费调用返回 402 api key spend limit reached。可随时调高、移除,或把已花金额清零。

IP 白名单IP / CIDR

最多 100 个 IP 或 CIDR 网段(IPv4 或 IPv6)。来自其他地址的调用返回 403 client IP not allowed for this API key。出口 IP 固定的服务端 key 都应该设置。

站点hostnames

把 key 变成只能在你域名下的页面中使用的浏览器 key。仅用于前端;见浏览器 key。

不要把没有限制的服务端 key 放进网页、移动应用或公开仓库。拿到它的人都能花你的余额。如果 key 泄露,请立即吊销或轮换。

3

从后端调用 API

用 /v1/discover 找到端点,用 /v1/inspect 查看输入和价格(两者都免费),然后执行。/v1/run 会根据结构化输入拼出上游请求,并返回一个 run 对象。

POST/v1/run

bash

curl -X POST https://gw.pikeway.ai/v1/run \
  -H "Authorization: Bearer $PIKEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-price" \
  -d '{
    "provider": "birdeye",
    "endpoint": "/defi/price",
    "input": { "address": "So11111111111111111111111111111111111111112" }
  }'

响应

HTTP/1.1 200 OK
X-Pikeway-Call-Id: 0192f6b0-5e2a-7d40-b1c3-8f9e2a4d6c11
X-Pikeway-Cost: 0.001

{
  "runId": "0192f6b0-5e2a-7d40-b1c3-8f9e2a4d6c11",
  "provider": "birdeye",
  "endpoint": "/defi/price",
  "method": "GET",
  "status": "COMPLETED",
  "output": { "data": { "value": 171.42 }, "success": true },
  "providerResponse": { "httpStatus": 200, "contentType": "application/json", "cache": "" },
  "cost": { "value": 0.001, "currency": "USD" },
  "durationMs": 312
}

想直接按提供方自己的请求格式调用?改用原始网关即可。完整参数见 /v1/run 和网关参考。

bash

# Same call through the raw gateway: your request is forwarded as-is
curl "https://gw.pikeway.ai/gw/birdeye/defi/price?address=So11111111111111111111111111111111111111112" \
  -H "Authorization: Bearer $PIKEWAY_API_KEY"

4

给每个 agent 或租户单独的预算

在控制台 → Team 为每个 agent、worker 或客户签发一把 agent key。每把 key 有自己的预算(最高 $100,000),从你的余额扣费。控制台会显示每把 key 近 30 天的花费、调用次数和最后使用时间,也可以单独吊销某一把而不影响其他 key。

一个 agent 一把 key,卡死的重试循环会停在它自己的预算上,而不是花光你的余额。
一个租户一把 key,不用自己做计量就能看到每个客户的花费。
用 agent 或租户的名字给 key 命名:名字会出现在日志和用量视图里。

5

监控花费并处理错误

任何 key 都能读取所属账户的余额;设置了额度的 key 还能看到自己剩余的预算。可以在长任务开始前检查,或据此设置告警。

GET/v1/wallet/balance

bash

curl https://gw.pikeway.ai/v1/wallet/balance -H "Authorization: Bearer $PIKEWAY_API_KEY"

响应

{
  "balance":   { "value": 48.21, "currency": "USD" },
  "earnings":  { "value": 0, "currency": "USD" },
  "keyBudget": { "limit": 20, "used": 3.47, "remaining": 16.53, "currency": "USD" },
  "spendable": { "value": 16.53, "currency": "USD" }
}

状态码	错误信息	怎么处理
`401`	`invalid or revoked API key`	key 已被吊销、已过期或填错了。换成当前有效的 key。
`402`	`insufficient balance`	充值,或在控制台 → 账单开启自动充值。
`402`	`api key spend limit reached`	这把 key 达到了额度。调高额度,或让 agent 停下。
`403`	`client IP not allowed for this API key`	调用来自白名单之外的 IP。
`429`	`rate limit exceeded`	退避后重试。

以上情况都不扣费。超时后重试付费调用时,带上相同的 Idempotency-Key 请求头,确保同一次调用不会被扣两次费。完整列表见错误码。

6

无停机轮换 key

在控制台 → API Key 中轮换 key。新 key 会复制所有设置和已花金额;旧 key 在宽限期内继续可用(默认 24 小时,最长 7 天,设为 0 则立即失效),方便你部署新 key。

安全清单

key 只放在服务器上,存进密钥管理器或环境变量,绝不提交到代码仓库。
每把 key 都设置额度;服务端 key 还要设置 IP 白名单。
按环境(dev、staging、prod)和 agent 分开使用不同的 key。
在请求到达 Pikeway 之前先对你自己的用户限流:他们触发的调用由你买单。

余额、按次计价和计费响应头的更多信息:Key、余额与计费。