Mainnet payment readiness

Current public beta status

• Primitive402 is live at https://primitive402.dev.
• Current production network: Base mainnet, eip155:8453.
• Current production asset: Base mainnet USDC.
• Current proof: paid production x402 calls have succeeded end to end.
• Staging proof: Base mainnet x402 succeeded via the CDP facilitator earlier.
• Production mainnet billing beta is enabled.
• /status.json is the source of truth for live production billing mode.
• Operational, support, accounting, and rollback readiness still matter during beta.

Facilitator options

CDP's x402 facilitator is the production facilitator for the mainnet beta. Coinbase's current x402 docs describe CDP as the recommended testnet and mainnet facilitator, with hosted verification and settlement, CDP API-key authentication, compliance screening, and published pricing.

The earlier Primitive402 public beta used the signup-free https://x402.org/facilitator path for Base Sepolia testing. Official x402 network support docs describe x402.org as testnet-only.

CDP's production endpoint is https://api.cdp.coinbase.com/platform/v2/x402. CDP network support lists Base mainnet eip155:8453, Base Sepolia eip155:84532, Polygon, Arbitrum, World, World Sepolia, Solana, and Solana Devnet. Primitive402 production mainnet billing beta uses Base mainnet USDC.

Other facilitators may exist. Evaluate supported networks and assets, 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="https://api.cdp.coinbase.com/platform/v2/x402"
X402_EVM_PAY_TO="<production receiving wallet>"
X402_NETWORK="eip155:8453"
PUBLIC_BASE_URL="https://primitive402.dev"
CORS_ORIGIN="https://primitive402.dev"
PROOF_PUBLIC_BASE_URL="https://primitive402.dev/proofs"
ADMIN_METRICS_TOKEN="<secret>"
CDP_API_KEY_ID="<secret>"
CDP_API_KEY_SECRET="<secret>"

CDP credentials are only used when X402_FACILITATOR_URL points at the CDP x402 facilitator. They belong only in Railway or equivalent environment secret storage. Do not put real values in docs.

Production mainnet values are live beta values now. Do not put real keys, wallet secrets, or admin tokens in docs or templates.

Current runtime config audit

• X402_ENABLED is read in apps/api/src/env.ts and consumed by apps/api/src/x402/middleware.ts.
• X402_FACILITATOR_URL is read from env and passed to HTTPFacilitatorClient.
• X402_NETWORK is used in route payment metadata and the registered ExactEvmScheme.
• X402_EVM_PAY_TO is checked for placeholder values and included as each route's accepts.payTo.
• Payment-required resource URLs are generated by trimming PUBLIC_BASE_URL and appending each /x402/v1/* path.
• Verify and settle calls are made by @x402/express through @x402/core's HTTPFacilitatorClient.
• The installed @x402/core@2.11.0 package supports createAuthHeaders for authenticated facilitator calls.
• Primitive402 wires createAuthHeaders for CDP facilitator URLs when both CDP_API_KEY_ID and CDP_API_KEY_SECRET are present.
• CDP Bearer JWTs are generated with @coinbase/cdp-sdk/auth; the raw CDP secret is not used as the bearer token.

Mainnet preflight

X402_ENABLED=true \
X402_NETWORK=eip155:8453 \
X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402 \
X402_EVM_PAY_TO=0x0000000000000000000000000000000000000001 \
PUBLIC_BASE_URL=https://primitive402.dev \
PROOF_PUBLIC_BASE_URL=https://primitive402.dev/proofs \
ADMIN_METRICS_TOKEN=placeholder-admin-token \
CDP_API_KEY_ID=placeholder-cdp-key-id \
CDP_API_KEY_SECRET=placeholder-cdp-key-secret \
pnpm x402:mainnet-preflight

The preflight is safe and non-mutating. It validates candidate configuration, never sends payments, never makes paid requests, never reads private keys, and prints only redacted CDP credential status.

Wallet and payTo guidance

• Use a production receiving wallet separate from developer, buyer, and testnet wallets.
• Prefer 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.
• Confirm the payTo address can receive Base mainnet USDC and is monitored by finance/support.
• Use a small-value mainnet test before public launch and reconcile the transaction against facilitator and application records.

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.
• Track paid route, price, network, asset, settlement status, transaction hash, payTo, payer when available, request id, route, response status, and whether paidX402Calls incremented.
• Alert on facilitator verification failures, settlement failures, missing PAYMENT-RESPONSE, unexpected non-2xx paid retries, and mismatches between facilitator records and usage logs.

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.
• If settlement succeeds but the route later returns a non-2xx response, Primitive402 may need a manual refund/credit process because the current runtime intentionally does not auto-refund.
• Duplicate payments, buyer mistakes, facilitator delays, chain congestion, unsupported wallets, and stale payment requirements need support playbooks before launch.

Operational risks

• CDP facilitator outage, latency, authentication failure, or rate limiting can block paid route access.
• CDP API keys become production secrets and must be stored only in the host secret manager.
• Base mainnet gas, USDC contract handling, chain congestion, or wallet incompatibility can affect buyer success.
• Incorrect X402_NETWORK, asset, payTo, resource URL, or price metadata can cause failed payments or unreconciled settlements.
• Bazaar/discovery indexing may require successful settlement activity through the relevant production facilitator path and may not update immediately.
• Real payments introduce refund, tax, accounting, abuse, sanctions/KYT, support, and incident-response obligations.

Before mainnet launch checklist

This checklist remains as launch and rollback guidance. Staging mainnet proof happened earlier; production mainnet billing beta is now enabled after production verification.

1. Re-check CDP facilitator docs and confirm production endpoint, auth requirements, pricing, and network support.
2. Confirm Base mainnet eip155:8453 and Base mainnet USDC are the approved first production network/asset.
3. Decide whether Primitive402 will use CDP facilitator only or keep a fallback facilitator option.
4. Implement CDP facilitator authentication in a separate reviewed task if required by the selected SDK/client path.
5. Choose the production receiving wallet or multisig and document owner, recovery, rotation, and monitoring process.
6. Confirm payTo receives Base mainnet USDC and is not a developer/testnet wallet.
7. Define refund, credit, duplicate-payment, failed-call, and dispute support policy.
8. Define accounting export fields and reconciliation cadence.
9. Configure production env vars in the host secret manager only; do not commit secrets.
10. Run unpaid x402 402 checks on staging or a controlled production window.
11. Run one paid Base mainnet test with the smallest practical amount.
12. Verify paid 2xx response and PAYMENT-RESPONSE.
13. Verify paidX402Calls increments only for successful settled paid 2xx tool executions.
14. Verify payment-required resource URL uses https://primitive402.dev.
15. Verify discovery readiness, release audit, admin metrics, and logs.
16. Update public docs and support docs from testnet status to production/mainnet beta status.
17. Announce mainnet payment beta only after successful testing and support/accounting review.

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.

Additional repository docs: docs/deployment/production-x402.md and docs/payments/mainnet-smoke-test.md.