集成 · 自建代理

自建代理接入步骤

搭一个轻量服务:认证你的用户、执行你的规则、用你的 key 转发到 Pikeway,并记录每次调用的费用。

1

给代理建一把专用 key

在控制台 → Keys 新建一把只给代理用的 key。设一个消费上限兜底;如果代理出口 IP 固定,再加上 IP 白名单。只把它以 PIKEWAY_API_KEY 存在代理主机上。

绝不要把这把 key 发给用户或放进前端。用户用你自己的凭证向代理认证。

2

写转发服务

代理保持 Pikeway 的路径不变,/v1/* 和 /gw/* 请求原样透传。它把用户凭证换成你的 key 转发,再把上游响应原样返回。

proxy.mjs

// proxy.mjs: a minimal Pikeway proxy (Node 18+). Run behind your own TLS.
import http from "node:http";

const UPSTREAM = "https://gw.pikeway.ai";
const KEY = process.env.PIKEWAY_API_KEY;          // your proxy's own key; never sent to users
const ALLOW = /^\/(v1\/(discover|providers|run|runs)|gw\/(birdeye|coingecko))\b/;

http.createServer(async (req, res) => {
  const user = await authenticate(req);            // your sessions / API keys / SSO
  if (!user) return send(res, 401, { error: "unauthorized" });
  if (!ALLOW.test(req.url)) return send(res, 403, { error: "endpoint not allowed" });
  if (!(await hasCredit(user))) return send(res, 402, { error: "top up your account" });

  const body = ["GET", "HEAD"].includes(req.method) ? undefined : await readBody(req);
  const up = await fetch(UPSTREAM + req.url, {
    method: req.method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": req.headers["content-type"] ?? "application/json",
      // one key per logical call, so retries are never charged twice
      ...(req.headers["idempotency-key"] && { "Idempotency-Key": `${user.id}:${req.headers["idempotency-key"]}` }),
    },
    body,
  });

  const callId = up.headers.get("X-Pikeway-Call-Id");
  const cost = Number(up.headers.get("X-Pikeway-Cost") ?? 0);
  if (callId) await recordUsage({ userId: user.id, callId, cost, price: cost * 1.2 }); // your markup

  res.writeHead(up.status, { "Content-Type": up.headers.get("content-type") ?? "application/json" });
  res.end(Buffer.from(await up.arrayBuffer()));
}).listen(8080);

const send = (res, s, j) => { res.writeHead(s, { "Content-Type": "application/json" }); res.end(JSON.stringify(j)); };
const readBody = (req) => new Promise((ok) => { const c = []; req.on("data", (d) => c.push(d)).on("end", () => ok(Buffer.concat(c))); });

authenticate、hasCredit、recordUsage 由你实现:接上你自己的用户库和计费。

3

决定用户能访问什么

按路径和提供方做白名单(上面的 ALLOW)。其他请求在产生费用前就返回 403。
可以在转发前注入或去掉参数,比如固定链、限制分页大小。
在你这一侧按用户限流和配额;key 的消费上限只是最后一道防线。

4

记录每次调用的费用

Pikeway 在响应上返回每次调用的费用。把它记到对应用户名下,再按你的方式收费。

响应头	含义
`X-Pikeway-Call-Id`	这次调用的唯一 id;同样的 id 会出现在你的 Pikeway 账本和调用日志里。
`X-Pikeway-Cost`	这次调用从你余额扣的美元数。只有 2xx 响应计费,其他为 0。
`X-Pikeway-Cache`	响应来自缓存时出现。

每次逻辑调用传一个 Idempotency-Key(如上按用户加前缀)。同一把 Pikeway key 下相同的 Idempotency-Key 只转发和扣费一次,重试是安全的。

5

让客户端指向代理

Pikeway CLI、SDK 和 Skill 都读取 PIKEWAY_API_BASE_URL,无需改代码即可对接你的代理。

Terminal

# Point any Pikeway client at your proxy instead of Pikeway
export PIKEWAY_API_BASE_URL=https://pikeway-proxy.acme.example
export PIKEWAY_API_KEY=acme_user_token_…   # your token, checked by your proxy

pikeway discover -q "token price"          # → your proxy → Pikeway
pikeway run -p birdeye -e /defi/price -i '{"address":"So111…112"}'

6

与 Pikeway 账本对账

定期拉取余额流水,按 call id 与你的用量表逐条匹配。匹配不上的 id 就是绕过了你记账的调用。

Terminal

# Every charge on your Pikeway balance, newest first (paginate with nextCursor)
curl "https://gw.pikeway.ai/v1/wallet/activities?limit=100" \
  -H "Authorization: Bearer $PIKEWAY_API_KEY"

流式和异步任务同样可以透传:把响应体按流转发,客户端通过代理轮询 /v1/runs/:id 即可。