verify_before_pay in ten minutes

You have a Paddock design-partner key and have been asked to put verify_before_pay in front of your agent’s payment path. This page is that, and nothing else. The general builder guide is the API reference; connecting over MCP is on its own page.

Your key goes in a header on every request:

X-Paddock-Key: pk_proagent_YOUR_KEY

No OAuth, no signing, no session. The key also works as an ?api_key= query parameter for browser testing, but use the header in production — query strings land in access logs, browser history and Referer headers.

You do not need the key to try the tool. verify_before_pay is on the free tier, so a free pk_free_ key reaches it against a shared 10 calls a day. Your partner key exists so you are not rationed while you build.

route is three-valued: the JSON literal true, the JSON literal false, or the STRING "inconclusive".

// The only correct test:
if (result.route === true) { pay(); } else { doNotPay(); }

// NEVER this — "inconclusive" is a non-empty string, so it is truthy,
// and this pays exactly when we have told you we could not check.
if (result.route) { pay(); }        // ✗

"inconclusive" means we could not read a 402 from the endpoint at query time. Not that it failed — that we do not know. Everything else in that response is history, and history is not proof of what an endpoint will charge you now. Treat it as a no for payment purposes and a look-again for yours.

false is the opposite: it means we know something. A contract mismatch, a flagged circular cluster, or a 404/410 from the endpoint. A hard false outranks an unreadable probe — if the price is wrong, an unparseable response elsewhere never softens that into a shrug.

Since verify_before_pay/0.7, a call that states no expectations is "inconclusive" too. Every contract check compares the live 402 against something you told us — pay_to for the wallet, expect_network for the chain, expect_asset for the token, expect_price_usdc for the price. Send none of them and there was nothing to compare, so the verdict says so rather than passing you on a readable 402 alone. The reason code is no_expectations_supplied and the summary reads Nothing was compared. Pass pay_to or expect_* for a verdict; for liveness alone call get_liveness.

If you are running shadow mode, this is the one thing to check in your harness. A stored verdict at verify_before_pay/0.6 or older could be a true for a URL-only call; the same call today is "inconclusive", and nothing about the endpoint changed — we did. Verdicts for calls that did state an expectation are unaffected and stay comparable across the boundary. That is what the version bump is for.

The pre-payment check no seller can self-report. Call it before your agent authorizes an x402 payment. It sends an unpaid request to the endpoint you name at the moment you call, decodes the 402, and checks network, asset, seller, and price against what you expected and against the seller's published config. It then adds three things only an independent observer can: whether the endpoint has settled real volume recently from wallets that are not its operator's, whether it sits in a circular-settlement cluster, and how its price compares to its category. The answer is `route: true`, `false`, or `"inconclusive"`, each with the evidence and its date. Liveness and contract are as of the call; settlement and circular signal are snapshot-dated, and each block says which. There is no success-rate field, on purpose: Paddock observes settlements, not failed calls, so it returns recency and frequency, which it can actually see. Test for `route === true`; inconclusive is the one case where you must not pay on our say-so. `route: true` scopes to one claim — the live contract matched what you expected — and is not an all-clear on every signal: stale settlement, a circular flag, a payTo divergence and a failed request pre-flight can each coexist with it, and each block says whether it moved the verdict, so read the evidence rather than `route` alone. A second, narrower verdict rides alongside it: `contract_and_request_ok` is `true` only when `route` is `true` and your own declared request passed pre-flight, `false` when either is bad, and `"not_assessed"` when a term was never established; `contract_and_request_ok_excludes` names the risk categories it is silent on, so it can never be read as a full clearance.

Do not gate payments on us in week one. Run the call, log the verdict, pay as you would have anyway, and grade us later. Two fields exist for exactly this: schema_version, bumped only on a breaking shape change and never for an added field — store it with every verdict, because two verdicts are only comparable at the same major version — and checked_at, the instant the probe ran. Responses are never cached; the entire value of the answer is that it was taken then.

{ "schema_version": "...", "checked_at": "...", "route": "...",
  "reason_codes": ["..."], "endpoint_url": "...", "pay_to": "...",
  "your_outcome": "settled | failed | refunded | not_attempted" }

Store reason_codes as an array, not a joined string — the vocabulary is append-only and you will want to group by individual codes later. After a few weeks you can answer the only question that matters: when we said false or "inconclusive", would paying have gone badly? Tell us what you find, including where we were wrong. Publishing our own bad news is a standing rule here, and a design partner’s disconfirming evidence is the most useful thing we can be handed.

There is no success rate, and there never will be one from this record. Paddock observes settlements, not attempted calls. A payment that was tried and failed leaves no row in our data, so a success rate computed from it could only ever be 100% — a number that would look like reassurance and mean nothing. You get recency and frequency instead: last_observed_settlement_date, observed_settlements_7d / _30d, and days_present_7d / _30d.

No settlement history is not a veto. A brand-new honest seller and a fake one look identical on day one. Refusing every unseen seller would make this an incumbency filter rather than a fraud check, so absence is reported loudly in reason_codes and kept away from the verdict. That call is yours, with your own risk appetite.

Outside coverage is said out loud. Our circular detector reads one facilitator on one chain. A wallet settling elsewhere gets "not_assessed" with a basis naming what was in scope — never a silent skip, and never a “clean” for something nobody looked at.

[email protected] — for anything, including “your verdict was wrong and here is the case”. Include checked_at and the endpoint_url; the response is not cached, so those two are what let us reconstruct what we saw.

Full reference: paddock.finance/docs · OpenAPI · MCP setup

What to read next.