Guide · Solana · 2026

Ship an x402 API on Solana

This is the buyer-intent guide: how to put HTTP 402 in front of a resource, accept payment proof, and verify or settle on Solana — including the Ship x402 lab path you can run today.

Architecture in four boxes

Resource server — your API; returns 402 or 200
Client / agent — reads requirements, pays, retries
Wallet — signs; keys never go to your server
Optional facilitator — verifies + settles USDC so you do not run full chain infra

Step 1 — Unpaid request returns 402

For a protected route, if there is no payment header, respond with status 402 and a JSON body listing accepts[]: scheme, network, amount, asset, payTo, resource, timeout.

GET /api/premium
→ 402 Payment Required
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "solana",
    "maxAmountRequired": "...",
    "payTo": "<merchant>",
    "asset": "USDC",
    "resource": "/api/premium"
  }]
}

Step 2 — Client pays

Lab / teaching — signed intent (Ship x402 exact-lab scheme)
Production — typically SPL USDC transfer or facilitator payload (see x402-solana / CDP docs)
DIY on-chain SOL — transfer + signature proof (Ship x402 donate endpoint style)

Step 3 — Retry with proof

Same URL, header X-PAYMENT (or stack-specific PAYMENT-SIGNATURE) carrying base64 payment payload.

Step 4 — Verify, reject replays, deliver

Check scheme, amount, resource, signature or on-chain tx
Reject reused nonces / signatures (replay protection)
Return 200 + body; optional payment response header

Lab path on Ship x402 (no mainnet USDC)

Open /app, create a Devnet wallet
Use the x402 Lab tab — or curl /api/x402/lab
Observe 402 → sign → 200; second use of same nonce is rejected

Production checklist

Dedicated RPC (not public rate-limited endpoints alone)
HTTPS everywhere; CSP on the wallet UI
Human/agent consent UI before any signature
Idempotent settlement; durable replay store if you gate real content
Clear pricing pages agents can fetch (and an llms.txt)

Open lab in app Read x402 vs MPP