Tools reference

Introduction

The PipRail MCP server advertises eight tools by default, built by the SDK’s paymentTools(client) and dropped straight onto the wire. The SDK descriptors carry draft-07 JSON Schema, so the server forwards them untouched. Only piprail_pay_request moves funds; piprail_register writes a listing to an external index (so it’s not flagged read-only) but moves none; the other six are read-only. Every result is emitted both as a text block and as structuredContent, so a client that ignores structured output still reads the text.

// every tool, in advertised order
"piprail_discover" · "piprail_quote_payment" · "piprail_plan_payment" ·
"piprail_pay_request" · "piprail_register" · "piprail_budget" · "piprail_guide" ·
"piprail_verify_receipt"

Each tool carries advisory MCP annotations (readOnlyHint, destructiveHint, openWorldHint, …). They are hints only; the real boundary is the spend policy, enforced before any send.

Six more in sovereign mode

PIPRAIL_MODE=sovereign appends six tools, for fourteen in total. It appends rather than replaces, so everything above is unchanged for everyone who never opts in.

// PIPRAIL_MODE=sovereign, after the eight above
"piprail_quote_swap" · "piprail_swap" ·
"piprail_sell" · "piprail_collect" · "piprail_earnings" · "piprail_wallet"

Why swapping is withheld by default

The spend policy does not govern swaps. Every budget cap governs paying a merchant, while a swap moves your own funds between denominations, so PIPRAIL_MAX_AMOUNT, PIPRAIL_MAX_TOTAL and the count caps all pass over it untouched. An agent able to swap could drain a wallet through fees and slippage without tripping a single check.

Sovereign mode does not remove that problem, it bounds it with a different instrument: PIPRAIL_MAX_PER_SWAP is required, and the server refuses to start without it. A model can never grant itself the mode; the operator sets it in the environment.

Selling needs no ceiling, and no key

The seller tools take money rather than spending it, so no cap applies. The receiving side holds no private key at all (payTo is a public address), which is why earning is safe to grant a model where spending is not. See the earning half for the full contract.

piprail_discover

Find x402 payment-gated resources on the open indexes, a phone book of payable APIs, without paying. Use it to answer “what can I buy?”, then quote and pay a chosen one. All arguments are optional.

Argument	Type	Meaning
query	string	Free-text topic to search for.
network	string	CAIP-2 id, 'self' (your chain, the default), or 'any' (all chains).
category	string	Keep only this category. Strict: uncategorized results are dropped.
asset	string	Keep only resources paying in this token symbol, e.g. 'USDC'.
maxPrice	number	Drop results whose index-advertised price is above this number.
minReliability	number	Drop results below this health score (0 to 100); unscored results pass through.
verified	boolean	Prefer verified listings.
sort	string	'relevance' | 'reliability' | 'price' | 'uptime' | 'name'.
limit	number	Max results per index (default 20).

Returns { count, resources[] }, each resource carrying resource, name, description, source, priceUsd, category, reliabilityScore, health, verified, and the distinct networks it offers. priceUsd and maxPrice are the index’s own advertised metadata. PipRail has no price oracle, so always piprail_quote_payment the chosen resource for the live, true price before paying. It is read-only and open-world.

Tip

Discovery results are cross-scheme. Always call piprail_quote_payment on a chosen resource, which re-checks the live price, before piprail_pay_request. See Discover and register.

piprail_quote_payment

Price a gated URL without paying. Call it first to decide whether a resource is worth buying.

Argument	Type	Meaning
url	string (required)	Full URL of the gated resource.

Returns the quote (gated: true plus amount, token, chain, recipient, and whether it sits within your spend policy), or { gated: false, url } when the URL needs no payment. Carries an open outputSchema so a strict client can validate structuredContent.

{ "gated": true,
  "amountFormatted": "0.10", "symbol": "USDC", "asset": "0x…",
  "network": "eip155:8453", "payTo": "0xYourWallet",
  "withinPolicy": true }

piprail_plan_payment

Check whether you can pay before committing. It reads your wallet balance, native gas, and recipient readiness across every rail the URL offers on your chain. Call it before piprail_pay_request so you never start a payment you can’t finish.

Argument	Type	Meaning
url	string (required)	Full URL of the gated resource.

Returns { gated, payable, status, fundingHint, summary, best, options[] } (and session when a time policy is set). summary is one model-readable line distilling the whole plan; each options[] entry carries state, blockers, warnings, and recipientReady.

