SDK API reference

Introduction

This is the map of everything @piprail/sdk exports, grouped by the job it does, with the headline APIs marked and the advanced tiers (wire codecs, low-level exact, the driver SPI) kept clearly separate. Each group links to the page that documents it in full.

Two entry points cover the 99% case: requirePayment / createPaymentGate to get paid, and PipRailClient to pay. Everything else is built on those.

import { requirePayment, PipRailClient } from '@piprail/sdk'

Accept payments (server side)

The server-side surface. requirePayment is Express/Connect middleware; createPaymentGate is the same logic, framework-free.

Export	Kind	Marked
requirePayment	fn	Headline
createPaymentGate	fn	Headline
createPaywall, createTipJar	fn	Presets: named sugar over createPaymentGate (fixed-price paywall / pay-what-you-want tip jar). See Presets & self-test
toFetchHandler, toWorker, proxyTo	fn	Adapters for every fetch runtime: toFetchHandler (universal (request, …) => Response) + toWorker (the { fetch } export). proxyTo(origin) is a serve that forwards paid requests to an existing backend → gate any API. See Framework adapters
deliverReceipt	fn	Reliable receipt webhook: a signed + retried POST to your endpoint
toInvalidBody	fn	Deprecated
RequirePaymentOptions, AcceptOption, ExactRailOption	type	carries onPaid / onPaidError / awaitOnPaid and their failure mirrors onFailed / onFailedError / awaitOnFailed; mimeType (→ v2 resource.mimeType + the self-describe endpoint)
UptoRailOption	type	The createPaymentGate({ upto }) rail option: metered / variable-amount billing (buyer signs a MAX, you settle the actual ≤ max). See upto rail (seller)
ReceiptOption	type	The createPaymentGate({ receipt }) rail option: emit a signed, anyone-verifiable verifiable receipt alongside the response
ChainSelector, TokenInput	type
PaymentGate, VerifyPaymentResult	type
GateSelfTest	type	The result of gate.selfTest(): { ok, rails, warnings, error? } (read-only, never-throw config check)
PaywallOptions, TipJarOptions, Serve	type	The preset + adapter option types
PaidReceipt	type	The enriched receipt onPaid receives
FailedPayment	type	The failure object onFailed receives: { code, detail, transient } (the mirror of PaidReceipt)
DeliverReceiptOptions, DeliverAttempt, DeliverResult	type
X402InvalidBody	type
ExpressLike{Request,Response,Next,Middleware}	type

See requirePayment & createPaymentGate, Defining accepts, Verifying payments, and Receipts & onPaid (the PaidReceipt, onPaidError, awaitOnPaid, and deliverReceipt, plus the failure mirror onFailed / FailedPayment / onFailedError / awaitOnFailed, fired when a submitted proof is rejected).

Note

onFailed is the exact mirror of onPaid: it fires only when a SUBMITTED proof is rejected (a kind:'invalid' verdict from gate.verify(): wrong amount, expired, replayed, unknown asset, wrong recipient, bad signature, …), never on a normal no-proof first-request 402 and never when verify() throws (a transient RPC blip or a 5xx SettlementError isn’t a verdict). The FailedPayment it receives carries the SAME machine code the buyer’s client is told, so both sides see one consistent reason. transient is true only for the two transient codes (tx_not_found / insufficient_confirmations), so the proof may still be settling and the buyer auto-retries, so alert on !transient. See Why payments fail and VerifyErrorCode.

Pay (agent side)

The client. One PipRailClient binds a chain + wallet and exposes the read-only trio (quote → estimateCost → planPayment) plus fetch. MultiChainPayer carries one wallet per chain and auto-routes a 402 to whichever chain can settle it.

