x402

Experimental surface

x402’s local facilitator adapter is experimental: implemented at the daemon level for self-hosted operators on the generic compute endpoints and not exposed on the marketplace publish path (marketplace_publish / froglet-node publish). Per the versioning policy, experimental surfaces may change or be removed without a major version — do not build on it for anything that must outlive a release cycle. To publish a paid marketplace service, use Lightning or Stripe. The separate x402.eip3009.v1 kernel method has conformance vectors, but this x402_usdc adapter is not yet wired into the signed marketplace Deal flow.

Setup

Provide the Base wallet address and an x402 v2 facilitator endpoint. The endpoint must either authenticate requests upstream itself or be an operator-managed transparent proxy that does so; Froglet does not synthesize CDP API JWTs from an unauthenticated URL.

cd froglet && FROGLET_X402_WALLET_ADDRESS=<base-wallet-address> \
FROGLET_X402_FACILITATOR_URL=<authenticated-facilitator-or-proxy-url> \
./scripts/setup-payment.sh x402

The only optional override is the currently fixed network alias:

cd froglet && FROGLET_X402_WALLET_ADDRESS=<base-wallet-address> \
FROGLET_X402_NETWORK=base \
FROGLET_X402_FACILITATOR_URL=<authenticated-facilitator-or-proxy-url> \
./scripts/setup-payment.sh x402

That writes .froglet/payment/x402.env with the selected wallet, network, and facilitator URL. The current Froglet x402 implementation supports base only.

Verification

The setup helper validates the wallet syntax locally, requires FROGLET_X402_NETWORK=base, and then probes facilitator reachability through:

POST <facilitator>/verify

The probe accepts a real 200, 400, or 422 response from /verify as proof that the endpoint is present. It rejects 401 and 403, because the running node would be unable to settle through an endpoint that still expects credentials Froglet has not supplied. The probe does not claim that a payment is fully spendable until a real authorization is presented at runtime.

The current public adapter expects the signed token amount to exactly match the configured numeric service price. It does not perform FX conversion from sats into backend-native token units.

Runtime behavior

x402 maps Froglet’s local /v1/node/* lifecycle to a facilitator-backed authorization flow:

• descriptor exposes x402_usdc
• prepare validates the signed payment token with the facilitator
• commit settles through the facilitator
• release is a no-op because the authorization either settles or it does not

This adapter does not currently add x402-specific quote/deal settlement terms to the signed kernel flow.

Use this rail for daemon-level, USDC-style machine payment on self-hosted compute endpoints. For published marketplace services, settle with Lightning or Stripe instead.