Billing

x402 ledger top-up (agent door)

The wallet rail for Shroud (Shroud AI plan). Without X-PAYMENT the response is a 402 quote (x402Version, accepts[] with payTo, maxAmountRequired, resource) for amount_usd (default $1) of USDC on Base. With a signed EIP-3009 X-PAYMENT the facilitator verifies it, the proof is claimed once, the payer wallet's org ledger is credited in micro-USD, and the facilitator settles.

Payment is the account. An unknown wallet's first settled top-up provisions a shadow org, one Shroud-enabled agent and one sk-shroud-v1 router key keyed on the wallet (returned once as router_key), after screening the wallet against the OFAC SDN list (fails closed when the list is missing or stale) and the caller's region against the custody geofence. Same wallet = same org on every later top-up. The response always carries a ≤60 s access_token for the wallet's agent so the gateway can serve the paid request immediately. The Shroud gateway drives this for Authorization: Bearer x402 requests and relays the quote or the result.

post/v1/x402/topup

Request

  • Base URL: https://api.1claw.co
  • URL: https://api.1claw.co/v1/x402/topup
  • Auth: none required

Headers

X-PAYMENTstring

Base64 x402 payment payload (EIP-3009 USDC authorization on Base)

Request body

amount_usdinteger

Whole dollars to add to the ledger (default 1)

Response

Credited

walletstring required

Payer address (lower-case)

org_idstring uuid required
agent_idstring uuid required
credited_micro_usdinteger required
balance_micro_usdinteger required
balance_usdstring required
router_keystring

Present only on the top-up that provisioned the account (or re-minted a lost key). Shown once.

access_tokenstring required

A ≤60 s agent token for the wallet's agent (carries the router_key claim)

expires_ininteger required
base_urlstring required

The Shroud gateway

provisionedboolean required

True when this top-up created the account

Changes

No recorded changes to this operation across all 1 revision of this API.