Export	Kind	Marked
PipRailClient	class	Headline
MultiChainPayer	class	Headline. One buyer, a wallet per chain
planAcross, fetchAcross	fn	plan / pay across an array of single-chain clients
PipRailClientOptions, MultiChainPayerOptions, WalletInput, PaymentScheme	type
PayingClient	type	the read-+-pay surface both PipRailClient and MultiChainPayer satisfy
PipRailQuote, PipRailCostQuote, PipRailEvent	type	the payment-failed event gained code? / detail? and ALSO fires on a pre-send DECLINE (policy / onBeforePay / no settleable rail)
PaymentPlan, PayOption, PayBlocker, PayWarning	type
SessionBudget, SpendRemaining	type
ReceiptVerification	type	The verdict returned by the static PipRailClient.verifyReceipt / PipRailClient.verifyAttestation. Re-verify a verifiable receipt against the chain, wallet-free (never throws). client.lastReceipt() returns the most recent one the client received.

See Quote, Estimate cost, planPayment(), fetch & autoRoute, Multi-chain buying, Events, and Wallets by family.

Tip

The payment-failed event (on onEvent) now carries an optional code? + detail?. On a server rejection that’s the SAME canonical code the merchant’s onFailed hook receives (a VerifyErrorCode); on a pre-send client decline it’s the decline reason (e.g. 'BUDGET' / 'APPROVAL' / 'MAX_AMOUNT'). payment-failed also fires on those pre-send declines now (policy, onBeforePay, or no settleable rail), where previously those only threw. The typed PaymentDeclinedError throw is unchanged and zero funds still move, so a consumer watching onEvent alone now learns of every failure type, not just server rejections. See Events.

Swapping tokens (optional)

Read Swapping tokens before using these. Nothing swaps automatically, and the spend policy does not govern swaps.

Export	Signature	Notes
client.quoteSwap	(req: SwapRequest) => Promise<SwapQuote | null>	Read-only. Never throws for a read problem: null means no quote, never no funds. A malformed slippageBps throws RangeError before any read.
client.swap	(quote: SwapQuote) => Promise<SwapReceipt>	Signs from your own wallet: one transaction, or two where a TRC-20/ERC-20 must be approved first. Asserts the chain’s own outcome before returning.
summarizeSwap	(q: SwapQuote) => string	One human sentence, always naming the rate’s source.
resolveSlippageBps	(bps?: number) => number	Validates and defaults. Throws RangeError on nonsense.
applySlippage	(amount: bigint, bps: number) => bigint	Pure, rounds up, integer only.
DEFAULT_SLIPPAGE_BPS	50	0.5%.
MAX_SLIPPAGE_BPS	1000	10% ceiling.

Types: SwapRequest, SwapQuote, SwapReceipt, SwapSide, SwapQuoteSource.

Agent mode: who may swap

Whether a model may swap is a question of authority, not of which package it imported.

Export	Type	What it is
AgentMode	'supervised' | 'budgeted' | 'sovereign'	Who is answerable for the wallet. Set once at construction; client.mode() reads it back and nothing writes it, so a model can never escalate itself.
DEFAULT_AGENT_MODE	'budgeted'	The default. Omit mode and the SDK behaves exactly as it did before modes existed, with the same eight tools.
AGENT_MODES	readonly AgentMode[]	Every valid mode, for validation and for surfaces that enumerate them.
SwapPolicy	{ maxPerSwap?, maxSlippageBps?, allowTo? }	The guardrail a payment cap cannot be. maxPerSwap is compared against the quote’s on-chain maxSpend, never the estimate.

paymentTools(client) returns the same eight tools in 'supervised' and 'budgeted'. 'sovereign' appends six: piprail_quote_swap, piprail_swap, the seller tools piprail_sell, piprail_collect and piprail_earnings, and piprail_wallet. It appends rather than replaces, so the default is untouched for anyone who does not opt in. client.canAgentSwap() and client.canAgentSell() are the one place each answer lives.

Every mode must be able to keep the promise its name makes, and the SDK checks this at construction.

Mode	What it grants	What it requires
supervised	the 8 tools	onBeforePay. It is the only thing that can pause a payment for a human, so without it the mode would be a label on a client that pays without asking anyone.
budgeted (default)	the 8 tools	nothing. The policy is the consent.
sovereign	14 tools	swapPolicy.maxPerSwap, in the SDK and the MCP alike. A payment cap counts payments, and a swap is not one, so sovereign is bounded by a different instrument. Selling needs no ceiling: it takes money rather than spending it.

