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)
# --networks defaults to "all" (Base + Monad + Robinhood + X Layer + Solana mainnet); the 402 challenge
# returns a multi-accepts list — the buyer picks one chain per payment.
python3 skills/x402/scripts/monetize.py --name my-api --upstream-port 5173 \
    --mode pay_per_use --price 0.01 --facilitator $FAC

# lock to a single chain (custom)
python3 skills/x402/scripts/monetize.py --name my-api --upstream-port 5173 \
    --mode pay_per_use --price 0.01 --networks eip155:8453 --facilitator $FAC

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