x402 Integration Guide

When your organization's request quota is exceeded, the 1claw API can return 402 Payment Required with an x402-compliant body. You can pay for overages on-chain (Base, USDC) and retry the request with an X-PAYMENT header so your agent can continue without prepaid credits.

This guide covers the 402 response format, how to obtain and send a payment proof, and a minimal code example.

When you get 402

• Authenticated requests over quota: Your tier's monthly request limit is exhausted and your org's overage method is set to x402 (or you have no prepaid credits).
• Unauthenticated requests on paid routes: Some endpoints require payment when no valid Bearer token is present; the API returns 402 so clients can pay and retry.

Toggle overage method in Settings → Billing or via PATCH /v1/billing/overage-method with {"method": "x402"}.

402 response format

The response body follows the x402 spec and is used by the x402scan marketplace and compatible wallets:

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "1500",
      "resource": "https://api.1claw.xyz/v1/vaults/{vault_id}/secrets/{path}",
      "payTo": "0x...",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "description": "read_secret",
      "mimeType": "application/json"
    }
  ],
  "description": "read_secret"
}

Field	Meaning
accepts[].maxAmountRequired	Amount in atomic units (USDC on Base has 6 decimals). Pay this amount (or the exact scheme amount) to the payTo address.
accepts[].resource	Full URL of the request that triggered 402. Retry this URL with the X-PAYMENT header after paying.
accepts[].payTo	Recipient address (1claw's receiving address on Base).
accepts[].asset	USDC on Base mainnet contract address.
accepts[].network	Chain: eip155:8453 = Base.

Pay and retry flow

1. Receive 402 — Your client gets 402 Payment Required and parses the JSON body.
2. Pay on-chain — Transfer the required USDC (atomic units) to payTo on Base, or use an x402-compatible wallet/SDK that produces a payment proof.
3. Obtain payment proof — The proof is typically a signed message or transaction reference that the x402 facilitator can verify. 1claw uses the Coinbase CDP facilitator by default; the facilitator verifies the payment and returns a proof token.
4. Retry with header — Send the same request again with header X-PAYMENT: <proof> (the value the facilitator gives you after verifying the payment).
5. API processes request — The middleware verifies the proof with the facilitator, then allows the request through; after a successful response, the backend settles the payment with the facilitator.

Replay protection: each payment proof is tied to the resource URL and amount; duplicate proofs are rejected.

Example: curl (manual)

After receiving 402, you would normally use an x402 client library to pay and get the proof. For illustration, once you have a proof string (e.g. from a facilitator or wallet):

# First request — may return 402 if over quota
RESP=$(curl -s -w "\n%{http_code}" -X GET \
  "https://api.1claw.xyz/v1/vaults/$VAULT_ID/secrets/my-key" \
  -H "Authorization: Bearer $AGENT_TOKEN")

HTTP_CODE=$(echo "$RESP" | tail -n1)
BODY=$(echo "$RESP" | sed '$d')

if [ "$HTTP_CODE" = "402" ]; then
  # Parse BODY for accepts[0].resource, maxAmountRequired, payTo, asset
  # Pay on Base (USDC) to payTo, then get X-PAYMENT proof from facilitator
  # Retry with proof:
  curl -X GET "https://api.1claw.xyz/v1/vaults/$VAULT_ID/secrets/my-key" \
    -H "Authorization: Bearer $AGENT_TOKEN" \
    -H "X-PAYMENT: <proof-from-facilitator>"
fi

Example: TypeScript (agent with retry)

const BASE = "https://api.1claw.xyz";

async function getSecretWithX402(
  vaultId: string,
  path: string,
  agentToken: string,
  payWithX402: (amountAtomic: string, payTo: string, resource: string) => Promise<string>
): Promise<unknown> {
  const url = `${BASE}/v1/vaults/${vaultId}/secrets/${encodeURIComponent(path)}`;
  const headers: Record<string, string> = {
    Authorization: `Bearer ${agentToken}`,
    "Content-Type": "application/json",
  };

  let res = await fetch(url, { headers });
  if (res.status === 402) {
    const body = await res.json();
    const accept = body.accepts?.[0];
    if (!accept) throw new Error("402 response missing accepts");
    const proof = await payWithX402(
      accept.maxAmountRequired,
      accept.payTo,
      accept.resource
    );
    headers["X-PAYMENT"] = proof;
    res = await fetch(url, { headers });
  }
  if (!res.ok) throw new Error(`API ${res.status}: ${await res.text()}`);
  return res.json();
}

// payWithX402: use an x402 client or CDP facilitator to pay on Base and return proof.
// Example stub — replace with real payment flow (e.g. @coinbase/sdk, or facilitator API).
async function payWithX402(
  _amountAtomic: string,
  _payTo: string,
  _resource: string
): Promise<string> {
  // 1. Transfer USDC to payTo on Base (amountAtomic = 6-decimal units).
  // 2. Call facilitator verify endpoint with payment details; get proof.
  // 3. Return proof string for X-PAYMENT header.
  throw new Error("Implement: pay on Base, then get proof from facilitator");
}

Facilitator (CDP)

1claw uses the Coinbase CDP x402 facilitator by default. The API sends the payment proof to the facilitator's verify endpoint before allowing the request, and to settle after a successful response. Your agent does not call the facilitator directly unless you implement a custom payment flow; most integrations use a wallet or SDK that speaks x402 and produces the proof the facilitator expects.

For more on the protocol and marketplace: x402.org, docs.g402.ai.

Summary

Step	Action
1	Request fails with 402; parse accepts[0] for maxAmountRequired, payTo, resource, asset.
2	Pay the required USDC (atomic units) on Base to payTo.
3	Obtain an x402 payment proof (e.g. via facilitator or x402-capable wallet).
4	Retry the same request URL with header X-PAYMENT: <proof>.
5	API verifies proof, processes request, then settles payment.

See Billing & Usage for subscription tiers, prepaid credits (alternative to x402), and overage pricing.