// Supervised: a human is genuinely in the loop, or construction fails.
const supervised = new PipRailClient({
  chain: 'base',
  wallet: { key: process.env.KEY },
  mode: 'supervised',
  onBeforePay: async (quote) => askTheHuman(quote),   // required, and it is the supervision
})

// Sovereign: the agent owns its wallet, both halves of it.
const agent = new PipRailClient({
  chain: 'base',
  wallet: { key: process.env.KEY },
  mode: 'sovereign',
  swapPolicy: { maxPerSwap: '25.00', maxSlippageBps: 100 },
})

Export	Signature	Notes
onBeforeSwap	(quote: SwapQuote) => boolean | Promise<boolean>	Approve or refuse a swap before anything is signed. onBeforePay genuinely never sees a swap (a swap is not a payment), so without this a supervised sovereign agent could swap its whole balance without one prompt. Same fail-safe contract: false or a throw refuses, as PaymentDeclinedError with reasonCode: 'APPROVAL'. @piprail/mcp wires it alongside onBeforePay whenever confirmation is on.
client.address()	() => Promise<string>	Where this wallet gets paid. Derived from the key, no RPC read. An agent handed a key it never chose has no other way to learn its own address, and piprail_sell defaults payTo to it.
client.balanceOf(assets?)	(assets?: readonly string[]) => Promise<WalletAssetBalance[]>	What the wallet can spend, per asset: the balance sheet, distinct from budget() (how much allowance is left). Never throws for a read problem: an unavailable read is null, never 0, so an agent can tell “I hold nothing” from “I could not find out”. On a MultiChainPayer it spans every chain. 🔴 For a native asset on a chain with a retained minimum this is lower than the figure an explorer shows; see the note below.
WalletAssetBalance	{ symbol, asset, decimals, known, amount, amountFormatted }	One holding. amount is the spendable base-unit figure. known: false means the chain does not ship that symbol, reported rather than guessed at.

Spendable is not the same as held

Solana, the XRP Ledger, Stellar and Algorand each make an account retain a minimum it can never send: Solana’s rent exemption, XRPL’s base plus owner reserve, Stellar’s base reserve per subentry, Algorand’s minimum balance. Since 3.1.0 a native balance reports that reserve deducted, because measuring affordability against the raw balance calls a payment affordable right up until the chain refuses it, which is the one thing planPayment() exists to prevent.

Measured live on mainnet:

Chain	The account holds	balanceOf reports	Locked reserve
Stellar (3 subentries)	1.5398 XLM	0.0398 XLM	1.5 XLM
XRP Ledger (2 owned objects)	2.3810 XRP	0.9810 XRP	1.4 XRP

The difference is locked, not lost. Spend against this number; estimateCost() judges gas against the true balance separately. Where a chain has no such minimum the two are equal.

| client.canAgentSell() | () => boolean | May a model price offers and collect for them? Sovereign only. | | client.chain() | () => ChainSelector | The chain this client is configured for. |

The coverage map

Plain data, no network calls. Same shape and same admission rule as KNOWN_FACILITATORS: an entry earns its place only after a real mainnet swap settled through it.

Export	Signature	Notes
SWAP_PROVIDERS	readonly SwapProviderEntry[]	The registry. Every entry carries dated, verifiable transaction hashes.
swapProvidersFor	(network: Caip2) => readonly SwapProviderEntry[]	Routes on one network; empty array when none.
canSwapOn	(network: Caip2) => boolean	The boolean form.
swappableNetworks	() => readonly Caip2[]	Every network with a proven route, deduped and sorted.

Types: SwapProviderEntry, SwapProof.

The website’s swap table is generated from this map (node site/scripts/gen-swap-providers.mjs), so the page can never drift from the SDK.

SwapQuoteSource.kind is 'protocol' (the ledger itself swapped, no third party) or 'provider' (a named keyless router). Always read it before trusting a rate.

Spend controls

