Troubleshooting

When a paid request behaves unexpectedly, work through these checks in order. Most issues fall into one of four buckets.

​

I get a 402 but never the resource

The challenge is being returned, but the retry isn’t producing a 200. Check:

• The client retried with a valid payment payload (signature, network, and amount must match the challenge).
• The transaction shows Completed in Transactions.
• The events stream shows Payment followed by Fulfillment in Events.

If you see a Payment event but no Fulfillment, the upstream call is failing — see the next section.

​

Payment succeeded but the upstream call failed

The events stream shows Payment but not Fulfillment, and the transaction is Failed. Check, in order:

• Paywall Target URL is correct and reachable from Proceeds.
• Paywall custom headers and query parameters are valid.
• Service auth method matches what your upstream expects — see Forward upstream auth.

Open the matching Error event for the underlying reason.

​

The wrong route is being charged

Requests are matching the wrong paywall, or your origin is being called with the wrong path. Check:

• The paywall slug matches the URL the client called.
• The paywall Target URL points at the correct upstream path.
• The generated URL pattern: /api/x402/pay/{serviceId}/{slug}.

​

MPP is not available

The Tempo / MPP path isn’t returning a working URL. Check:

• Tempo is included in the paywall’s supported networks.
• The paywall exposes an MPP endpoint at /api/mpp/pay/{serviceId}/{slug}.
• The client is using an MPP-aware flow such as mppx.

If MPP is missing for a paywall that should support it, re-edit the paywall and ensure Tempo is selected under Networks.

​

Agent payments aren’t going through

You’re paying from an agent in Claude Code, Cursor, or Codex and the call fails. Check:

• The agent wallet is funded with USDC. For Circle Agent Stack, confirm you deposited into Gateway, not just the onchain wallet.
• You’re using the right URL type for the tool: MPP (/api/mpp/pay/...) for Tempo Wallet, x402 (/api/x402/pay/...) for Circle Agent Stack; AgentCash handles either.
• The wallet tool’s CLI, skill, or MCP server is installed in the IDE where your agent runs — see Pay with an agent.

​

Still stuck?