x402 Refunds, Disputes and the Sign-Off You Still Need

curl -i https://moltlinestudio.com/api

Run that against the agent payment endpoint and you get an HTTP 402 back, not a 200. That is x402 doing exactly its job: a machine-readable payment challenge. It is also the point where most teams stop reading the spec and start assuming the protocol handles everything downstream.

It does not. x402 settles a payment handshake. It does not refund, reverse, arbitrate, or decide whether your agent should have spent the money at all. Settlement is final, so the controls belong in your client: spend caps, key custody, and a defined behaviour for a run that cannot pay.

This post walks those gaps in order. We start with one free call and one 402 round trip, then look at what x402 actually settles and how final that settlement is.

A comparison table separates what the protocol covers from what you cover. We close with why most runs never reach the payment step, plus four numbers and one error path to define before you ship.

Start With One Free Call and One 402 Round Trip

curl -sS -X POST https://mcp.moltlinestudio.com/<server> \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Swap <server> for any endpoint on the server catalogue. Free tools answer with no account, no API key and no signup: 110 of the 160 tools work that way.

Now request a premium tool with no licence. The response is a JSON error, premium_tool_requires_license, pointing at https://moltlinestudio.com/api. It is not HTTP 402.

That distinction is the whole article. HTTP 402 is x402's payment handshake. premium_tool_requires_license is an entitlement check. Wire them together and you ask an agent to pay again for something it already bought. The premium tool and 402 handling notes walk through the client side.

What x402 Actually Settles, and How Final It Is

The 402 round trip is the whole protocol surface. A request arrives unpaid, the server returns 402 with payment requirements, the client pays and retries the same request (x402.org). The whitepaper dated May 6, 2025 pitches this as a way to drop API keys, subscriptions and manual payment processing, settling in stablecoins such as USDC (whitepaper).

x402.org says the protocol charges zero protocol fees and only network fees apply. That is a fee claim, not a refunds claim.

Settlement is a transfer, not an authorization. Once USDC lands on Base, no issuer or intermediary holds funds that can pull them back. Treat that as a design reading, not a documented refund mechanism, and check docs.x402.org before relying on anything beyond the handshake.

Vendor FAQ lines need attribution. x402.org mentions millions of transactions and a security audit without a figure, date or auditor. Repeat those only as x402.org's claim.

Independent scrutiny is early. A 2026 arXiv paper on x402 logic flaws names a "Synchronization Gap" in payment integrity (arXiv); only its table of contents is public in the extract, so treat it as an area of scrutiny, not findings. For how licence terms interact with this model, see licensing that breaks.

Does x402 Support Refunds or Chargebacks?

Settlement finality answers the refund question directly: no. The handshake has no reverse step. Nothing in a 402 challenge, payment payload, or settlement response represents a refund, a hold, or a partial reversal. The whitepaper's section on "Mitigating Fraud, Chargebacks, and Compliance Overhead" argues the card problem away. It does not give you a refund path for your own buyer.

A USDC transfer on Base has no issuing bank to file a chargeback against. Every failure mode ends the same way:

• Overpayment is spent.

• A payment from the wrong run is spent.

• A payment for the wrong endpoint is spent.

The only remedy is whatever the seller chooses to do off protocol. Write that choice down before you sell anything:

• The licence term and what it grants.

• Whether a day pass is refundable at all.

• How a buyer reaches a human.

State the answer plainly. The licence term for a specific server listing is the concrete example.

Legal framing is still forming. A December 2025 JD Supra article on HTTP 402 and internet-native stablecoin payments exists (JD Supra analysis), but treat it as a pointer to a conversation, not settled guidance. That is a policy gap, not a protocol feature.

Who Decides Whether an Agent Is Allowed to Buy?

Refunds are a seller policy. Spending authority is yours. x402 answers one question: did this request carry payment? It never answers whether the agent should spend at all. That is policy, and it lives in your client.

Settle these before an agent holds a funded key:

• maximum single payment

• budget per run and per UTC day

• which endpoints are payable

• which agents get keys

• what stops a run mid-flight

None belong server-side. A server can price a tool and reject an unpaid request. It cannot know your budget or who approved the spend. If the endpoint is an image tool, the same rule applies before you wire an image tool.

Enforce the number in code, not in a prompt. A system-prompt instruction is a suggestion. A hard cap checked before the retry is a control.

Keep three sign-offs manual: first payment to a new merchant, anything above the cap, and renewals that roll into a second month.

Where Should Spend Caps Live?

Policy settled, the cap belongs in the process that holds the signing key: after the 402 returns and before the retry leaves. That is the only point where a limit can stop a payment rather than describe one.

Enforce three numbers, not one:

• per run

• per UTC day

• per merchant or endpoint