The policy + ledger primitives. evaluatePolicy is the pure decision function the client and MCP both call before any spend. The ledger + store are how caps survive a restart and span chains and still no backend, no database, no fee: SpendLedger is in-memory and a SpendStore is a caller-owned file (or anything you implement).

Export	Kind	Marked
evaluatePolicy	fn	Headline
SpendLedger	class	Share one across several clients for a cross-chain grand total (MultiChainPayer.fromWallets wires it for you)
memorySpendStore	fn	A SpendStore backed by an in-memory array: memorySpendStore(seed?); from @piprail/sdk
fileSpendStore	fn	A durable JSONL SpendStore: fileSpendStore(path); from @piprail/sdk/node (Node-only, keeps node:fs out of the browser bundle)
denomOf	fn	Pure. denomOf(symbol, asset, policy) → the unit a token folds into, or none
BUILTIN_DENOMS, DENOM_PRECISION	const	the built-in symbol→unit map (USDC/USDT/USD1/FDUSD/U/RLUSD → 'USD', EURC → 'EUR') and the fixed-point precision (24)
PaymentPolicy, PaymentIntent, PolicyDecision, PolicyDenyCode	type	PaymentPolicy gained maxTotalPerDenom / denomFor / maxPayments / maxPaymentsPerWindow / warnAtFraction; PolicyDenyCode gained MAX_TOTAL_DENOM / MAX_PAYMENTS / WINDOW_COUNT
SpendStore	type	{ load(): SpendRecord[]; append(record): void }. Pass as the client’s spendStore to persist the ledger (never throws)
SpendRecord, SpendSummary, SpendAssetTotal, SpendDenomTotal	type	SpendSummary gained byDenom: SpendDenomTotal[]; SpendRecord gained optional decimals / denom
DenomRemaining, CountStatus	type	the per-denomination remaining row + the payment-count status SessionBudget now also reports

See Payment policy, Total budget, Time envelope, evaluatePolicy(), and Spend ledger.

Agent toolkit

paymentTools(client) returns the tool set an autonomous LLM drives; the renderers and guide make a bound client legible to the model.

Export	Kind	Marked
paymentTools	fn	Headline
AgentTool, ToolAnnotations	type
summarizePlan, explainDecline, formatSpendReport, describeChallenge	fn
PIPRAIL_AGENT_GUIDE, agentGuide	const / fn
classifyChallenge	fn
ChallengeTriage, ChallengeVerdict	type
buildSelfDescription, buildEndpointInfo, BRAND	fn / const	the extensions.piprail self-description builder, the endpoint sub-block assembler, + brand single-source-of-truth
SelfDescription, SelfDescribeRail, SelfDescribeEndpoint	type	the self-describe block, a rail in it, and the agent-readable endpoint (summary/input/output)

See Payment tools, The agent tools, Renderers, Agent guide, and Challenge triage.

Chains

CHAINS is the built-in EVM mainnet registry (each preset carries its canonical token addresses); resolveChain turns a chain value into a ResolvedChain.

Export	Kind
CHAINS, resolveChain	const / fn
ChainInput, ChainName, ResolvedChain	type
ChainPreset, TokenInfo	type

See Chains overview and Chains & tokens.

Discovery

Be found, and find others, on the open x402 indexes, with nothing PipRail-hosted. The builders are pure (emit static artifacts); the register* / searchOpenIndexes functions talk to the free public directories.

Export	Kind
buildOpenApi, buildWellKnownX402, buildWellKnownX402Manifest, buildX402DnsTxt, buildBazaarExtension, GENERATOR	fn / const
discoveryHeaders, POWERED_BY, renderLandingPage	fn / const
searchOpenIndexes, register402Index, registerX402Scan	fn
claim402IndexDomain, verify402IndexDomain	fn
normalizeNetwork, getDirectoryInfo, decorateOutcome, DIRECTORY_INFO	fn / const
rankResources, scoreResource	fn
appendKeywords	fn
appendAttribution, REGISTER_ATTRIBUTION	fn / const
PaymentRail, ResourceDescription, ManifestInput	type
OpenApiDocument, OpenApiOperation, WellKnownX402, WellKnownX402Manifest, WellKnownX402Item, X402DnsRecord	type
DiscoveryDescriptor, BazaarExtension	type
DiscoverySource, DiscoverySort, DiscoveredRail, DiscoveredResource	type
RegisterOutcome, RegisterInput, SearchOpenIndexesOptions	type
DirectoryInfo, ListingVisibility, DomainClaim, DomainVerification	type
DiscoverOptions, RegisterOptions	type