{ "gated": true, "payable": false, "status": "blocked",
  "fundingHint": "Can't settle on Base: top up 0.04 USDC (to pay 0.10 USDC).",
  "summary": "NOT payable: Can't settle on Base: top up 0.04 USDC (to pay 0.10 USDC).",
  "best": null,
  "options": [
    { "network": "eip155:8453", "symbol": "USDC", "amount": "0.10",
      "state": "blocked", "blockers": ["INSUFFICIENT_TOKEN"],
      "warnings": [], "recipientReady": "n/a" }
  ] }

The summary line comes verbatim from the SDK’s summarizePlan(). A payable plan instead reads "Payable: 0.10 USDC on eip155:8453 (gas ~0.00002 ETH). 1 other rail(s) not settleable." Gas is shown in the native coin only; there is no fiat figure.

Caution

payable: false means do not attempt the payment; fundingHint says exactly what to top up.

piprail_pay_request

The one tool that moves funds. It fetches the URL and makes the required payment if needed, subject to the spend policy and the approval hook. It pays whichever rail the client is configured for: PipRail’s backendless on-chain rail, or the standard exact rail when enabled. Its annotations mark it readOnlyHint: false, destructiveHint: true, idempotentHint: false.

It always hands the model a structured outcome, success or failure, never an exception. A settled fetch returns { status, ok, body, receipt, verifiableReceipt? }; anything that goes wrong (a refused payment, a server rejection, a broadcast that didn’t confirm) comes back as a structured { ok: false, … } object the agent can branch on. The two shapes are below.

Argument	Type	Meaning
url	string (required)	Full URL to fetch.
method	string	HTTP method, default GET.
body	object | string	Request body for POST/PUT. An object is JSON-serialised and sent with content-type: application/json set automatically; a string is sent verbatim with no content-type set.

On success it returns { status, ok, body, receipt, verifiableReceipt? }, where receipt is the parsed payment receipt if one settled. verifiableReceipt is present only when the gate emitted a verifiable-receipt extension: the PipRailReceipt JSON ({ piprail, receipt, resource, … }, where piprail is the literal string "1") stamped with the URL you fetched, which you keep and later re-check with piprail_verify_receipt.

{ "status": 200, "ok": true,
  "body": { "...": "the resource you paid for" },
  "receipt": { "transaction": "0x…", "network": "eip155:8453", "payer": "0xYourWallet" },
  "verifiableReceipt": { "piprail": "1", "receipt": { "...": "…" }, "resource": "https://…" } }

Every failure is structured, never a crash

This tool is the single funnel where every PipRailError reaches the model as a structured object instead of a thrown error, so the agent reasons about it rather than crashing. The fields are mutually contextual, populated by the kind of failure, so you’ll never see all of them on one object at once (a clean decline has no ref; a timeout has no declined):

{ "ok": false, "code": "INSUFFICIENT_FUNDS",
  "reason": "…", "explain": "…",
  "ref": "0x…",          // only on PAYMENT_TIMEOUT / MAX_RETRIES_EXCEEDED: the broadcast proof
  "reasonCode": "POLICY", // only on a decline
  "declined": true }      // only on a policy/approval refusal

Field	When present	Meaning
code	always	The stable PipRailError code. Branch on this.
reason	always	The error message.
explain	always	A one-line human explanation (explainDecline).
declined	policy / approval refusal	true, and no funds moved.
reasonCode	a decline	SESSION_EXPIRED, APPROVAL, OUTSIDE_WINDOW, POLICY, BUDGET. Some are terminal.
ref	PAYMENT_TIMEOUT / MAX_RETRIES_EXCEEDED	The on-chain proof of a broadcast-but-unconfirmed tx.

Danger

On PAYMENT_TIMEOUT, MAX_RETRIES_EXCEEDED, or CONFIRMATION_TIMEOUT, the payment may already be on-chain, so never re-pay or you double-spend. The first two carry the broadcast proof on .ref; CONFIRMATION_TIMEOUT does not carry .ref, so re-check the proof ref you already hold. The agent guide spells out every recovery case.

A genuine, non-SDK bug is the only thing that still surfaces as an MCP isError result.

Note

The MCP is the payer. When a payment is rejected by a merchant’s gate (wrong amount, expired, replayed, bad signature) that gate’s canonical VerifyErrorCode (the same code the merchant’s own onFailed hook receives) rides through to the model in this tool’s reason line, so both sides report one consistent cause. The top-level code here is the PipRailError code for the give-up condition (e.g. MAX_RETRIES_EXCEEDED). The MCP exposes only the buyer side, and onFailed is a server-gate (merchant) hook, so it is not an MCP tool. Building the seller? Wire onFailed into requirePayment / createPaymentGate.

