visitor@x402card:~$ explain flow

How x402card works

x402card offers two independent x402 flows. A wallet owner can issue and fund a virtual card, or an x402 payer can buy a prepaid Freeland travel eSIM and receive its installation credentials privately.

Last verified against production architecture: 2026-08-18.

The complete flow

  1. Public purchase challenge. An agent POSTs one stable idempotency key to /api/card/purchase and validates the returned exact Base-USDC 402 requirements.
  2. Payer ownership. The agent repeats the same request once with PAYMENT-SIGNATURE. The payer becomes the owner; no bearer session is required for purchase.
  3. Issue economics. The wallet pays exactly 25 USDC. VALUT issues a $25 card, then an idempotent $10 withdrawal returns the platform fee to the master balance, leaving $15 expected.
  4. Private continuation. The payer wallet authenticates afterward to read owner state. Card credentials require a separate fresh signature and are never returned by the purchase route or remote MCP.
  5. Payable URL. The owner creates an order. The returned URL answers with HTTP 402 Payment Required and exact Base-USDC payment requirements.
  6. Settlement. A payer agent signs the payment and retries the same URL. The facilitator verifies and settles it on Base.
  7. Materialization. x402card stores durable settlement evidence exactly once. Ambiguous provider results are not treated as success.
  8. Card funding. A worker uses the pre-funded provider USD float to top up the card. Received Base-USDC remains treasury inventory until operator rebalancing.

The eSIM flow

  1. Choose. Read the live Freeland catalog and select a destination, data allowance, duration, and exact current price.
  2. Prepare. POST the plan id and one stable idempotency key to the public purchase route and inspect its HTTP 402 requirements.
  3. Pay once. Settle the exact quote in native USDC on Base. The x402 payer becomes the owner; no card is required.
  4. Fulfill. Preserve the private order delivery token and poll the same order while the eSIM is allocated.
  5. Install. Retrieve the owner-only ICCID, QR/LPA data, and installation links with a private, non-cacheable response.

Settlement is not the same as card credit

settled

The USDC payment has authoritative settlement evidence.

funding

A separate idempotent provider job is processing the card top-up.

funded

The provider has confirmed the card funding result.

operator review

An ambiguous or delayed state is held for safe review instead of being replayed blindly.

Current payment rail

For machine-readable discovery, see the agent contract, OpenAPI, and the well-known agent descriptor.