Discussion: batched / session x402 settlement for agent query loops

[PaulieB14]

@tmigone Opening this as a suggestion / discussion, not a bug. Feel free to convert it to a Discussion.

Update (revised after production feedback): someone running x402 in production corrected the original premise of this issue, and they're right, so I've rescoped it.

What I got wrong

I originally framed this as "x402 makes you pay on the request, not on a successful result." That is not an x402 property, it's an implementation choice. The signed authorization and the settlement are separate steps, and the server decides when to settle. A handler can validate everything first and only settle when it returns success; on rejection it returns 4xx and the buyer's authorization simply expires unused, so nobody eats a failed call. The standard Next x402 wrapper does this out of the box. Settlement also doesn't have to block the response, you can count and settle after the response is already on the wire. So per-call "pay only for what succeeded" already exists today, and the latency cost isn't inherent either.

The actual open problem

The amortized case. When an agent makes many small queries in a short burst, you don't want a facilitator round trip per call in the hot path, and you don't want N separate settlements. Batched or session settlement — many queries reconciled into a single settlement — is the piece that doesn't have a clean answer yet in the x402 client.

Shapes worth exploring

1. Prepaid balance. Caller tops up once, the server draws it down per query with no per-call settlement, and re-challenges when the balance is empty.
2. Signed vouchers / escrow. Caller signs incrementing off-chain vouchers, the server redeems the latest one on chain in a single tx, unspent funds return on close. The Graph already has essentially this in TAP (receipts aggregated into RAVs, redeemed in batches), so the pattern is proven in-stack.

Open question: is any batched/session settlement already on the radar for the x402 client?

[PaulieB14]

Update: x402 already ships this as a first-class scheme

Since opening this, I dug into the current x402 spec and the batching I proposed here is no longer a protocol gap — the protocol already defines a batch-settlement scheme (EVM) that is a superset of what #1031 asked for. So this shifts from "should x402 support batched/session settlement?" to "should graph-client adopt the batch-settlement scheme?"

How it works (from the spec)

The batch-settlement scheme enables high-throughput payments via stateless, unidirectional payment channels:

• A buyer deposits ERC-20 funds into onchain escrow once (deposit via EIP-3009 or Permit2, submitted by the facilitator).
• The buyer then signs off-chain cumulative vouchers per request, each stating the channel's total claimable amount.
• The server verifies each voucher quickly and serves the response without waiting for an onchain transfer.
• The server's channel manager periodically claims the latest vouchers from many channels in a single batched onchain transaction, then sweeps claimed funds to the receiver in a separate settle tx.
• Idle channels can be cooperatively refunded after outstanding vouchers are claimed.
• The route price is a per-request maximum; for dynamic pricing the server can charge less via settlement overrides (e.g. setSettlementOverrides(res, { amount: "50%" })).

It's explicitly intended for repeated paid API calls and usage-metered endpoints where one-by-one settlement is too expensive or slow — i.e. exactly the agent query-loop case in this issue.

Mapping #1031's asks -> shipped mechanism

#1031 ask	Batch-settlement mechanism
Avoid per-call onchain settlement	Deposit-once escrow + off-chain cumulative vouchers + batched onchain redemption
Settlement overhead at agent query volume	Designed for "repeated paid API calls / usage-metered endpoints"
No refund on failed/partial responses	Cooperative refund of idle channels + settlement overrides (charge below the per-request max)
Payment rails	EIP-3009 or Permit2 — the same rails graph-client's x402 gateway already uses

Links

• EVM spec: scheme_batch_settlement_evm.md
• Cloudflare binding: scheme_batch_settlement_cloudflare.md
• Docs page: docs/schemes/batch-settlement.mdx
• Public rendered docs: docs.x402.org/schemes/batch-settlement
• Solidity contract: x402BatchSettlement.sol
• Implementers doc: x402-batch-settlement-implementers.md
• TypeScript package: @x402/evm (mechanisms/evm)
• TypeScript src: batch-settlement (@x402/evm/batch-settlement)
• TypeScript example server: batch-settlement
• Fullstack example: next-batch-settlement-redis
• E2E example: next app/api/batch-settlement
• Python module dir: mechanisms/evm/batch_settlement/
• Go mechanism: go/mechanisms/evm/batch-settlement

