x402

💸 x402 Monetization Skill

Turn any local HTTP service into a paid service on platform networks (Base + Monad + Robinhood + X Layer; x402 V2 protocol, exact scheme, USDC/USDG via EIP-3009 — buyer pays zero gas), and act as a buyer paying other agents' x402 services with the user's Privy wallet.

Architecture: reverse-proxy sidecar. The gateway (gateway/app.py) sits in front of the user's untouched service. One unified gateway, three billing modes as config presets — the error contract is identical across all modes.

buyer agent ──402/PAYMENT-SIGNATURE──> gateway :840x ──plain HTTP──> user service :port
                     │
               facilitator (verify + settle on Base/Monad/Robinhood/X Layer/Solana) ──USDC/USDG──> user's Privy wallet

Reference files (MUST read before the matching task)

Detailed material lives in skills/x402/references/ — it is part of this skill. Do NOT guess or improvise what these files cover:

Limited-time free promotion (seller quick rules)

For a listed paid marketplace service the owner can open a free window (max 90 days). Full playbook: references/selling.md → Limited-time free promotion.

Agent MUST:

1. Not blind-PUT free-promo from a UI prompt — run P1–P5 self-check first.
2. Remember free = wallet identity + amount 0 verify + no settle/debit, not anonymous and not a free lifetime subscription after the window.
3. On platform gateway: amount-0 challenge and skip settle/debit are built-in.
4. On custom upstream keys (P3/P4) or self-built x402: you MUST patch ACL / force amount="0" / skip settle — see selling.md Step C.
5. Use x402 resource (path) for access isolation — never invent service_id on the wire.
6. After enable: verify free-status, 402 amount=0, free call without settlement, then confirm paid path returns after cancel/expiry.

Buyer tip: if unpaid 402 shows accepts[].amount == "0", sign 0 (no USDC needed); do not force list-price signing during free.

Sell — monetize a service (quick start)

FAC=https://starchild-x402-facilitator.fly.dev
# pay_per_use: verify -> settle on EVERY request (simplest mode)

Platform modes follow the community-gateway billing contract: 402 JSON body with accepts as a list (multi-accepts, one entry per network — the buyer picks one chain per payment), accepts[].pricingModel, facilitator is the single source of truth for "already paid", every settle auto-callbacks community-gateway for records.

Billing mode decision table

⚠️ lifetime/monthly/weekly/quarterly/yearly REQUIRE --facilitator-admin-token (fail-closed at startup). Multi-plan: --plan MODE=PRICE (repeatable). → MUST read references/selling.md BEFORE deploying any of these modes — it has the exact commands, contract details, and template list.

Output includes gateway_port. Expose the GATEWAY port, not the upstream (via preview or community-publish). pay_to defaults to the user's Privy EVM wallet — revenue lands there directly. Registry: /data/workspace/.x402/services.json; per-service config/log/state: /data/workspace/.x402/<name>/.

Networks & facilitators

The platform supports multiple chains. By default a service follows the platform mainnet full set (--networks all, the default) — currently Base + Monad + Robinhood + X Layer + Solana. The 402 challenge returns a multi-accepts list (one entry per chain); the buyer picks one chain per payment. Lock to specific chains with --networks eip155:8453,eip155:143,eip155:4663,eip155:196 (custom).

The platform facilitator handles /verify + /settle on every supported chain; its settler key only pays gas — fund flow is fixed by the buyer's signature and can never touch user funds. Gas/fees are paid by the platform on every chain (ETH on Base, MON on Monad, ETH on Robinhood, OKB on X Layer, SOL on Solana) — never passed to the service provider. Safety: mandatory eth_call simulation before spending gas, per-payer rate limiting, authorization-nonce idempotency. Testnet USDC (Base Sepolia): 0x036CbD53842c5426634e7929541eC2318f3dCF7e, faucet at faucet.circle.com. Prices auto-convert: $0.01 → 10000 atomic USDC units.

Multi-chain config (networks_mode)

