# x402card purchase contracts for AI agents This is the canonical operational guide for an agent issuing or topping up a wallet-owned virtual card, or buying a Freeland prepaid eSIM through x402. ## Goal Execute one explicitly approved purchase with exact terms, bind ownership to the x402 payer, recover ambiguous responses with one stable idempotency key, wait for product-specific fulfillment, and return sensitive credentials only through the owner-private channel. ## Discovery - Service metadata: - API catalog: - Virtual-card discovery contract: - Direct virtual-card purchase: `POST https://api.x402card.org/api/card/purchase` - Card top-up discovery contract: - Direct card top-up: `POST https://api.x402card.org/api/card/topup` - Live plan catalog: - eSIM discovery contract: - Direct x402 purchase: `POST https://api.x402card.org/api/esim/purchase` - Agent contract: - OpenAPI: - Runtime config: - eSIM readiness: - Read-only remote MCP: Runtime config and the returned 402 requirements are authoritative. For eSIMs, the live catalog is also authoritative. Do not use cached price or availability. ## Virtual-card sequence 1. **Discover** — read the card discovery contract and runtime config. Confirm public issuance and provider gates are available. 2. **Approve economics** — show the exact fixed terms before payment: 25 USDC paid, $25 initial card value, $10 platform fee, $15 expected available after fee settlement. 3. **Prepare** — generate one stable idempotency key and POST `{ idempotencyKey }` to `/api/card/purchase` without a payment header. This does not charge the wallet. 4. **Inspect HTTP 402** — require x402 version 2, scheme `exact`, network `eip155:8453`, native Base USDC, amount `25000000`, the expected payee, and resource `/api/card/purchase`. 5. **Commit once** — repeat the same body once with `PAYMENT-SIGNATURE`. The payer becomes the owner and issuance begins asynchronously. 6. **Recover safely** — after an ambiguous paid response, repeat only the same body and key. Require `replayed: true`; do not create a replacement payment. 7. **Continue privately** — authenticate the payer wallet to list cards and read status/balance. Reveal credentials only after a fresh owner signature and never put PAN/CVV into shared logs, public artifacts, remote MCP, or model context. Settlement is not active-card proof. Treat the operation as pending until the card provider reports active; platform-fee settlement is a separate state. ## Card top-up sequence 1. **Discover** — require an active card, then read the top-up discovery contract and runtime config. 2. **Approve economics** — show the exact gross amount, load fee, and expected card credit. Current limits are 25–250 USDC and the current load fee is 2%; live config and the returned 402 are authoritative. 3. **Prepare** — generate one stable idempotency key and POST `{ amountUsdCents, idempotencyKey }` to `/api/card/topup` without a payment header. This does not charge the wallet. 4. **Inspect HTTP 402** — require x402 version 2, exact Base USDC, expected payee, resource `/api/card/topup`, and atomic amount `amountUsdCents * 10000`. 5. **Commit once** — repeat the same body once with `PAYMENT-SIGNATURE`. The payer must own the active card. 6. **Recover safely** — after an ambiguous paid response, repeat only the same body and key. Require `replayed: true`; never authorize a replacement payment. 7. **Wait for credit** — settlement queues a funding job. Poll the same owner order until `funded`, a typed failure, or `operator_review`; do not claim the card balance changed before provider confirmation. ## eSIM purchase sequence 1. **Discover** — read runtime config and the live plan catalog. Filter by the requested destination and constraints. 2. **Understand** — inspect the selected plan's data allowance, duration, coverage, and exact public price. 3. **Select** — present the selected plan and exact quote to the user before any value-changing action. 4. **Prepare** — generate one stable idempotency key and POST `{ planId, idempotencyKey }` to `/api/esim/purchase` without a payment header. This does not charge the wallet. 5. **Inspect HTTP 402** — require x402 version 2, scheme `exact`, network `eip155:8453`, native Base USDC, the selected plan amount, and resource `/api/esim/purchase`. 6. **Commit once** — sign the exact requirements and repeat the same POST once with `PAYMENT-SIGNATURE`. The payer becomes the owner. 7. **Continue** — preserve the returned `orderId` and private `delivery.token`. Poll the owner order with `X-Esim-Delivery-Token`; payment-only wallets do not need `personal_sign`. 8. **Recover safely** — if the paid response is lost, repeat the same purchase body with the same idempotency key. Require `replayed: true`; the server verifies payer authority and must not settle a second transfer. 9. **Retrieve result** — after `fulfilled`, call the credentials endpoint with the same delivery header and return the QR code, LPA activation string, ICCID, and installation links privately. Wallet-signature authentication remains a fallback. 10. **Verify** — confirm the response is `no-store, private`. An invalid token or non-owner session must not reveal the order or its credentials. Use the exact request and response schemas in the live Agent Contract or OpenAPI. Do not guess route bodies from this narrative. ## State and error handling - `awaiting_payment`: the order exists but no confirmed settlement is attached. - settlement in progress or ambiguous: poll the same order; do not submit a second payment. - fulfillment in progress: continue polling the same order. - `fulfilled`: retrieve credentials through the owner endpoint. - `failed` or `expired`: stop and report the typed status and safe error. Do not compensate, refund, reorder, or retry without a new explicit user decision. ## Safety constraints - Never request, export, transmit, or store a seed phrase or private key. - Remote MCP is read-only discovery. It cannot sign or pay and must not receive wallet authority. - The payer becomes the owner. For eSIM, treat `delivery.token` like the QR itself. For cards, require fresh owner authentication before credential reveal. - Card top-up is owner-only: the x402 payer must own the active card being funded. - Submit at most one payment for an order attempt. - Treat the live catalog and returned payment requirements as authoritative. - Do not expose card credentials, supplier identifiers, wholesale cost, provider credentials, or installation credentials to a non-owner. - Do not put QR or LPA credentials into shared logs, public artifacts, analytics, or caches. ## Payment profile - Protocol: x402 version 2 - Scheme: `exact` - Network: Base mainnet, `eip155:8453` - Asset: native USDC, `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` - Challenge header: `PAYMENT-REQUIRED` - Payment header: `PAYMENT-SIGNATURE` - Settlement response header: `PAYMENT-RESPONSE` Read current policy and feature availability from immediately before purchase.