# x402card

x402card is a wallet-native crypto card. Wallet signatures authenticate owners. Incoming x402 payments settle USDC on Base and automatically create card-funding jobs.

Agent rule:
- Do not open or browse the human root website for service work.
- Use read-only MCP first: https://api.x402card.org/mcp
- If MCP is unavailable, use the HTTP API contract below.
- MCP never receives wallet or MetaMask authority.

Primary agent docs:
- MCP endpoint: https://api.x402card.org/mcp
- Machine-readable API contract: https://api.x402card.org/api/agent
- OpenAPI: https://api.x402card.org/api/openapi.json
- Well-known agent JSON: https://api.x402card.org/.well-known/agent.json
- Human-readable hidden docs: https://x402card.org/agent.html
- Runtime config: https://api.x402card.org/api/config
- Readiness: https://api.x402card.org/ready
- Install CLI: curl -sSL https://x402card.org/install | sh

API base:
- https://api.x402card.org

CLI:
- x402card mcp
- x402card api
- x402card openapi
- x402card status

Core owner-agent flow:
0. GET /api/config and confirm the requested action is currently enabled.
1. Open the x402card browser terminal with MetaMask.
2. Run `issue`.
3. Manually approve Connect/login if needed and one exact 25 USDC EIP-712 payment.
4. The terminal polls the existing order; rerunning `issue` never creates a second payment.
5. Expect card ACTIVE with $25, then a separate $10 card fee withdrawal and $15 available.

Core payer-agent flow:
1. Request payable_url.
2. Read HTTP 402 and PAYMENT-REQUIRED.
3. Build x402 exact EVM payment on Base USDC.
4. Retry same URL with PAYMENT-SIGNATURE.
5. Read PAYMENT-RESPONSE and JSON funding result.

x402:
- version: 2
- scheme: exact
- network: eip155:8453
- asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- public payable endpoint: GET|POST https://api.x402card.org/pay/:orderId

Constraints:
- No app balance.
- Active card required before order creation.
- Minimum order is currently $25.
- Maximum order is currently $250.
- Public card issuance is currently enabled. Check /api/config and /ready immediately before an issue action.
- Issue payment is exactly 25 USDC; the $10 platform fee is withdrawn from the card, not paid again by the wallet.
- While the fee is pending, the card remains active and reports fee settling; failures report fee under review.
- Never request, export, or store the wallet private key.
- Card funding is automatic after confirmed x402 settlement.
- VALUT card top-up uses pre-funded VALUT float; Base-USDC treasury rebalance is manual.