Payment planning

Mainnet payment readiness

A production payment launch plan for Primitive402 x402 routes. Mainnet billing is not enabled yet.

Current public beta status

  • Primitive402 is live at https://primitive402.dev.
  • Current network: Base Sepolia, eip155:84532.
  • Current asset: Base Sepolia testnet USDC.
  • Current proof: paid x402 testnet calls have succeeded end to end.
  • Production/mainnet billing is not enabled yet.
  • Mainnet readiness is a separate launch step, not an environment-variable flip.

Facilitator options

CDP's x402 facilitator is the recommended production path to evaluate first. Coinbase's current x402 docs describe CDP as the recommended testnet and mainnet facilitator, with support for ERC-20 payments on Base, Polygon, Arbitrum, World, and Solana.

The current Primitive402 public beta uses the signup-free https://x402.org/facilitator path for Base Sepolia testing. Treat that facilitator as testnet-only unless its provider documentation says otherwise.

Other facilitators may exist. Evaluate supported networks, uptime/SLA, cost, settlement reliability, documentation quality, ecosystem/discovery support, mainnet support, and security posture before changing runtime config.

Mainnet environment checklist

X402_ENABLED="true"
X402_FACILITATOR_URL="<production facilitator URL>"
X402_EVM_PAY_TO="<production receiving wallet>"
X402_NETWORK="<mainnet network id, for example eip155:8453 if Base mainnet is selected>"
PUBLIC_BASE_URL="https://primitive402.dev"
CORS_ORIGIN="https://primitive402.dev"
PROOF_PUBLIC_BASE_URL="https://primitive402.dev/proofs"
ADMIN_METRICS_TOKEN="<secret>"

Do not change X402_NETWORK from eip155:84532 until a deliberate mainnet launch task is approved and tested. Do not put real keys, wallet secrets, or admin tokens in docs or templates.

Wallet and payTo guidance

  • Use a production receiving wallet separate from developer, buyer, and testnet wallets.
  • Consider a dedicated business wallet or multisig.
  • Railway only needs the public payTo address.
  • Never store the receiving wallet private key in Railway.
  • Buyer private keys are never needed on the Primitive402 server.
  • Do not reuse the testnet buyer wallet for production.

Accounting and logging

Production launch needs reconciliation between onchain settlement, facilitator records, and Primitive402 ApiCall logs.

  • Track payment transaction hashes and payer wallet addresses where available.
  • Use paidX402Calls for successful settled paid 2xx executions.
  • Non-2xx paid retries are not counted as paidX402Calls in metrics.
  • The current beta does not attempt automatic refunds.
  • Define export/reporting needs for finance, support, and incident review.
  • Complete tax and accounting review before accepting real revenue.

Charge policy caveats

  • HTTP 402 Payment Required challenges are not charged.
  • Successful paid 2xx responses count as paid tool executions.
  • Non-2xx paid retries are not counted as paidX402Calls in metrics.
  • The current beta does not attempt automatic refunds.
  • Low-confidence 200 responses may still be chargeable because they are valid structured analysis results.
  • Production refund, credit, support, and dispute policies need a final business decision.

Legal, compliance, and tax notes

This is not legal, tax, accounting, or compliance advice. Mainnet payments may create accounting or tax obligations. Review privacy, terms, acceptable-use, security, public status language, jurisdictions, KYC, sanctions, restricted-use policies, support process, and dispute handling before launch. Do not claim compliance is solved until qualified review is complete.

Launch checklist

  1. Choose the production facilitator.
  2. Verify selected network and asset support.
  3. Choose the production receiving wallet or multisig.
  4. Configure production env vars in the host secret manager.
  5. Run unpaid x402 402 checks.
  6. Run one paid mainnet test with the smallest practical amount.
  7. Verify paid 2xx response.
  8. Verify paidX402Calls increments.
  9. Verify payment-required resource URL uses https://primitive402.dev.
  10. Verify discovery readiness and admin metrics.
  11. Verify logs do not expose secrets.
  12. Update docs from testnet status to production/mainnet beta status.
  13. Announce mainnet payment beta only after successful testing.

Rollback checklist

  • Set X402_ENABLED=false or revert to known testnet config if needed.
  • Revert facilitator URL, network, and payTo.
  • Communicate status on /status or public docs.
  • Preserve logs, facilitator records, and transaction references for debugging.
  • Rotate any exposed secrets immediately if leakage occurs.

Repository doc

Markdown source: docs/payments/mainnet-readiness.md.

x402 docs Paid x402 test guide Discovery readiness Docs home