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
toInvalidBody	fn	Deprecated
RequirePaymentOptions, AcceptOption, ExactRailOption	type	—
ChainSelector, TokenInput	type	—
PaymentGate, VerifyPaymentResult	type	—
X402InvalidBody	type	—
ExpressLike{Request,Response,Next,Middleware}	type	—

See requirePayment & createPaymentGate, Defining accepts, Verifying payments, and Receipts & onPaid.

Pay (agent side)

The client. One PipRailClient binds a chain + wallet and exposes the read-only trio (quote → estimateCost → planPayment) plus fetch.

Export	Kind	Marked
PipRailClient	class	Headline
planAcross	fn	Headline
PipRailClientOptions, WalletInput, PaymentScheme	type	—
PipRailQuote, PipRailCostQuote, PipRailEvent	type	—
PaymentPlan, PayOption, PayBlocker, PayWarning	type	—
SessionBudget, SpendRemaining	type	—

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

Spend controls

The policy + ledger primitives. evaluatePolicy is the pure decision function the client and MCP both call before any spend.

Export	Kind	Marked
evaluatePolicy	fn	Headline
PaymentPolicy, PaymentIntent, PolicyDecision, PolicyDenyCode	type	—
SpendRecord, SpendSummary, SpendAssetTotal	type	—

See Payment policy, 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	fn	—
PIPRAIL_AGENT_GUIDE, agentGuide	const / fn	—
classifyChallenge	fn	—
ChallengeTriage, ChallengeVerdict	type	—

See Payment tools, The 7 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, buildX402DnsTxt, buildBazaarExtension, GENERATOR	fn / const
searchOpenIndexes, register402Index, registerX402Scan	fn
claim402IndexDomain, verify402IndexDomain	fn
normalizeNetwork, getDirectoryInfo, decorateOutcome, DIRECTORY_INFO	fn / const
PaymentRail, ResourceDescription, ManifestInput	type
OpenApiDocument, OpenApiOperation, WellKnownX402, X402DnsRecord	type
DiscoveryDescriptor, BazaarExtension	type
DiscoverySource, 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
MissingDriverError, UnsupportedNetworkError, UnsupportedSchemeError	class
PaymentTimeoutError, ConfirmationTimeoutError, MaxRetriesExceededError	class
PaymentDeclinedError, InvalidEnvelopeError, NoCompatibleAcceptError	class
NonReplayableBodyError, SettlementError	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 — 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, parseSettleResponse	fn
parseSignatureHeader, parseExactPaymentHeader	fn
buildChallengeHeader, buildSignatureHeader, buildExactSignatureHeader, buildReceiptHeader	fn
HEADER_REQUIRED, HEADER_SIGNATURE, HEADER_RESPONSE, HEADER_SIGNATURE_V1, HEADER_RESPONSE_V1	const
Caip2, AssetId, AddressId	type
VerifyResult, VerifyErrorCode	type
X402AcceptEntry, X402ExactAcceptEntry, X402AnyAccept, X402Challenge	type
X402PaymentSignature, X402Receipt, X402ResourceObject, SettleOutcome	type
ExactAuthorizationWire, ExactPaymentPayload, ParsedExactPayment	type

See Wire codecs and VerifyErrorCode.

Advanced: low-level exact (EVM, EIP-3009)

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.

Export	Kind	Note
parseExactRequirements, chainIdForExactNetwork, encodeXPaymentHeader	fn	—
readExactDomain, eip3009Abi	fn / const	reads/uses a token’s true on-chain EIP-712 domain
EXACT_NETWORK_SLUGS, EIP3009_TYPES	const	—
buildExactAuthorization	fn	Deprecated — trusts the server-supplied domain
ExactAccept, ExactAuthorization, BuildExactParams	type	—

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.
FacilitatorConfig	type	The facilitator’s base url + optional authHeaders provider.
FacilitatorPaymentRequirements	type	The trusted exact requirements posted to the facilitator.
SettleViaFacilitatorInput	type	Full input to settleViaFacilitator (config + payload + receipt fields).

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

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
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.