Common x402 facilitator setup mistakes
Avoid the common setup issues that break x402 settlement, including wrong fee-payer keys, unfunded accounts, and mismatched network configuration.
Why it matters
Most local facilitator failures are configuration issues rather than protocol bugs. A short checklist can save hours.
Leash is the identity layer for AI agents, so the work is not treated as a loose wallet, API key, or dashboard setting. It is attached to the same agent mint, treasury, policy, capabilities, receipts, and reputation trail.
How Leash handles it
Leash settlement depends on consistent network, asset, facilitator URL, fee payer, buyer signer, and seller payTo configuration.
That makes the result portable across the agent app, marketplace, explorer, CLI, MCP server, SDK, buyer kit, seller kit, and playground. The surface can change, but the identity and proof trail stay the same.
Implementation checklist
Check the facilitator logs, verify /supported, confirm the fee payer balance, and run the API smoke test against your local facilitator URL.
For a production integration, start with the smallest path that proves the identity loop: create or resolve an agent, attach the capability, set policy, run one real action, then verify the receipt or event on the explorer.
Smoke-test a local facilitator
export LEASH_FACILITATOR_URL=http://localhost:8787
pnpm --filter @leashmarket/api facilitator:smoke
# For full stack e2e:
LEASH_API_FACILITATOR_URL=http://localhost:8787 pnpm --filter @leashmarket/api e2e:devnetFAQ
What does invalid fee payer transferring funds mean?
It usually means the facilitator fee payer is also the buyer transfer authority. Use a separate keypair.
Why does devnet settlement fail after a restart?
The fee payer may be unfunded, the env secret may be missing, or the buyer and facilitator may be pointed at different networks.