給你的 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 · GET /api/monitor · POST /api/mandate/check
• 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 · POST /api/payment-request
• 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"}'

收窄（少給能力組、把白名單收緊、把過期時間提前）憑密鑰就能立即生效；放寬（多給能力組、放開或刪掉白名單、延後或取消過期）要點一封發到該密鑰登記郵箱的確認信，否則偷到密鑰的人第一件事就是把限制刪掉，這三道鎖等於沒上。一次請求裡只要有一項是放寬，整次改動都等確認。沒帶的字段保持原樣。

在網頁上設置 →