x402 seller (pr402)

Help the user monetize an HTTP API on the pr402 facilitator using the exact rail (SplitVault via pr402) unless they explicitly need sla-escrow (escrow + oracle — different skill path; see oracles Seller Guide).

Pay-per-call vs subscription

If the user wants time-window access, do not apply per-request 402 gates — follow the subscription reference instead.

Two-part integration model

Reference implementation: x402-seller-starter (Rust / TypeScript / Python — separate repo, not inside the x402 hub).

GitHub repos (x402 hub is virtual)

The x402 hub coordinates docs and ships x402-cli only. Clone each project from its own repository:

The on-chain exact rail uses SplitVault (UniversalSettle engine). Program source is not public yet — do not link integrators to a GitHub repo; use facilitator docs and the seller starter.

Facilitator hosts

Default for examples and production integration:

Devnet testing only: https://preview.ipay.sh or https://preview.agent.pay402.me — match facilitator host to the cluster your seller wallet uses.

Confirm solanaNetwork with GET https://ipay.sh/api/v1/facilitator/health (or your chosen host). Never hardcode RPC URLs — read solanaWalletRpcUrl from health/capabilities.

Golden path checklist

Run in order; do not skip Activate before accepting payments.

1. Preview — GET /api/v1/facilitator/sellers/{WALLET}/preview

Read lifecycle.nextStep. If "activate", proceed to step 2.

1. Activate (on-chain) — POST /api/v1/facilitator/sellers/provision-tx with { "wallet", "asset": "USDC" } (or SOL / mint).

Sign the returned base64 bincode VersionedTransaction with the seller wallet and broadcast. statusCode: "ALREADY_PROVISIONED" means done — no tx to sign.

1. Register merchant (optional, discovery) — challenge → sign → register.

Details: [references/onboarding-cli.md](references/onboarding-cli.md)

1. Enroll API routes (optional, discovery) — publish x402-resources.json manifest.

Details: [references/x402-resources-manifest.md](references/x402-resources-manifest.md)

1. Runtime SDK — boot X402SellerSDK, gate paid routes, handle headers.

Details: [references/runtime-sdk.md](references/runtime-sdk.md)

1. Settle — unpaid request → HTTP 402 + enriched body; paid request → direct /settle, then HTTP 200 + PAYMENT-RESPONSE only after success.

x402 v2 headers (runtime)

Critical pr402 rules (not generic x402)

• payTo is a PDA, not the seller's personal wallet. Starters use POST /payment-required/enrich so the facilitator injects vault PDAs — do not hand-derive PDAs in app code.
• One payment asset per merchant wallet on this facilitator. Multi-rail/multi-token → separate seller pubkeys.
• Scheme aliases: sellers may publish v2:solana:exact in accepts[]; verify/settle bodies use wire exact.
• Mint allowlist: if the deployment sets PR402ALLOWEDPAYMENT_MINTS, wrong asset fails at build/settle with an explicit approved-mints message.
• Settle immediately: on Solana, blockhashes expire quickly. Call /settle directly; it verifies before broadcast. Deliver only after success: true. Use /verify only for diagnostics, never as proof of payment.

Language starters

Clone x402-seller-starter and open the subdir matching the user's stack:

Required env (all languages): FACILITATORBASEURL (e.g. https://ipay.sh), MERCHANTWALLET, SELLERPUBLICBASEURL, X402_AMOUNT (USDC microunits as string, e.g. "50000" = 0.05 USDC).

When implementing for the user

1. Prefer adapting the starter structure over inventing a new payment stack, but confirm its payment gate calls /settle directly before production use.
2. Separate onboarding from runtime — CLI/REST onboarding once; SDK calls enrich and direct settle at runtime (no heavy Solana deps in the web server).
3. Call live OpenAPI — GET {facilitator}/openapi.json on the target host before guessing field names.
4. Do not commit keypairs — use env paths; warn if .env contains secrets.
5. Escrow sellers — if the user needs conditional delivery / oracles, stop and route to sla-escrow + oracles workspace; the seller starter is exact-only.
6. Subscription sellers — if the user needs hourly/daily/monthly access windows, use x402-subscription-starter and [references/subscription-exact-rail.md](references/subscription-exact-rail.md); Tier B JWT auth is miralandlabs/subscription-auth (individual account — not miraland-labs), not a new payment rail.

Live documentation

Production facilitator (default):

• https://ipay.sh/agent-integration.md
• https://ipay.sh/quickstart-seller.md
• https://ipay.sh/seller-quick-start.md
• https://ipay.sh/openapi.json

Devnet equivalents live under https://preview.ipay.sh/… when testing on Devnet.

Related hub skills

• pr402 — entry router when integrator role is unclear
• pr402-facilitator — only when editing the Rust facilitator, not when integrating as a seller
• pr402-buyer — when the same project also needs a paying agent client