See Discover & register, Open indexes, Emitters, and Domain verification.

Errors

Every thrown error is a typed PipRailError subclass with a stable .code.

Export	Kind
PipRailError	class (base)
InsufficientFundsError, RecipientNotReadyError	class
WrongChainError, WrongFamilyError, UnknownTokenError	class
InvalidConfigError	class
MissingDriverError, UnsupportedNetworkError, UnsupportedSchemeError	class
PaymentTimeoutError, ConfirmationTimeoutError, MaxRetriesExceededError	class
PaymentDeclinedError, InvalidEnvelopeError, NoCompatibleAcceptError	class
NonReplayableBodyError, SettlementError, WalletRequiredError	class
toInsufficientFundsError	fn
DeclineReasonCode	type

See Error model, Error hierarchy, VerifyErrorCode, and Why payments fail.

Advanced: wire codecs

The raw envelope codecs, for building a client or server by hand. PipRailClient and createPaymentGate cover the 99% case, so reach for these only when you’re hand-rolling the wire format (server: buildChallengeHeader → verify → buildReceiptHeader; client: parseChallenge → buildSignatureHeader → parseReceipt).

Export	Kind
pickAccept	fn
parseChallenge, parseReceipt, parseReceiptExtension, parseSettleResponse	fn
parseSignatureHeader, parseExactPaymentHeader, parseUptoPaymentHeader	fn
parseSignatureObject, parseExactObject, parseUptoObject, decodeBase64Json	fn: the object-accepting parser cores the base64 header parsers wrap, for a transport that carries the SAME payload as raw JSON (A2A), fed via gate.verifyObject
buildChallengeHeader, buildSignatureHeader, buildExactSignatureHeader, buildUptoSignatureHeader, buildReceiptHeader	fn
buildReceiptExtension, EXT_OFFER_RECEIPT	fn / const
buildPaymentIdentifierAdvertisement, readPaymentIdentifier, EXT_PAYMENT_IDENTIFIER	fn / const
HEADER_REQUIRED, HEADER_SIGNATURE, HEADER_RESPONSE, HEADER_SIGNATURE_V1, HEADER_RESPONSE_V1	const
Caip2, AssetId, AddressId	type
VerifyResult, VerifyErrorCode	type
X402AcceptEntry, X402ExactAcceptEntry, X402UptoAcceptEntry, X402AnyAccept, X402Challenge	type
X402PaymentSignature, X402Receipt, X402ResourceObject, SettleOutcome	type
PipRailReceipt, SignedReceipt	type
ExactAuthorizationWire, ExactPaymentPayload, ExactPaymentPayloadAny, ParsedExactPayment	type
Permit2Authorization, Permit2PaymentPayload, Permit2UptoAuthorization, Permit2UptoPaymentPayload, ParsedUptoPayment	type

See Wire codecs and VerifyErrorCode.

Advanced: low-level exact (EVM: EIP-3009 + Permit2)

The standard x402 exact scheme at the codec tier. For the high-level paths use PipRailClient({ schemes: ['exact'] }) (buyer) or createPaymentGate({ exact }) (seller). These exports are for hand-rolled clients, v1 servers, and custom flows. The exact scheme has six asset-transfer methods: EIP-3009 (transferWithAuthorization, on EVM tokens that implement it) and Permit2 (for EVM ERC-20s that don’t, e.g. Binance-Peg USDC/USDT on BNB), plus SVM (Solana: any SPL token, the merchant is the fee payer), Algorand, Aptos, and NEAR on their respective L1s. The codecs in the table below are the EVM tier (EIP-3009 + Permit2); the non-EVM payloads, SVM’s { transaction } shape (ExactSvmPaymentPayload), Algorand (ExactAlgorandPaymentPayload), Aptos (ExactAptosPaymentPayload) and NEAR (ExactNearPaymentPayload), are built and verified inside their respective drivers. They are variants of the exported ExactPaymentPayloadAny union (reached via ParsedExactPayment), not importable individually. See Gasless payments.

