x402 credit top-up

Crane Ledger supports optional programmatic credit purchases using the x402 payment protocol on Base mainnet (eip155:8453), settled in USDC via EIP-3009 (transferWithAuthorization). This complements Stripe checkout for human-driven flows.

Supported network and asset

Only this USDC token on Base mainnet is accepted for the default configuration. Operators may override the network or token using X402_NETWORK and X402_ASSET_ADDRESS (see below); custom values are not documented here as customer-facing “supported” assets.

For human or card-based top-ups, use Stripe (Billing & credits) instead.

Who is billed

• API identity is still your API key (Authorization: Bearer …). Keys can be scoped to a sub-organization as today.
• Credits are always added to the billing master (root) organization for that key’s hierarchy. The URL must use that master organization id (ORG_… with is_root).
• On-chain payer is whoever signs the x402 payload (shown in credit events as x402_payer when present). The wallet does not replace API keys.

Endpoint

POST /organizations/{master_organization_id}/credits/purchase-x402?credits={n}
Authorization: Bearer {api_key}

• master_organization_id: the root org that holds the credit pool (same id you would use for Stripe credit purchase on the master).
• credits: integer ≥ 1. 1 credit = $0.01 USDC → amount in atomic units is credits × 10_000 (USDC has 6 decimals).

First request (challenge)

Omit the payment signature header. The server responds with 402 Payment Required, a PAYMENT-REQUIRED header (base64 JSON, x402 v2), and a small JSON body describing the challenge.

Second request (settlement)

Retry the same URL and credits value with:

PAYMENT-SIGNATURE: {base64-encoded x402 v2 payment payload}

The server calls the configured facilitator /verify then /settle, credits the master org, and returns 200 OK with a PAYMENT-RESPONSE header (base64 JSON) and a JSON body including transaction_hash and credits_added.

Configuration (server operators)

Agents and MCP

• Use @x402/fetch, @x402/axios, or another x402-aware HTTP client against this REST endpoint for automatic 402 handling.
• The MCP server exposes start_x402_credit_purchase and complete_x402_credit_purchase tools that return raw HTTP status, headers, and body so clients can read PAYMENT-REQUIRED on 402.

Idempotency

Successful settlements are recorded by a hash of the payment payload. Replaying the same PAYMENT-SIGNATURE returns 200 with idempotent: true without double-settling on-chain when the facilitator and row insert cooperate as designed.

• ✨ For LLMs/AI assistants: Read our structured API reference