x402 micropayments for overages

When your org is over its monthly request quota and the overage method is x402, payable endpoints return 402 Payment Required. You pay on Base with USDC and retry with an X-PAYMENT header.

• 402 body is spec-compliant with an accepts[] array
• accepts[] uses scheme exact, network eip155:8453, asset USDC on Base
• Amounts are atomic units (USDC has 6 decimals, so 1500 is 0.0015 USDC)
• 1Claw settles through the Coinbase CDP facilitator on Base (chain 8453)

1. 1

   Set your credentials. Replace with your 1ck_ key from Settings → API Keys. Use your vault UUID from 1claw vault list or Foundations.

   bash Copy

   export TOKEN=1ck_your_key_here
   export VAULT_ID=your_vault_uuid

2. 2

   Switch the org overage method to x402.

   bash Copy

   curl -X PATCH "https://api.1claw.co/v1/billing/overage-method" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{ "overage_method": "x402" }'

3. 3

   Hit a payable endpoint. When over quota you get a 402 with accepts[].

   bash Copy

   curl -i "https://api.1claw.co/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
     -H "Authorization: Bearer $TOKEN"

4. 4

   Read the 402 accepts[] entry: scheme, network, maxAmountRequired, payTo, and asset.

   json Copy

   {
     "x402Version": 1,
     "accepts": [{
       "scheme": "exact",
       "network": "eip155:8453",
       "maxAmountRequired": "1500",
       "payTo": "0x...",
       "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
     }]
   }

5. 5

   Clone the x402 example from github.com/1clawAI/1claw-examples (or see the retry pattern below). Generate an EOA key, fund it with USDC on Base, and let an x402 client sign the payment and retry.

   bash Copy

   git clone https://github.com/1clawAI/1claw-examples.git
   cd 1claw-examples/x402-payments
   npm install && cp .env.example .env
   # set X402_PRIVATE_KEY, TOKEN, VAULT_ID
   npm start

6. 6

   Alternatively, retry the request inline with an X-PAYMENT header containing the payment proof from your x402 client.

   bash Copy

   curl -i "https://api.1claw.co/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-PAYMENT: <payment-proof-from-x402-client>"

You can now take a 402, sign a USDC payment on Base, and retry the same request with X-PAYMENT to get a 200.

Where this goes wrong in practice. x402 puts payment authorisation in an automated path, so the checks that a human would perform implicitly must be written down.

• Challenge validation is partially implemented. Amount and network are checked because they are obvious; payTo and the asset contract are the ones an attacker actually controls.
• 402 responses are retried blindly. A retry loop against a priced endpoint spends real money, and the failure looks like a transient network problem in every dashboard you own.
• The asset is matched by symbol. Any token can call itself USDC, so the check has to pin the contract address rather than the name.
• Overage is enabled without a ceiling. Automatic payment removes the friction that used to cap the damage of a runaway loop.