A pre-payment risk check for your agent or system

Idempotency-Key: retry payments safely

When the network drops, your agent cannot tell whether a payment request ran. Send an Idempotency-Key header with the POST /api/pay payment call (and with rotate), and keep the same key, the same nonce and the same body when you retry: within 24 hours we return the original response, nothing runs twice, and the retry is not recorded as a replay attack. Semantics follow the IETF draft 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 — A retry with the same key, body and credential: the original status code and body, unchanged.
• 422 idempotency_key_reused — The same key was used with a different body (for example, a new nonce on retry). Nothing ran.
• 409 idempotency_request_in_progress — The original request is still running. This is concurrency, not a replay attack, and is not recorded as a threat. Resend unchanged after retry-after seconds.
• 400 idempotency_key_invalid — The key must be 1–255 printable ASCII characters; a UUID is recommended.

A replay must present the same x-agent-secret as the original, so someone who only knows the key cannot read your response. Calls without the header behave exactly as before. For a new payment, use a new key and a new nonce.

Webhook signatures

If you configure a webhook in the console (/keys), we POST a JSON body to it when one of your agent's payments is blocked. Every message is signed per the Standard Webhooks specification, so your system can confirm it came from OceanAlt, was not altered, and is not an old message replayed.

• webhook-id — Unique message id; unchanged across retries of the same message, so deduplicate on it.
• webhook-timestamp — Send time in Unix seconds. Reject anything more than 5 minutes from your current time.
• webhook-signature — v1,<base64>: HMAC-SHA256 over webhook-id.webhook-timestamp.raw-body, keyed with the base64-decoded bytes after whsec_. For 24 hours after a rotation there are two signatures separated by a space; accept if either matches.

Verify in Node (no dependencies; this exact snippet runs in our own test suite):

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);
// });

Or use any Standard Webhooks library (standardwebhooks.com), passing it the whsec_ secret from the console.

The signing secret is generated in the console, shown once, and can be rotated at any time. Your endpoint should answer 2xx within about 5 seconds; failed deliveries are retried after 1 min, 5 min, 30 min and 2 h, up to 5 attempts in total, and redirects are not followed. Each attempt's status code, duration and error summary appear under Recent deliveries in the console for 30 days.

Locking a key down: scopes, IP allowlist, expiry

A key has no limits by default, and keys already in use are unaffected. Its holder can add limits, and those limits decide how much can be done with the key if it ever leaks.

Scopes: which endpoints the key may call

• screen_address — Address screening: one payee address (the ?on= point-in-time lookup does not read keys and is unaffected)GET /api/risk
• screen_endpoint — Endpoint screening: is this payment URL a known phishing hostGET /api/endpoint
• decide — Pre-payment decision: allow / review / decline (including the optional intent check)GET /api/decide · POST /api/decide
• payee_decide — Payee-side decision: accept this incoming payment or notPOST /api/payee/decide
• batch_screen — Batch screening: up to 25 addresses in one call (the paid POST /api/x402/batch authenticates by payment and does not read keys)POST /api/risk/batch
• trace_funds — Fund-flow tracing: multi-hop taint trace and counterparty flow analysis (two views of the same upstream data, kept in one scope)GET /api/risk/trace · GET /api/risk/flow
• evidence_bundle — Evidence bundle: one address's Ed25519-signed evidence bundleGET /api/evidence/bundle
• intent_check — Intent check: what this calldata will actually do, against the payment you declaredPOST /api/intent/check
• baseline_lookup — Control-baseline lookup: what controls a counterparty has attested to, before you settleGET /api/baseline/lookup

Everything not listed above does not read a key and is rate limited per source IP: the x402 paid endpoints (paid per call, so they never needed a key), the point-in-time lookup GET /api/risk?on=, and the gateway, fulfillment and registry endpoints. The MCP endpoint POST /api/mcp takes a key optionally: without one every tool works as before; with one, tool calls are rate limited per key, the holder's scopes and IP allowlist apply per tool, and verdicts can go to the decision log (this is our own API key, not the OAuth authorization in the MCP specification). These locks also govern what a key may do, not how much: the six endpoints added on 2026-09-16 are still rate limited per source IP and still count towards nobody's monthly allowance: calling them without a key behaves exactly as it did before. Agent credentials (x-agent-id + x-agent-secret) are a separate mechanism and are unaffected. The decision log is off by default and records nothing until the holder switches it on; export it with GET /api/access-keys/decisions (JSON or CSV, signed).

• 403 key_scope_denied — The endpoint is outside this key's scopes. The response says which scope was refused and which ones the key allows.
• 403 key_ip_denied — The call did not come from the key's IP allowlist, up to 20 entries, each an address or a CIDR range (e.g. 198.51.100.0/24), with IPv4 and IPv6 matched separately. We use where the connection actually came from; an X-Forwarded-For header the caller sets itself does not count.
• 200 access.key_rejected = expired — Past the expiry its holder set. Treated exactly like a revoked key: the call is still served, at the anonymous level, and the response says the key was not accepted, never a silent downgrade that sends you hunting through your own code.

Read and change the settings (authenticated with the key itself)

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"}'

Tightening applies immediately with the key alone: fewer scopes, a narrower allowlist, an earlier expiry. Loosening needs a confirmation link emailed to the address the key was issued to: more scopes, a wider or removed allowlist, a later or removed expiry. Otherwise anyone who stole the key would simply remove its limits. If any part of a request loosens something, the whole change waits. Fields you leave out keep their current value.

Set it up in the browser →