Issue or top up a card, or buy an eSIM over x402.

01 · discover

Start from live contracts.

02 · issue card

Direct virtual-card sequence.

1. Approve exact economics. The wallet pays 25 USDC; the card starts at $25; the separate $10 platform fee leaves $15 expected available.
2. Prepare idempotently. POST {"idempotencyKey":"..."} to /api/card/purchase without a payment header.
3. Validate before signing. Require x402 v2, exact, Base eip155:8453, native USDC, amount 25000000, expected payee, and resource /api/card/purchase.
4. Submit once. Repeat the same body once with PAYMENT-SIGNATURE. The payer becomes the owner and issuance is queued.
5. Recover the same operation. After an ambiguous response, reuse the same body and key; require replayed: true.
6. Authenticate only for owner reads. List cards and read status/balance with the payer wallet. Reveal PAN/CVV only after a fresh owner signature and outside model context.

POST https://api.x402card.org/api/card/purchase           # 402
POST https://api.x402card.org/api/card/purchase           # same body + PAYMENT-SIGNATURE, once
POST https://api.x402card.org/api/auth/challenge          # owner continuation
GET  https://api.x402card.org/api/cards                   # owner bearer session

A settled purchase is not an active card. Provider issuance and platform-fee settlement are separate states.

03 · top up card

Direct active-card funding sequence.

1. Require an active owner card. Read live config and the top-up discovery contract before proposing a payment.
2. Approve exact economics. Show gross Base-USDC payment, current load fee, and expected card credit. Current bounds are 25–250 USDC and the current load fee is 2%.
3. Prepare idempotently. POST {"amountUsdCents":5000,"idempotencyKey":"..."} to /api/card/topup without a payment header.
4. Validate before signing. Require x402 v2, exact, Base eip155:8453, native USDC, expected payee, dynamic atomic amount, and resource /api/card/topup.
5. Submit once. Repeat the same body once with PAYMENT-SIGNATURE. The payer must own the active card.
6. Recover the same operation. After an ambiguous response, reuse the same body and key; require replayed: true.
7. Wait for provider credit. Poll the same owner order. Settlement queues funding but does not prove that the card balance changed.

POST https://api.x402card.org/api/card/topup             # 402
POST https://api.x402card.org/api/card/topup             # same body + PAYMENT-SIGNATURE, once
GET  https://api.x402card.org/api/orders/{orderId}       # owner bearer session

Report success only when the funding job reaches funded. Retrying, funding, and operator review are not card-credit proof.

04 · buy eSIM

eSIM customer jobs and side effects.

05 · continue eSIM

Exact eSIM purchase sequence.

1. Inspect runtime. Read config, eSIM readiness, and the current plan object. Treat the returned quote as authoritative for this attempt.
2. Prepare idempotently. POST {"planId":"...","idempotencyKey":"..."} to /api/esim/purchase without a payment header.
3. Validate before signing. Require x402 version 2, scheme exact, network eip155:8453, native Base USDC, resource /api/esim/purchase, expected payee, and quoted atomic amount.
4. Submit once. Repeat the same POST and body with one PAYMENT-SIGNATURE. This is the only settlement.
5. Preserve private access. Save the returned order id and delivery.token. Never log, publish, index, or send the token to another user.
6. Reconcile by reading. Poll with X-Esim-Delivery-Token. If the paid response is lost, repeat only the same purchase body and idempotency key; require replayed: true.
7. Deliver privately. When fulfilled, request credentials with the same delivery header and pass QR/LPA directly to the user. Wallet-signature authentication is an optional fallback.

GET  https://api.x402card.org/api/esim/plans?countryCode=ID
POST https://api.x402card.org/api/esim/purchase           # 402
POST https://api.x402card.org/api/esim/purchase           # same body + PAYMENT-SIGNATURE, once
GET  https://api.x402card.org/api/esim/orders/{orderId}   # X-Esim-Delivery-Token
GET  https://api.x402card.org/api/esim/orders/{orderId}/credentials # same header

06 · verify

Fail closed around money and secrets.

The remote MCP intentionally has no wallet authority and does not create or pay orders. Use it to discover contracts; use an owner-controlled signer and the HTTP/x402 sequence above to purchase.