给你的 Agent / 系统装上付款前风险检查

幂等键：安全地重试付款

网络中断时，你的 Agent 不知道付款请求到底执行了没有。给 POST /api/pay 的付款调用（以及 rotate）带上 Idempotency-Key 请求头，重试时保持同一个 key、同一个 nonce、同样的请求体：24 小时内我们原样返回第一次的响应，不会重复执行，也不会把这次重试记成重放攻击。语义参照 IETF 草案 draft-ietf-httpapi-idempotency-key-header。

curl -X POST "https://oceanalt.com/api/pay" \
  -H "content-type: application/json" \
  -H "x-agent-secret: $OCEANALT_AGENT_SECRET" \
  -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
  -d '{"agentId":"my-agent","amountUsdc":1,"to":"0x…","purpose":"api-credits","nonce":"b3f1c2…"}'

• Idempotent-Replayed: true — 同 key、同请求体、同凭证的重试：原样返回第一次的状态码和响应体。
• 422 idempotency_key_reused — 同一个 key 用在了不同的请求体上（比如重试时换了 nonce）。没有执行。
• 409 idempotency_request_in_progress — 第一次请求还在处理中。这是并发，不是重放攻击，不记威胁。等 retry-after 秒后原样重发。
• 400 idempotency_key_invalid — key 需为 1–255 个可打印 ASCII 字符，建议用 UUID。

回放必须出示与第一次相同的 x-agent-secret，只知道 key 的人拿不到你的响应。不带这个头的调用，行为与以前完全一样。要发起一笔新的付款，请换新的 key 和新的 nonce。

Webhook 签名与验签

在控制台（/keys）配置了 webhook 的，你的 Agent 付款被拦下时，我们会 POST 一段 JSON 到你的地址。每条消息都按 Standard Webhooks 规范签名，你的系统可以确认它真的来自 OceanAlt、没有被改过、不是旧消息重放。

• webhook-id — 消息唯一编号；同一条消息重试时不变，请按它去重。
• webhook-timestamp — 发送时间（Unix 秒）。与你的当前时间相差超过 5 分钟就拒绝。
• webhook-signature — v1,<base64>：对「webhook-id.webhook-timestamp.原始请求体」做 HMAC-SHA256，密钥是 whsec_ 之后那段 base64 解码出的字节。轮换密钥后 24 小时内会带两个签名（空格分隔），任一匹配即可。

Node 验签示例（零依赖，这段代码在我们的自测里原样跑过）：

import { createHmac, timingSafeEqual } from "node:crypto";

// secret:  the whsec_… value shown once in the console
// rawBody: the request body exactly as received (do NOT JSON.parse and re-stringify it)
export function verifyOceanAltWebhook(secret, headers, rawBody, toleranceSec = 300) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigs = headers["webhook-signature"];
  if (!id || !ts || !sigs) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false; // stale or replayed

  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key).update(id + "." + ts + "." + rawBody).digest();

  // during a rotation there are two space-separated signatures; accept if either matches
  return sigs.split(" ").some((entry) => {
    const [version, b64] = entry.split(",");
    const got = Buffer.from(b64 || "", "base64");
    return version === "v1" && got.length === expected.length && timingSafeEqual(got, expected);
  });
}

// Express example:
// app.post("/hooks/oceanalt", express.raw({ type: "application/json" }), (req, res) => {
//   const raw = req.body.toString("utf8");
//   if (!verifyOceanAltWebhook(process.env.OCEANALT_WEBHOOK_SECRET, req.headers, raw)) return res.sendStatus(401);
//   const event = JSON.parse(raw); // then deduplicate on req.headers["webhook-id"]
//   res.sendStatus(204);
// });

也可以用任意 Standard Webhooks 库验签（standardwebhooks.com），把控制台给你的 whsec_ 密钥传进去即可。

签名密钥在控制台生成，只显示一次，可随时轮换。收件方要在约 5 秒内回 2xx；没送到的会在 1 分钟、5 分钟、30 分钟、2 小时后自动重试，最多共 5 次，不跟随重定向。每次尝试的状态码、耗时和错误摘要都在控制台的「最近投递」里，保留 30 天。