piprail_register

List an x402 resource you run on the open indexes so other agents can find it. The default target is 402 Index: no auth, no signature, no payment. Moves no funds; nothing is PipRail-hosted.

Argument	Type	Meaning
url	string (required)	Full URL of the resource to list.
name	string	Display name (defaults to the host).
description	string	What the resource offers.
category	string	The top findability lever, since most listings have none. A real category ('ai', 'finance', …) makes a listing rank + filter.
tags	string[]	Keywords, folded into the description for search and sent as a tags field.
priceUsd	number	Advertised price (metadata).
network	string	Network slug to advertise, e.g. 'base' (defaults to the paying chain). Set it when registering from a multi-chain (PIPRAIL_CHAINS) wallet.
asset	string	Payment asset symbol, e.g. 'USDC' (metadata).
provider	string	Who runs the resource (provider/org name).
contactEmail	string	Contact email for the listing (also used by the domain claim).

Returns { outcomes[] }, one { source, ok, detail, visibility, note } per index; a step the chain can’t satisfy comes back ok: false with the reason.

Note

Index and agent payers are overwhelmingly standard exact clients. A default onchain-proof-only gate gets listed but they can’t pay it, so add an exact rail (and set the gate’s discovery option, required for x402scan) to be both discoverable and payable.

piprail_budget

Read how much of your spend budget and time leash is left: per (network, asset) remaining, the session time envelope, and your spend so far. Use it in Mode A (headless) to self-check before paying, so you never discover the leash by hitting a decline. Read-only and idempotent; takes no arguments.

Returns { spent, remaining, session, report, grandTotal, counts, policy }, where report is a formatted line of the spend ledger and the last three mirror the grand-total leash:

Field	Meaning
grandTotal	The per-denomination cross-token cap, one row per capped denomination ({ denom, spentFormatted, capFormatted, remainingFormatted, fraction }), present from the start. Empty when no maxTotalPerDenom is set.
counts	The payment-count leash: { settled, lifetimeCap?, lifetimeRemaining?, windowCap?, windowSettled?, windowRemaining? }. settled is always present; the caps appear only when maxPayments / maxPaymentsPerWindow are set.
policy	The configured spend policy read back, so the model sees the leash it’s bound by (undefined when none is set).

{ "spent": "0.10", "remaining": "19.90", "report": "…",
  "session": { "start": "2026-06-10T00:00:00Z", "expiresAt": "2026-06-10T02:00:00Z", "secondsRemaining": 3500 },
  "grandTotal": [
    { "denom": "USD", "spentFormatted": "0.10", "capFormatted": "20.00",
      "remainingFormatted": "19.90", "fraction": 0.005 }
  ],
  "counts": { "settled": 1, "lifetimeCap": 100, "lifetimeRemaining": 99 },
  "policy": { "maxTotalPerDenom": { "USD": "20.00" }, "maxPayments": 100 } }

The grand total is a user-declared unit-of-account sum, not a price oracle: tokens you group as one unit (USDC/USDT/… → USD) are summed 1:1; native and unknown tokens have no denomination and are never summed. It still spans chains when the server runs in multi-chain mode, because all chains share one ledger.

Note

By default, totals and the time envelope are in-memory for this process and reset on restart. Set PIPRAIL_SPEND_LOG to a path for a durable store, and grandTotal + counts resume after a restart, still a caller-owned file with no backend.

piprail_guide

Read the PipRail agent contract: the quote → plan → pay loop, how to read a refusal (and which declines are terminal), the never-re-pay rule, and Mode A vs Mode B. Read-only and idempotent; takes no arguments. Returns { guide }, the full PIPRAIL_AGENT_GUIDE string. Call it once if you’re unsure how to use these tools.

piprail_verify_receipt

Re-verify a PipRail verifiable receipt against the chain, confirming a payment really settled (the funds provably moved to payTo for at least the stated amount) without trusting whoever handed you the receipt. Read-only and wallet-free: pass the PipRailReceipt JSON from a prior piprail_pay_request verifiableReceipt, or any third party. Read-only and idempotent.

Argument	Type	Meaning
receipt	object (required)	The PipRailReceipt JSON ({ piprail, receipt, resource, decimals? }) to re-verify.
rpcUrl	string	Optional RPC URL for the receipt’s chain (required for chains outside the common presets).