A single cap is too coarse for a looping agent. Put prices in client config, not prose. Moltline's own labels are 19 USDC on Base for a month at https://moltlinestudio.com/api and 2 USDC for a day pass at https://moltlinestudio.com/api/premium/day-pass. A wrapper that knows those two numbers can refuse anything else.

Log every 402, payment attempt and refusal against the run id, with amount and endpoint. Without that log you cannot audit what the agent bought. Map each cap to a named endpoint from the server list, not a category.

Next, decide who holds the key.

Who Holds the Key the Agent Signs With?

The cap is only as strong as the key behind it. That key belongs to one agent, not the fleet.

• One wallet per agent. A shared key makes every payment unattributable and every leak a shared leak. Run ids in your logs tell you what happened; separate wallets tell you who paid.

• Fund to the decision, not the month. 2 USDC buys a day pass. 200 USDC buys ten months if a retry loop goes wrong. Hold the smaller number.

• Keep the key out of prompts, repos and logs. An agent that can read its own private key can be talked into spending with it. Load it from a secret store at signing time.

• Rotate routinely. Treat rotation as a scheduled task, not incident response. NIST SP 800-57 Part 1 Rev. 5 covers key lifecycle guidance.

• Name the top-up authority. A top-up is a human decision, or a pre-approved automated one with its own cap. If the agent decides, you have removed the human from the only step that matters.

An empty wallet mid-run is the next problem.

What Happens When a Run Cannot Pay?

Once the key has a balance, the next failure is a run that cannot pay. Define that path in code before the agent reaches it. Otherwise the model improvises: retries, alternate endpoints, self-funded top-ups, or a confident summary of work it never did.

Fail closed. Return the structured error to the caller, stop the step, and record which tool was blocked. A run that quietly continues without the tool produces output you cannot trust.

Never let an agent top itself up from its own reasoning. Buying a licence or a day pass is a human decision, or a pre-approved automated one with a cap. It is not emergent behaviour.

Your wrapper chooses one of three responses to that error: pay if under cap, queue for approval, or fail the step. The server does not decide.

Add an alert path so the failure reaches a person. A blocked run nobody sees is a silent outage for the task. For the transport and setup behind that wrapper, see MCP server setup basics.

Protocol Covers vs You Cover: A Comparison Table

The failure path is defined; now split the controls. The protocol's share is small.

x402 handles the challenge, the payment and the retry. Every row after settlement lands in your column.

The entitlement row is the one teams miss. A licence bought once turns later calls into entitlement checks, so the common path is a lookup, not a payment.

Pricing shape matters. Moltline sells flat access, not per call: $19/month for All-Access in crypto, 19 USDC over x402 at the payment endpoint, 2 USDC for a day pass. One spend decision per period. Endpoints are listed on the server catalogue.

Why Most Runs Never Reach the Payment Step

The table makes the split clear, but most traffic never reaches the split. Check your own client logs: the runs where a payment is required are the exception, and the spend decision happens once, then disappears into a lookup. If your client is Claude, the Claude MCP integration path shows where that lookup sits.

Three consequences:

• Testing: payment code runs rarely, so it breaks silently. Exercise it on a staging key.

• Risk: exposure per period is the price of the period, not the calls. Cap that number.

• Errors: keep premium_tool_requires_license and HTTP 402 separate. One means buy a licence, the other pay this request.

Next Step: Four Numbers and One Error Path

The entitlement check is the common path, so test the uncommon one deliberately. Curl a free endpoint from the server list and confirm you get a result with no key. 110 of 160 tools work that way.

Then request a premium tool with no licence and read premium_tool_requires_license yourself. You need the exact payload your wrapper will handle, not a description of it.

Write down four numbers before any agent holds a funded key:

1. Maximum single payment.

2. Per-run cap.

3. Per-day cap.

4. Balance you will leave in an agent wallet.

Pick one response for a run that cannot pay, and implement it before launch:

• Pay, if the amount is under cap.

• Queue for approval.

• Fail the step and record the blocked tool.

Run the 21-check agent-readiness checker at https://moltlinestudio.com/agent-check.html, fix what it flags, then choose your first endpoint from https://moltlinestudio.com/servers.html.

Conclusion

x402 settles payments. It does not settle refunds, disputes, or who signs off on a purchase. Those stay with you.

Three takeaways:

• Finality is the default, so treat every payment as irreversible until your own refund path exists.

• Spend caps belong in your client, not the protocol. Cap the period, not the call count.

• Keep premium_tool_requires_license and HTTP 402 separate in your error handling.

The value is a working payment loop you can test before real money moves. Start with the free path: curl a free endpoint from the server list, then read the premium error payload yourself.

Write your four numbers down, pick one blocked-run response, and run the 21-check agent-readiness checker at https://moltlinestudio.com/agent-check.html. Then choose your first endpoint from https://moltlinestudio.com/servers.html. Test the uncommon path deliberately, and the common one stops surprising you.