How to price paid MCP tools with x402

Start with the unit a buyer values

A tool call is a transport event, not necessarily a useful commercial unit. One call may return a finished company record; another may create a job that requires polling; a third may return ten search results that need paid follow-up reads. Define the completed outcome first, then count the calls, compute, upstream fees and failure risk required to deliver it.

Good pricing copy names both the technical and product unit: '$0.02 per query returning up to 20 cited results' is more useful than '$0.02 per call.' If output size, latency or quality varies, publish the constraints buyers can rely on. This makes competing tools comparable and gives an agent enough information to estimate workflow cost before it starts spending.

When should a tool use exact pricing?

Use the exact scheme when the server can state the full price before execution. Fixed database lookups, standardized reports and deterministic transformations are natural candidates. The client authorizes the advertised amount, and the server settles that amount if the payment and request are valid. The simplicity makes policy checks and buyer estimates easier.

Do not use a fixed price to conceal large differences in delivered work. If a short document and a thousand-page document cost the same but impose radically different costs, providers will either overcharge small jobs or lose money on large ones. Set clear size limits, create tiers or move variable work to a measured-usage scheme.

When should a tool use upto pricing?

The upto scheme fits work whose final charge depends on usage that is known only after execution, such as model tokens, compute time or bytes processed. The buyer authorizes a maximum and the server settles the actual amount up to that cap. This preserves a deterministic spending boundary without forcing the seller to guess every job's final cost in advance.

Usage measurement becomes part of the product contract. State what is measured, how it is rounded, when measurement starts and what happens when the cap would be exceeded. Return usage and actual charged amount in the result or settlement evidence. A maximum without a transparent meter is difficult for agents to compare and for buyers to audit.

When does batch settlement make sense?

Batch settlement is designed for frequent EVM micropayments where settling every request independently would add avoidable overhead. The buyer funds a channel, signs off-chain vouchers for calls and the seller later redeems value in batches. Each request can still have a maximum, and the client must register the scheme when a server advertises it.

The model adds channel state and reconciliation, so it should solve a measured volume problem. A new provider with occasional calls may be better served by exact pricing until traffic justifies the operational complexity. Buyers also need policies for deposits, outstanding voucher value and closing or replenishing the channel.

Keep discovery and evaluation free

An agent should be able to learn what a tool does, inspect its input schema, see accepted payment options and estimate the result before paying. Charging for tools/list or hiding the price behind an initial paid call creates a circular problem: the buyer must spend before it can decide whether the capability fits. Publish discovery metadata and safe examples outside the paid execution path.

A free diagnostic or small sample can reduce uncertainty further, but it should not become an unbounded cost center. Rate-limit abuse, use cached public data or expose a constrained preview. The paid tier should unlock a clearly more useful outcome, not merely remove artificial opacity from the free one.

Price failures and retries before they happen

Decide which failures are chargeable. Invalid arguments, denied authorization and unsupported payment options should normally fail before settlement. Upstream timeouts and post-settlement execution failures are harder: a server may already have incurred cost, but a buyer did not receive the promised result. Publish the rule and return a correlation identifier that supports reconciliation.

Use the x402 payment-identifier extension or an equivalent documented idempotency design so a safe retry does not create a second payment or duplicate a mutating operation. Never tell clients to retry every error automatically. A client should know whether the payment settled, whether the work started and whether the same identifier will return a cached result.

• Reject malformed tool input before requesting or settling payment where possible.
• Separate payment failure, execution failure and invalid output in logs and responses.
• Document refund, replay or support behavior for paid calls that do not deliver.

Run a pricing experiment, not a permanent guess

Launch with a small number of legible price points. Track cost per completed result, buyer completion rate, paid-but-unsuccessful calls, repeat use and the share of workflows stopped by policy. Compare results by tool because a data lookup and an image generation job can support different margins and buyer expectations even on the same server.

Change one important variable at a time and preserve dated observations. A lower price that causes agents to loop or attracts low-intent traffic may reduce reliability. A higher price may improve unit economics but push the complete workflow over a buyer's budget. Optimize for sustainable completed tasks rather than transaction count alone.

What should the listing and 402 response disclose?

Publish the tool name, output, billing unit, price or maximum, scheme, network, asset, example input and observation date. If the same tool has multiple price tiers or network options, describe what changes. Keep the live 402 response authoritative and update directory and Bazaar metadata whenever the production route changes.

Finally, prove the offer from a buyer's perspective. Run the documented connection path with a dedicated wallet, inspect the requirement, complete one representative payment and validate the result. A pricing page, schema or compiler pass cannot show that the exact route settles the intended amount and returns the promised work.

Related directory entries

Sources and methodology

TOLL·402 distinguishes public claims, registry discovery, unpaid quote checks and settled paid-call verification. Sources below support the visible claims; presence in a registry is not treated as verification.

1. x402 seller quickstart — Current exact, upto and batch-settlement behavior.
2. x402 payment identifier extension — Official idempotency mechanism for safe payment retries.
3. x402 Bazaar documentation — Discovery metadata for paid resources and MCP tools.
4. TOLL·402 pricing field report — Directory evidence and limits of advertised per-call prices.