Export	Kind	Note
parseExactRequirements, chainIdForExactNetwork, encodeXPaymentHeader	fn	EVM tier
readExactDomain, eip3009Abi	fn / const	reads/uses a token’s true on-chain EIP-712 domain (EVM)
EXACT_NETWORK_SLUGS, EIP3009_TYPES	const
PERMIT2_ADDRESS, X402_EXACT_PERMIT2_PROXY, PERMIT2_WITNESS_TYPES	const	Permit2 method: the canonical Permit2 + x402ExactPermit2Proxy + witness types
PERMIT2_PROXY_CHAIN_IDS, isPermit2ProxyChain	const / fn	EVM chains where the x402 Permit2 proxy is deployed (where the Permit2 exact method can settle)
buildExactAuthorization	fn	Deprecated, because it trusts the server-supplied domain
ExactAccept, ExactAuthorization, BuildExactParams	type
Permit2Authorization, Permit2PaymentPayload, ExactPaymentPayloadAny	type	the per-method wire payloads (EIP-3009 / Permit2 / SVM / Algorand / Aptos / NEAR); ParsedExactPayment is a union on method ('eip3009'/'permit2'/'svm'/'algorand'/'aptos'/'near')

Advanced: upto rail (EVM, metered / variable-amount Permit2)

The upto (metered) scheme: the buyer signs a Permit2 witness transfer for a MAX, and the merchant settles the actual (≤ max) after serving. EVM-Permit2 only. The high-level paths are createPaymentGate({ upto }) (seller) and PipRailClient({ schemes: ['onchain-proof', 'upto'] }) (buyer). These constants are the canonical proxy + witness types, for reference and advanced use. The proxy (vanity …0002, distinct from the exact …0001) is BOTH the signature spender and the seller’s settle contract.

Export	Kind	Note
X402_UPTO_PERMIT2_PROXY	const	The canonical x402 upto Permit2 proxy address (vanity …0002).
UPTO_PROXY_CHAIN_IDS, isUptoProxyChain	const / fn	EVM chains where the upto Permit2 proxy is deployed (where the upto rail can settle).
PERMIT2_UPTO_WITNESS_TYPES	const	The EIP-712 witness type set for the upto Permit2 signature.

See the upto rail (seller) page for how to wire it.

Advanced: A2A transport (x402 over Google Agent2Agent)

The seller-side A2A adapter, the A2A analogue of requirePayment. Wrap a PaymentGate and map A2A Task/Message metadata ⇄ x402’s existing envelopes, backendless: zero driver/scheme/chain changes, so every family rides A2A for free. The raw-JSON dispatch seam it relies on, gate.verifyObject, is a method on the already-exported PaymentGate.

Export	Kind	Note
createA2APaymentHandler	fn	Headline (A2A). Wrap a PaymentGate into an A2A payment handler.
toA2APaymentRequired, toA2APaymentReceipts, toA2APaymentFailed	fn	Map an x402 challenge / receipts / failure into A2A Task/Message metadata.
fromA2APaymentRequired, fromA2APaymentPayload	fn	Read an A2A payment-required / payment payload back out of A2A metadata.
toA2AErrorCode, VERIFY_CODE_TO_A2A_ERROR	fn / const	Map a VerifyErrorCode to its A2A error code.
A2A_X402_EXTENSION_URI_V01, A2A_X402_EXTENSION_URI_V02	const	The x402-over-A2A extension URIs (v0.1 / v0.2).
A2A_STATUS_KEY, A2A_REQUIRED_KEY, A2A_PAYLOAD_KEY, A2A_RECEIPTS_KEY, A2A_ERROR_KEY	const	The A2A metadata keys the envelopes ride on.
A2A_EXTENSIONS_HEADER	const	The HTTP header that activates the A2A x402 extension.
A2APaymentHandler, A2APaymentHandlerOptions	type	the handler + its options
A2AArtifact, A2AExtensionDeclaration, A2AMessage, A2AMetadata, A2APart, A2APaymentStatus, A2ATask, A2ATaskRecord, A2ATaskState, A2ATaskStore	type	the A2A wire types

