x402 Explained: Why Your Analytics Miss Agent Payments, and How to Measure Them
x402 payments happen inside HTTP headers between an agent and your server, and agents rarely execute the JavaScript that browser analytics depend on. So a paid API call never becomes a pageview, and revenue settles onchain rather than in a payment dashboard. Measure server-side instead: log each 402 challenge, paid retry, verification, settlement and delivery.
Where an x402 payment actually travels
In x402 v2 the whole payment happens in HTTP headers. An unpaid request gets a 402 with a PAYMENT-REQUIRED header, a base64-encoded JSON object listing what the resource accepts: scheme, network, amount, asset and payTo. The client retries with a PAYMENT-SIGNATURE header carrying its signed payment payload. The server verifies and settles through a facilitator, serves the resource, and returns a PAYMENT-RESPONSE header with the settlement result: success, the transaction hash, the network and the payer address. Version 1 used X-PAYMENT and X-PAYMENT-RESPONSE for the same jobs, and some endpoints still serve both.
The spec is explicit that response bodies are a server concern and all protocol information rides in those headers. That one design decision explains most of the measurement gap.
Why browser analytics see none of it
No page, no tag. Tag-based analytics run as JavaScript inside a rendered page. An agent calling an API fetches JSON over HTTP and executes nothing, so no event fires. The paid request, the 402 before it, and the settlement after it are all invisible to the tag.
Agents avoid HTML even where it exists. Mintlify reported in September 2026 that across the docs sites it hosts, agents made 257 million requests in August against 131 million human page loads, and that 83% of agent traffic arrived through Markdown pages, llms.txt files and agent skills. Those are Mintlify's own figures and its detection method is not described, but the direction matches the mechanism: agents take the machine-readable path, which carries no tag.
A 402 looks like an error. Most monitoring groups 4xx responses as client errors. On a paid endpoint, the 402 is the top of the funnel, and treating it as noise hides your conversion rate.
Bots are filtered by design. Analytics vendors drop known automated traffic to protect human metrics. Mintlify's report quotes HubSpot's Chris Riley: treating non-human traffic as noise "means you're now filtering out your customers."
Revenue lands onchain. There is no card processor dashboard. Settled USDC goes to your payTo address, and the only receipts are the facilitator's response and the chain itself.
Measure it server-side: the five events
Instrument the middleware that handles x402, or a thin wrapper around it, and emit one record per stage, joined on a request id.
1. Challenge issued. Route, price, scheme, network and asset offered, plus coarse caller data such as user agent. This is your denominator.
2. Paid retry received. A PAYMENT-SIGNATURE arrived. Decode it and log which requirement the client accepted.
3. Verify result. Valid or invalid, with the facilitator's invalidReason. Clients should match on reason codes, not message text, and so should your dashboards.
4. Settle result. Success or failure, errorReason, transaction hash and payer. Count revenue only here.
5. Delivery. The status, latency and size of the response you actually served after settlement.
From those five you get the metrics that matter: challenge-to-payment conversion per route, verify and settle failure rates by reason, revenue per route, distinct payers, repeat payers, and the paid-but-not-delivered count, which is both a refund liability and the clearest sign of a broken handler.
Decode, but do not trust
PAYMENT-SIGNATURE is client-supplied input. Log it as a claim and record it as revenue only after the facilitator settles. A payload that fails verification is an attempt, not a sale.
Reconcile against the chain
Your logs say what you think settled. The chain says what did. On a schedule, compare settled transaction hashes with transfers into payTo using a block explorer or node. A hash in your logs with no matching transfer, or a transfer with no log entry, is the discrepancy worth chasing.
What a payer address does and does not tell you
The payer field is a wallet address, not a customer. One operator can run many agents from one address, and one agent can rotate addresses. Distinct payers is a floor on distinct buyers in some cases and an overcount in others. Treat it as a trend line, not a census, and segment by route and price rather than by assumed identity.
The same caution applies to user agents. Agents send whatever string their HTTP client sets. Use it for grouping, not for attribution.
Why it is worth the effort
The failures that cost money are the ones tags cannot see. A route issuing many 402s and receiving few paid retries is mispriced, or offers an asset or network buyers do not hold. A high settle failure rate on one reason code points at a specific client defect. Browser callers that never reach the 402 at all usually indicate a CORS problem: the x402 HTTP transport spec notes that none of the payment headers is CORS-safelisted, so a server must expose and allow them explicitly.
The buyer side has the mirror image of this problem. An agent spending from a CryptoCadet float, a non-custodial session-key bounded USDC balance on Base, needs its own record of what it paid for. Each side keeping a log, joined on the transaction hash, is what turns a stream of small payments into something both parties can audit.
Frequently asked questions
- Does Google Analytics track x402 payments?
- Not by default. Tag-based analytics rely on JavaScript running in a browser page, and an agent calling a paid API executes no JavaScript. The 402 challenge, the paid retry and the settlement all happen in HTTP headers between the agent and your server, so they never reach a client-side tag. Server-side logging is the only reliable source.
- Which HTTP headers does x402 use?
- In x402 v2, the server sends `PAYMENT-REQUIRED` with a 402 response, the client retries with `PAYMENT-SIGNATURE`, and the server returns `PAYMENT-RESPONSE` with the settlement result. Each carries base64-encoded JSON. Version 1 used `X-PAYMENT` and `X-PAYMENT-RESPONSE`, so an endpoint serving both versions should log both spellings.
- How do I count unique paying agents?
- Approximately, by distinct payer addresses in successful settlement responses. That is a count of wallets, not agents or customers: one operator can run many agents from one wallet, and one agent can use several. Use it as a trend, segment by route and price, and avoid treating any single address as a known identity.
- Should a 402 response be treated as an error in monitoring?
- No. On a paid endpoint the 402 is the expected first response and the top of the payment funnel. Track it as a challenge event with route and price attached, and alert on the ratio of challenges to paid retries instead. Group it with errors and the conversion rate disappears from view.