给密钥上三道锁：能力范围、IP 白名单、过期时间

密钥默认什么都不限，你已经在用的密钥不受影响。持有者可以自己加上限制。它们决定这把密钥万一泄露，对方能拿它做多少事。

能力范围（scope）：这把密钥能调哪些接口

• screen_address — 查地址：单个收款地址筛查（?on= 时点查询不读密钥，不受影响）GET /api/risk
• screen_endpoint — 查付款网址：这个端点是不是已知钓鱼站GET /api/endpoint
• decide — 付款前判决：allow / review / decline（含可选的付款意图检查）GET /api/decide · POST /api/decide
• payee_decide — 收款方决策：接不接这笔钱POST /api/payee/decide
• batch_screen — 批量筛查：一次最多 25 个地址（付费的 POST /api/x402/batch 按付款认，不读密钥）POST /api/risk/batch
• trace_funds — 资金流追踪：多跳沾染追踪与上下游对手方分析（同一份上游资金数据的两种看法，合成一组）GET /api/risk/trace · GET /api/risk/flow
• evidence_bundle — 证据包：一个地址的 Ed25519 签名证据包GET /api/evidence/bundle
• intent_check — 盲签比对：这段 calldata 真正会执行什么，与你声称要付的那笔对不对得上POST /api/intent/check
• baseline_lookup — 控制基线查询：结算前查对手方自证过哪些控制项GET /api/baseline/lookup

上面没列出来的接口不读密钥，按来源 IP 限流：x402 付费端点（按付款认，本来就不需要密钥）、时点查询 GET /api/risk?on=，以及网关、履约、注册表那几个接口。MCP 端点 POST /api/mcp 是可选的：不带密钥照常全部可用；带了密钥，工具调用按密钥限流，持有者设的能力范围和 IP 白名单按工具生效，判决可进决策日志（这是我们自己发的密钥，不是 MCP 规范里的 OAuth 授权）。另外，这三道锁管的是「这把密钥能做什么」，不是「能做多少」：2026-09-16 新纳入的六个接口仍按来源 IP 限流、仍不计入任何人的月额度，不带密钥调它们，和以前一模一样。Agent 凭证（x-agent-id + x-agent-secret）是另一套，不受这些限制影响。决策日志默认关闭，持有者自己打开后才记录，可用 GET /api/access-keys/decisions 导出（JSON 或 CSV，整份签名）。

• 403 key_scope_denied — 这次调的接口不在这把密钥的范围里。返回里写明是哪个范围、这把密钥允许哪些。
• 403 key_ip_denied — 请求不是从白名单里的地址发出的。最多 20 条，可写单个地址或网段（CIDR，例如 198.51.100.0/24）；IPv4 与 IPv6 分开算。我们认的是连接真正来自哪里，请求头里自称的 X-Forwarded-For 不算数。
• 200 access.key_rejected = expired — 过了持有者设的过期时间。和被停用是同一个待遇：调用仍然按匿名档服务，但明确告诉你密钥没被认，不会闷声降级让你去自己代码里找 bug。

读设置 / 改设置（用密钥本身认证）

curl "https://oceanalt.com/api/access-keys/settings" -H "authorization: Bearer $OCEANALT_API_KEY"

curl -X POST "https://oceanalt.com/api/access-keys/settings" \
  -H "authorization: Bearer $OCEANALT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"scopes":["screen_address","decide"],"ip_allowlist":["198.51.100.0/24"],"expires_at":"2027-01-01T00:00:00Z"}'

收窄（少给能力组、把白名单收紧、把过期时间提前）凭密钥就能立即生效；放宽（多给能力组、放开或删掉白名单、延后或取消过期）要点一封发到该密钥登记邮箱的确认信，否则偷到密钥的人第一件事就是把限制删掉，这三道锁等于没上。一次请求里只要有一项是放宽，整次改动都等确认。没带的字段保持原样。

在网页上设置 →