See A2A transport.

Advanced: x402-over-MCP transport (the third official transport)

The seller-side MCP adapter, the MCP analogue of requirePayment / createA2APaymentHandler. Carry x402’s existing envelopes over MCP tool calls instead of HTTP headers, backendless: verify/settle/ replay all run through the gate’s verifyObject (zero new crypto, zero driver/scheme/chain changes), so every family rides MCP for free.

Export	Kind	Note
createMcpPaymentTool	fn	Headline (MCP). Wrap a PaymentGate as a paid MCP tool. A fulfill() throw after settle still returns a success _meta payment-response, never a re-challenge (B7 at-most-once).
toMcpPaymentRequired, toMcpPaymentResponse	fn	Build the 402-challenge (isError + structuredContent + a byte-equal content[0].text) and the settled tool result.
fromMcpPayment, fromMcpPaymentRequired, fromMcpPaymentResponse, isMcpPaymentRequired	fn	Buyer/seller read helpers. Pull the payment / challenge / settlement out of an MCP message.
buildMcpPaymentMeta	fn	Frame an already-produced { accepted, payload } into the retry call’s params._meta["x402/payment"].
MCP_PAYMENT_META_KEY, MCP_PAYMENT_RESPONSE_META_KEY	const	The spec _meta keys (x402/payment / x402/payment-response, with a slash, not A2A’s dot).
McpPaymentTool, McpPaymentToolOptions, McpContentBlock, McpToolCallParams, McpToolResult, McpPaymentMeta	type	the MCP wire types (duck-typed; zero @modelcontextprotocol/sdk dependency)

A fully-automatic McpPayer (the buyer side) is a documented fast-follow, exactly as A2A shipped seller-first. See MCP transport (seller).

Advanced: exact facilitator (Mode B), facilitator.js

The Mode-B facilitator path (createPaymentGate({ exact: { settle: { facilitator } } })) delegates verify + settle to a third-party facilitator you choose. PipRail hosts nothing.

Export	Kind	Note
settleViaFacilitator	fn	Run the two-POST verify→settle contract against a facilitator URL.
parseFacilitatorSupported, facilitatorCoverage	fn	Read a facilitator’s GET /supported → which (scheme, network) pairs it settles (never throws).
KNOWN_FACILITATORS, knownFacilitatorsFor, firstKeylessFacilitator	const / fn	The keyless-facilitator coverage data map (which keyless facilitator settles exact on a network).
FacilitatorConfig	type	The facilitator’s base url + optional authHeaders provider.
FacilitatorPaymentRequirements	type	The trusted exact requirements posted to the facilitator.
SettleViaFacilitatorInput, FacilitatorSupportedKind, KnownFacilitator	type	input to settleViaFacilitator; the /supported kinds; a coverage-map entry.

See the exact rail (seller) page for how to wire it, and Facilitator coverage for the keyless-facilitator data map.

See Low-level exact, exact rail (seller), and exact (buyer).

Advanced: driver SPI

Bring your own chain family. registerDriver adds a family that implements the PaymentDriver contract; the rest are the contract’s types.

Export	Kind
registerDriver	fn
PaymentDriver, ChainFamily	type
ReceiptInput	type
ResolvedNetwork, ResolveOptions, ResolvedToken, CostEstimate	type
WalletHandle, WalletBalance, DiscoverySigner, ConfirmInfo	type
RecipientReason	type
EvmToken, SolanaToken, TonToken, StellarToken, XrplToken	type
TronToken, NearToken, SuiToken, AptosToken, AlgorandToken	type

See Driver SPI and PaymentDriver architecture.

Note

The public API is exactly what @piprail/sdk re-exports from its entry point. Anything reachable only by deep-importing an internal module is not part of the contract and may change without a major version bump.