Extending the platform with a new chain only requires updating ASSETS + MAINNET_NETWORKS in platform_modes.py (and the facilitator's KNOWN_ASSETS) — every all-configured service picks up the new chain on its next 402, with zero business-table updates.

⚠️ Robinhood USDG note: the USDG contract uses a Diamond proxy with a non-standard EIP-712 domain. The facilitator reads DOMAIN_SEPARATOR() from chain for verification. Buyer-side raw-digest signing is a TODO (see client.py _CHAIN_DOMAIN_SEP_CHAIN_IDS); standard typed-data signing is used for now and works if the on-chain domain matches the metadata.

Historical Base-only configs are migrated once (SQL/config sweep to networks_mode: all); resolve_networks does NOT guess "bare Base means all".

Keepalive (register once per machine)

One watchdog guards ALL x402 gateways (cloudflare-skill pattern: idempotent, prints only on state change → silent scheduled task when healthy):

1. Boot: append to /data/workspace/setup.sh: bash /data/workspace/skills/x402/scripts/keepalive.sh || true
2. Watchdog: scheduled_task(action="schedule", schedule="every 10 minutes", command="bash skills/x402/scripts/keepalive.sh", deliver="origin") — empty output = silent. ⚠️ Use the RELATIVE path (skills/x402/...), never /data/workspace/skills/... — the scheduler's path sanitizer strips workspace/ from absolute commands, mangling them into a nonexistent /data/skills/... and the task fails every run. After registering, verify with get_log that the first execution succeeds.

Gateway down → restarted from its config. Upstream down → reported but NOT restarted (upstream has its own supervisor via previews — don't fight it).

A LISTED paid service must stay reachable 24/7 (idle suspend + auto-update restarts work against this) → read references/selling.md § Always-on availability BEFORE publishing for the update-mode check/flip flow.

Buy — pay other agents' x402 services

Quick Start — preset CLI scripts (use these FIRST, no custom code)

One process per step, ONE JSON object on stdout — no per-call LLM reasoning about balances/signatures/rail selection needed:

Raw client (advanced / custom flows):

Pre-flight FIRST (one round-trip, not serial walls)

Before asking the user to confirm any purchase, run client.payment_preflight(amount_atomic, networks=<the 402's accept networks>) and present ALL blockers together. It checks in one shot: ① signers reachable, ② wallet policy sanity — an ENABLED policy with EMPTY rules is deny-all and rejects every signature (new Privy wallets should be allow-all; if found, propose a policy card and get it signed BEFORE paying), ③ USDC balance per candidate rail (direct RPC). If no rail is funded, offer every option at once — pay from another funded chain, bridge, or fiat-onramp — never a bare "fund the wallet" that leads to the next wall. Never let the user fix funding, then discover a policy block, then a dependency error in three separate round-trips.

Dependencies: the buyer path needs web3>=7. If the machine pins an older web3 (trading bots often pin 6.x), NEVER upgrade it globally — run bash skills/x402/scripts/ensure_env.sh (zero-interaction, idempotent): it creates an isolated .venv-x402 immune to PIP_USER/PYTHONPATH/user-site interference (venv built --without-pip + PYTHONNOUSERSITE=1) and prints the interpreter to use on the last stdout line. payment_preflight detects the version conflict and points here. Do this at setup, not mid-purchase.

Multi-chain selection (buyer receives multiple accepts)

When a service returns 402 with accepts as a list (one entry per network, e.g. Base + Monad + Robinhood + X Layer + Solana), the buyer Agent does NOT need to ask the user which chain to use — chain selection is fully automatic in both paid_request and bazaar_pay. The logic:

1. payment_preflight (run BEFORE confirming): checks USDC balance on every candidate rail and returns funded_rails[]. If multiple rails are funded, the automatic selector picks the best one. If NO rail is funded, present ALL funding options at once (bridge, on-ramp, pay from another chain) — never ask "which chain?" when the answer is "none of them".

2. Automatic rail ranking — balance-aware, Base default (shared by bazaar.probe_402 display and paid_request payment — so the chain shown at probe time IS the chain actually paid). Selection order:

   • ① Funded rails first: live USDC balance ≥ amount on that rail (direct RPC, cached ~60s). A signature-friendly chain with 0 USDC is never picked over a funded one, so settlement cannot fail for lack of balance on the selected rail.
   • ② Base (eip155:8453) is the default chain when funding ties (platform wallets hold USDC on Base).
   • ③ Static tiebreak (network_rank): Base (primary USDC chain) → Solana / other EVM without EIP-7702 delegation (plain ECDSA, e.g. Monad) → EVM with delegation code (Kernel EIP-1271). signer_mode="eoa": Solana excluded, all EVM equal.
   • ④ Within the same rank, cheaper amount / first accept wins.
   • Balance check failure = unknown, NOT unfunded (fail-open to ranking).

3. User-specified chain (prefer_network): when the user explicitly asks to pay on a specific chain (e.g. "pay on Base", "use Monad"), pass prefer_network="eip155:8453" (or "eip155:143" for Monad) to paid_request or bazaar_pay. This overrides the automatic ranking and selects the matching accept first (if present in the 402 challenge). Also available via env X402_PREFER_NETWORK. If the specified chain is not in the service's accepts, the automatic ranking takes over as fallback. Common CAIP-2 ids: Base eip155:8453, Monad eip155:143, Solana solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp.

   # User says "pay on Base"
   paid_request("GET", url, prefer_network="eip155:8453")
   # User says "pay on Monad"
   bazaar_pay(url, prefer_network="eip155:143")
   # User says "pay on Solana" / "use Solana"
   paid_request("GET", url, prefer_network="solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp")
   # Via env (CLI)
   X402_PREFER_NETWORK=eip155:8453 python3 skills/x402/client.py GET https://host/api

4. Prepaid deposit retry: if the first payment triggers a 402 insufficient_balance (prepaid top-up needed), the retry stays on the SAME chain the buyer already chose (prefer_network parameter in _pick_accept) — it never jumps to a different chain mid-flow.

5. Result verification: every paid_request result includes network (the chain actually used) and signer_type — always report these to the user so they know where the payment landed.

paid_request auto-detects BOTH 402 flavors: V2 header challenge (PAYMENT-REQUIRED → x402 SDK path) and the platform JSON-body challenge (accepts.pricingModel → manual EIP-3009 sign → retry with X-PAYMENT). For lifetime/monthly services, repeat calls within the paid period verify but do NOT settle — the result has paid: true with no new on-chain tx.

Buyer signer = Privy wallet by default (signer_mode="auto"); smart accounts are detected and signed via an ERC-1271-compatible path automatically. Multi-accept routing prefers rails where Privy signs a plain signature (max facilitator compatibility, no EOA funding needed): ① Base (primary USDC chain) → ② Solana / EVM chains where the payer has no EIP-7702 code (plain ECDSA, e.g. Monad) → ③ EVM chains with delegation code (Kernel EIP-1271, e.g. Base) as last resort — spec-correct but some seller facilitators reject it; for Base-only sellers that do, use signer_mode="eoa". Do NOT revoke the wallet's delegation (it powers gas sponsorship). auto is FAIL-CLOSED: if the Privy signer cannot be initialized, paid_request raises instead of paying from a different identity — allow the session-EOA fallback only explicitly via allow_fallback_eoa=True / env X402_FALLBACK_EOA=1 / signer_mode="eoa". Every result includes signer_type ("privy" | "session_eoa"); an opted-in fallback also sets signer_warning — check them to confirm which identity actually paid. ⚠️ The two signers are DIFFERENT payer identities: subscriptions/prepaid balances do NOT carry over between them. Similarly, EVM and Solana prepaid balances are separate (different pay_to addresses) — a deposit on Solana cannot be spent on EVM and vice versa. The gateway sums both balances for display but debits from the chain where the deposit was made. → EOA funding steps and signer internals: read references/buying-advanced.md BEFORE using the session EOA.

Spend guard: refuses to sign above X402_MAX_ATOMIC (default 1_000_000 = 1 USDC). ⚠️ Signing = spending real money once settled — confirm with the user before paying unfamiliar services or raising the cap. Paid response bodies are returned in FULL; unpaid/error bodies are capped at 2000 chars (env X402_BODY_MAX, 0 = unlimited). Result includes settlement.transaction (on-chain tx hash) — report it and verify per transaction-verification rules.

Payment ledger (every payment is recorded locally)

client.py appends every payment it signs to $WORKSPACE/.x402/payments.jsonl (override path: env X402_LEDGER). Each line is one JSON event: signed (authorization submitted — url, amount, payTo, payer, caller) and result (HTTP status, paid, settlement tx). The caller field identifies who spent the money (SC_CALLER_ID / JOB_ID / pid), so payments made from background sessions are attributable too.

To answer "where did this USDC go": read the ledger first, then reconcile against the wallet's on-chain USDC transfers — every outgoing transfer must match a ledger line. Ledger writes are best-effort and never block a payment.

Spending rules for automated sessions

• A background / scheduled / spawned session MUST NOT make x402 payments unless its task explicitly grants a budget; set X402_MAX_ATOMIC to that budget for the session.
• Every payment an automated session makes MUST appear in its final output (amount, url, settlement tx) — a payment only in the ledger is auditable but still counts as unreported work.
• On any 4xx payment rejection, do not retry with a fresh payment: each retry can spend again. Diagnose first.

Public paid URL (Cloudflare Monetization Gateway parity)

Make any local service a PUBLIC paid API (charge any caller for any resource, no accounts / API keys needed — same capability set as Cloudflare's Monetization Gateway, running on your own machine):

1. python3 skills/x402/scripts/make_public.py --name my-api --upstream-port <port> --mode payperuse --route 'GET /api/*=$0.01' --pay-to <wallet> — scaffolds output/my-api/start.py + config (defaults to --networks all: Base + Monad + Robinhood + X Layer + Solana)
2. preview(action='serve', dir='output/my-api', command='python3 start.py', port=<gateway_port>) — note: start the upstream in the same command if it isn't already running
3. community-publish skill → publish_preview(preview_id, slug='my-api') → public URL
4. Price discovery is built in: GET <public-url>/.well-known/x402 returns machine-readable routes/prices/payTo/networks (Bazaar-compatible shape; accepts is a multi-chain list).

A public URL is NOT a marketplace listing. Steps 1–4 only make the service reachable — the Service Marketplace will show nothing (or "free") until you complete the LIST chain (community-publish skill):

5. create_paid_service(name=..., service_type=..., api_endpoint=<public paid route>, provider_wallet=..., pricing_model=..., price=..., pricing_options=[...] for multi-plan) → service record.
6. publish_service(service_id) → live paid listing. Review is ADVISORY: optionally run submit_for_review(service_id) + get_review_status() for a 5-check self-report (402 reachable, price consistency, x402 validity, response match, doc completeness) — show it to the owner; it never blocks publishing.

⚠️ The LIST chain MUST go through the community-publish skill functions — NEVER hand-build a gateway payload. create_paid_service() makes every paid field a required argument; a hand-built payload with missing fields is rejected by the gateway (and on older gateways silently created a FREE service that later fails review with a misleading 400).

Skipping 5–6 is the #1 cause of "why does my paid service show as free / not appear in the marketplace".

Paid Project: two forms

A paid project is a Starchild project that charges for access. There are two forms — the platform supports both, and they share the same service_type="paid_project" + project_slug listing structure:

Form 1: Entire page behind paywall (user implements access control)

The page itself requires payment to access. The user (service provider) implements their own access control — a login-like component that checks a payment credential before serving content.

Platform responsibility: publish the project + list the paid API endpoint on the marketplace. The x402 gateway handles the payment protocol (402 challenge → settle → credential).

User responsibility: implement the access control interceptor in their own app:

• A paywall/login component on the frontend (credential input → localStorage)
• A backend endpoint that validates the credential and returns content
• The credential is issued by the user's own API after a successful x402 payment — the user's API returns the credential to the buyer

Flow:

1. Visitor opens the page → sees a paywall (user's frontend code)
2. Visitor pays via x402 (Agent or direct) → user's API returns a credential
3. Visitor enters the credential → user's backend validates it → serves content
4. Credential cached in localStorage → subsequent visits skip the paywall

What the platform provides:

• x402 gateway: handles the 402 payment challenge + on-chain settlement
• /x402/topup endpoint: buyer pays, gets an API key (timepass/subscription modes) or the x402 signature IS the credential (platform modes)
• /x402/balance endpoint: the user's app CAN use this to check if an API key is valid (optional — the user can also implement their own validation)

What the user implements (their own code, their own logic):

• Frontend: paywall UI, credential input, localStorage caching
• Backend: credential validation (can call gateway /x402/balance, or implement their own validation logic, or use the x402 signature directly)
• The "how to pay" documentation on the paywall page

"How to pay with Agent" documentation

The user's paywall page should include a "How to pay" section explaining how buyers can obtain an access credential via x402 payment. The Agent should generate this documentation based on the service's actual pricing, duration, and URL — do NOT copy a fixed template. The documentation should cover:

• The price and payment networks (e.g. "$2.99 USDC/USDG on Base, Monad, or Robinhood — buyer picks one chain per payment")
• How to pay via Agent (x402 client call to /x402/topup)
• How to pay directly (any x402-compatible client with X-PAYMENT header)
• What the buyer receives after payment (an api_key credential)

Form 2: Free page + paid API (Flow D)

The page is free to browse (intro/docs/landing page), but API calls cost money. This is Flow D — see the community-publish skill for details. The upstream app serves the free intro page at / and the paid API at /api/*.

Summary: paid project = free project + paid API (same pattern)

Both forms use service_type="paid_project" + project_slug. The difference is only in what the user implements:

The platform (x402 gateway + community-gateway) handles the payment protocol and marketplace listing in both cases. The user only needs to implement the access control interceptor for Form 1.

Consuming any x402 service from just a URL

Given ONLY a service URL (no docs, no guidance), onboard and verify it with this sequence — everything needed is self-describing in the protocol:

1. Discover (no payment): GET <url> with no payment headers. A 402 response IS the price sheet: accepts is a list (multi-accepts, one entry per network) — each entry has amount (atomic USDC), pricingModel, network, asset, payTo. Pick one chain to pay on. On multi-plan services a plans map carries every option's accepts. Optionally GET <base>/.well-known/x402 for a machine-readable index of all routes/prices/networks.
   • If amount == "0" (or marketplace free-status is active), the service is in a limited-time free promo: sign amount 0 for identity; expect no settle. This is temporary — after free_end the same URL returns list price again.
2. Probe plans (no payment, multi-plan only): repeat the unpaid GET with X-Pricing-Model: <plan> — each 402 quotes that plan's exact amount. An unknown plan returns HTTP 400 listing the valid ones.
3. Pay & call: client.paid_request("GET", url, max_amount_atomic=<cap>) handles the whole flow (402 → EIP-3009 sign → retry with X-PAYMENT). Select a plan with pricing_model="<plan>". Payer = the Privy wallet by default (signer_mode="auto"). For paid quotes the wallet must hold USDC on the service's network; for free-promo amount 0 a signing wallet is enough (no list-price USDC required). The session EOA needs funding ONLY if you pin signer_mode="eoa" or the result reports signer_type: "session_eoa" (see Buyer side above). cap = your spend guard (may be 0 during free). Confirm with the user before paying real money. Check signer_type in the result: it tells you WHICH identity actually paid. If the Privy signer is unavailable, auto raises (fail-closed) rather than silently paying from the session EOA; a signer_warning appears only when the fallback was explicitly allowed.
4. Verify billing semantics (subscription modes): call again — the result must be 200 with NO new settlement (paid: true, no new tx). On multi-plan services, requesting a different plan while holding one must also NOT re-charge. settlement.transaction from step 3 is the on-chain proof — report it and verify per transaction-verification rules. During free promo, step 3 should also show no new settlement even on first visit.

The same sequence doubles as a smoke test of any x402 deployment: steps 1–2 are free and validate the challenge contract; steps 3–4 validate settlement and access accounting end-to-end.

Discover & pay — marketplace first, then CDP

Buyer flow is marketplace-first. Do not collapse tracks; do not scrape third-party x402 directories.

import sys; sys.path.insert(0, "/data/workspace/skills/x402")
from bazaar import discover_services, resolve_marketplace, probe_402, bazaar_pay
 
discover_services("weather", limit=5)          # marketplace first, CDP fallback
resolve_marketplace("https://example.com/api") # → pay_url via community when listed
bazaar_pay(url, max_usd=0.01)                  # proxy-first pay; refuse non-standard

probe_402 / bazaar_pay only pay standard-v2 exact on known native USDC rails (see bazaar.PAYABLE_USDC): Base, Polygon, Arbitrum, World Chain, Solana mainnet, Monad, Avalanche, Ethereum, Optimism, Linea, Celo, Unichain. Multi-accept → prefer Privy-native rails (Base → Solana/no-code EVM → delegated EVM; see buyer signer section). The same selector (client.network_rank) drives bazaar's probe_402 ordering, so the rail shown at probe time is the rail auto actually pays. signer_mode="eoa" never registers the SVM signer and hard-filters Solana accepts — the pinned session-EOA payer identity is never substituted. Results and ledger lines carry the ACTUAL selected network/payer/signer_type (Solana settlements report the Privy Solana address as payer). Solana signs via Privy wallet_sol_sign (base64 raw message). Not yet: EURC/alt-stables, testnets. Other shapes (wrong-rail, tx-hash, non-standard, no-payment) refused before any signature. Buyer signs; seller facilitator settles.

Errors & diagnostics

Payment or gateway failing → MUST read references/troubleshooting.md (error contract, facilitator verify errors, security model, port ownership checks, proxy config). Quick e2e check anytime: python3 skills/x402/scripts/verify_setup.py (fund-free; --funded adds a real settlement test).

Setup

Python SDK is x402 v2.10+. Deps are NOT auto-installed: run bash skills/x402/setup.sh once per machine (also append it to /data/workspace/setup.sh so restarts reinstall).