For TypeScript, the @x402/evm package (at typescript/packages/mechanisms/evm) exposes @x402/evm/batch-settlement/server and @x402/evm/batch-settlement/client (plus .../server/file-storage and .../client/file-storage), per its package.json exports.

Related threads

• x402#136 (closed) — "Payment Channel Support?", the original feature request; closed by merged PR #2051 (Batch-settlement scheme specification for EVM).
• x402#2273 (open) — [Extension Proposal] metered-session: prepaid metered sessions with auto-refund for streaming x402 transports. Covers the streaming/refund angle and is worth watching.
• x402#1642 (open) — [RFC] upto scheme for SVM.
• x402#2457 (closed) — RFC: SVM batch-settlement scheme, the Solana counterpart to the EVM scheme.

Next step for graph-client

Rather than build bespoke batching, adopt the batch-settlement scheme in graph-client's x402 integration (or demonstrate it in a reference client) — it already uses the EIP-3009 / Permit2 rails the gateway relies on, and the metered-session thread (#2273) is worth tracking for the streaming/refund case.

cc @hyperxiaoerxz-hash @tmigone @ardatan

[tmigone]

Hi @PaulieB14 thanks for the discussion here.

Batched settlement as you say is something that's already part of the x402 protocol, in fact we helped design it based on ideas from our previous work with TAP/GraphTally.

The reason it's not enabled/implemented in the graph stack is that we don't see the need for it yet. There are two big benefits for using it:

1. On chain efficiency - batched settlement cuts the gas costs considerably, specially important when the cost is comparable to the transaction amount being processed.
2. Reduced latency - batched settlement removes a roundtrip to the facilitator from the query hot path, making it faster.

Point 1) does not affect the user, it's the gateway operator the one paying that cost (and at current query volume it's actually free).
Point 2) does affect the user, but the premise is that this is mostly being used in agentic contexts where an HTTP roundtrip is not very noticeable when compared to LLM inference delays.

[PaulieB14]

Thanks for the detailed reply @tmigone. Good to know it came out of the TAP/GraphTally work, that lineage makes sense.

Agree on the gas point. That cost sits with the operator and it's basically nothing at current volume, so on its own it isn't a reason a user would care about.

On latency I mostly agree too, with one exception. The "LLM roundtrip dominates" logic works for conversational agents where there's one inference per query. But there's a whole class of agents that don't work that way. Data gathering, monitoring, and analytics agents fire a lot of subgraph reads back to back with no model call in between. For those, the roundtrip to the facilitator on every query is the main cost, not something that disappears next to inference time. It's a smaller slice of usage today, but it's exactly the kind of high frequency querying that would actually move volume.

One thing I'd add to your list. There's a third benefit beyond gas and latency, which is billing. Right now you pay per call whether or not the query returns anything useful. With batch settlement you get cooperative refunds and settlement overrides, so you don't have to charge for a failed or empty read. It doesn't matter much at low volume, but it's a fairness thing, not just an optimization.

All that said, I don't actually think batching is what's holding adoption back. The real problems are earlier in the funnel. Most agents have no idea The Graph is a native x402 data source, so awareness is the first gap. And even when they know, there's no clean way for an agent to figure out which of 15,000 plus subgraphs answers its question, so discovery is the second. Batching is more of a "turn it on once there's volume" thing. Awareness and discovery are what create the volume in the first place. Happy to keep the batch settlement path ready for when it's needed since the reference code is all there, but if the goal is getting agents to actually use The Graph.

[tmigone]

You make very good points. I think in your example of data gathering agents you could still make the inference delay argument, but with less relevancy.

In any case, this functionality is definitely something we want to have but I don't think we should be prioritizing yet until we get higher adoption.