Returns { ok, onChain: { payTo, asset, amount, payer }, matchesClaims, ageSeconds, error? }. ok is true when the chain confirms the settlement; onChain.payer is re-derived from the transaction, so matchesClaims: false means the receipt forged the payer; amount is a verified lower bound. It is read-only and open-world (it reads the on-chain tx via RPC). Unlike most tools it never throws: a chain or RPC problem comes back in the error field, never as an exception. It calls the static PipRailClient.verifyReceipt, so the same check is available wallet-free in code; see Verifying receipts and Verifiable receipts.

{ "ok": true,
  "onChain": { "payTo": "0xMerchant", "asset": "0x…", "amount": "100000", "payer": "0xBuyer" },
  "matchesClaims": true, "ageSeconds": 42 }

piprail_sell

Sovereign mode only. Price something and get the x402 challenge to hand a buyer. The challenge is data, so it travels over any channel the agent already has: no web server, no open port. Creates an in-session offer; moves no funds.

Argument	Type	Meaning
description	string	Required. What the buyer is paying for, and what the agent owes them.
price	string	Required. Human-readable, e.g. '2.50'.
token	string	What to be paid in. Defaults to USDC; native for the chain’s coin.
chain	string	Defaults to the chain the wallet is on.
payTo	string	Where the money goes. Defaults to the agent’s own address.
resource	string	Identifier or URL for the thing being sold. One is minted if omitted.

Returns { offerId, payTo, paidToYou, price, token, chain, schemes, challenge, next, warnings? }. schemes is what a buyer may actually use: an offer that resolves to onchain-proof only cannot be paid by an ordinary x402 agent-buyer, and that is reported in warnings rather than left silent. Offers live in memory for the session and are cleared by a restart.

piprail_collect

Sovereign mode only. Verify, against the chain, a payment a buyer claims to have made. This is the only thing that proves payment. A buyer’s word, a well-formed tx hash and a settled payment are three different things, and only this call tells them apart.

Argument	Type	Meaning
offerId	string	Required. The offer from piprail_sell.
payment	string	Required. What the buyer returned: the payment-signature header value, or the payload as JSON. Either form is accepted.

Returns { paid, earned, receipt, next } on success, or { paid: false, reason, retryChallenge }. Nothing should be delivered until paid is true.

Two bindings make one payment buy exactly one thing:

• A proof belongs to the offer it was minted for. A settlement presented against a different offer is refused with code: 'wrong_offer', checked before the chain is consulted. Without it, two offers at the same price to the same address are indistinguishable to any driver (both ask only “did this move at least X to this address?”), so a buyer could pay for the cheap one and collect the expensive one.
• A settlement is spent once, across every offer in the session. The used-proof set belongs to the seller, not to each offer, so redeeming a payment on one offer kills it on all of them.

piprail_earnings

Sovereign mode only. What the agent has sold and what it has actually been paid, the earning-side mirror of piprail_budget. Counts only payments proven by piprail_collect, never what a buyer claimed. Read-only, in-memory for the session.

Returns { offers, totals, collected, report }.

piprail_wallet

Sovereign mode only. What the agent HOLDS, and the address it gets paid at: the balance sheet, which is a different question from piprail_budget (how much of the allowance is left). Read-only.

Argument	Type	Meaning
assets	string[]	Symbols to report, e.g. ['native','USDC','USDT']. Defaults to the chain’s coin and USDC.

Returns { address, chain, holdings, report, next }. Each holding carries known (false when the chain does not ship that symbol) and an amount that is null when the read was unavailable, never 0. An agent must be able to tell “I hold nothing” apart from “I could not find out”, because acting on the second as if it were the first looks exactly like having been drained. On a multi-chain server the holdings span every chain the agent owns, not just the primary.

The guide prompt and resources

When the server is built with guide on (the default, since PIPRAIL_GUIDE off only suppresses it), two extra MCP surfaces are exposed alongside the tools. They are purely additive: with guide off, the tools path is byte-identical.

Surface	Kind	Content
piprail_agent_guide	prompt	The full agent contract: how to pay, reading a refusal, Mode A vs B.
piprail://guide	resource (text/markdown)	The same PIPRAIL_AGENT_GUIDE text.
piprail://budget	resource (application/json)	The live spend leash: { spent, remaining, grandTotal, counts, session, policy }, the same as the piprail_budget tool, minus the one-line report summary (the resource omits it).

The piprail://budget resource mirrors the running client’s budget, including the grand-total (grandTotal), payment-count leash (counts), and the configured policy read back (policy), so a client can poll the remaining leash as a resource read rather than a tool call. See Modes for how the guide and the confirm hook fit together.