Piprail
About
Hand any AI agent a budget-capped wallet to pay, discover & register x402 payment-gated URLs across every chain. Local, self-custodial, no backend, no fee.
Details
- Author
- piprail
- Downloads
- 324
- Categories
- Finance, Other, API
Jump to
- Five tools for the full x402 payment lifecycle.
- Budget-capped wallet enforced before any on-chain send.
- Supports every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar, and XRP Ledger.
- Works with USDC, USDT, and native coin across chains.
- Wallet key never leaves your machine — no back end or custody.
- Runs locally with no facilitator and no additional fee.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
PiprailCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Run npx -y @piprail/mcp, add the config block (set your wallet key and spend caps via environment variables like PIPRAIL_MAX_AMOUNT, PIPRAIL_MAX_TOTAL, PIPRAIL_TOKENS, PIPRAIL_HOSTS, and PIPRAIL_CHAIN), then restart your client. The server exposes five tools for discovering, quoting, planning, paying, and registering x402 endpoints.
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?" — search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.
piprail_quote_payment
Get the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.
piprail_plan_payment
Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive — across every rail the URL offers on your chain — and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.
piprail_pay_request
Fetch an x402 payment-gated URL, automatically making the required payment if needed (subject to the spend policy + approval hook). Pays whichever rail the client is configured for — PipRail's backendless on-chain rail, or, when enabled, the standard `exact` rail (where the buyer signs and the server settles, so no buyer gas). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } — no funds moved.
piprail_register
List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index — no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted. NOTE: index/agent payers are overwhelmingly standard `exact` clients — a default onchain-proof-only gate gets listed but they cannot pay it, so add an `exact` rail (and set the gate's `discovery` option, required for x402scan) to be usefully discoverable AND payable.
piprail_budget
Read how much of your spend budget and time leash is left — per (network, asset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much USD you can still spend across every stablecoin and chain), the payment-count leash, 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; moves no funds. NOTE: the time envelope is in-memory for THIS process; the money/count totals persist only if a spend store is configured.
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 for broadcast-but-unconfirmed payments, and Mode A (headless) vs Mode B (supervised). Read-only; call it once if unsure how to use these tools.
piprail_verify_receipt
Re-verify a PipRail VERIFIABLE RECEIPT against the chain — confirm 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). Returns { ok, onChain:{payTo,asset,amount,payer}, matchesClaims, ageSeconds, error? }: `ok` = the chain confirms the settlement; `onChain.payer` is RE-DERIVED from the tx and `matchesClaims:false` means the receipt forged the payer; `amount` is a verified lower bound. Pass `rpcUrl` for a chain outside the common presets.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"piprail": {
"piprail": {
"command": "npx",
"args": [
"-y",
"@piprail/mcp"
],
"env": {
"PIPRAIL_PRIVATE_KEY": "<YOUR_WALLET_KEY>",
"PIPRAIL_CHAIN": "base",
"PIPRAIL_MAX_AMOUNT": "0.10",
"PIPRAIL_MAX_TOTAL": "10.00",
"PIPRAIL_TOKENS": "USDC"
}
}
}
}
}McpServers
{
"piprail": {
"command": "npx",
"args": [
"-y",
"@piprail/mcp"
],
"env": {
"PIPRAIL_PRIVATE_KEY": "<YOUR_WALLET_KEY>",
"PIPRAIL_CHAIN": "base",
"PIPRAIL_MAX_AMOUNT": "0.10",
"PIPRAIL_MAX_TOTAL": "10.00",
"PIPRAIL_TOKENS": "USDC"
}
}
}Let any HTTP endpoint charge for itself, and any agent pay for itself — across every major chain, in a couple of lines.
The middle is the difference.A traditional processor holds the money in transit, takes days to release it, and can freeze or reverse it. PipRail removes the middle entirely — the agent pays the merchant's wallet directly, the merchant verifies it locally against their own RPC, and it settles in one transaction at0% fee, self-custodial end to end.See it on piprail.com →
Opensright here in your browser— no download, GitHub renders it inline. 16 slides · every stat sourced in the speaker notes.
The whole thesis in one read:whyagent payments are happening now,whychain & token fragmentation is the enemy, andhowa singlechain:parameter turns PipRail into the universal adapter. The payment path is0% forever— the moatandthe distribution; value accrues to the layer around the free rail, never the rail itself.
Source.pptx(fully editable, brand fonts embedded) lives in.claude/skills/branding/design/deck/. The rootPipRail-deck.pdfis regenerated from it — don't hand-edit the PDF.
The single, searchablesource of truth— every function, option, chain, and example. This README is just the front door.
import { requirePayment } from '@piprail/sdk' app.get('/report', requirePayment({ chain: 'base', token: 'USDC', amount: '0.05', payTo: '0xYourWallet…' }), (_req, res) => res.json({ report: 'TOP SECRET' }), )
That route now costs0.05 USDC on Base, paid straight to your wallet. Point an agent at it and it pays itself — name any chain with a singlechain:parameter. The full quickstart, every chain, the MCP server, spend controls, and the error model are in thedocs.
- docs.piprail.com— the complete manual (source of truth)
- MCP server·Discovery·Supported chains
- Integrations— drop PipRail into agent frameworks:OpenClaw,Hermes,elizaOS,n8n&Mastra(more coming)
- Runnable examples— merchant + agent demos, a live Anvil end-to-end, and thewhy-402teardown
- Releasing(tag-driven CI) ·Contributing(DCO)
PipRail is free, open-source, and has no backend to sell you — so word of mouth is how it grows. If it saved you from building a payments backend, the best way to give back is to help other developers (and their agents) find it:
- ⭐Star PipRail on GitHub— the #1 way to help others discover it
- 𝕏Follow @piprailhq— new chains, ship logs, and agent-payment tips
- 🌐piprail.com· 📖docs.piprail.com
Code:MIT— use it, fork it, ship it, commercially or otherwise.
Name & brand:PipRail™, the logo, and the@piprailnpm scope are trademarks of the PipRail project — MIT covers thecode, not thename. Build on it freely; just don't call a fork "PipRail" or imply it's official. SeeTRADEMARK.md.
Built for the agent economy ·piprail.com
AI intelligence oracle + cross-border settlement rail. 10-layer Stability Oracle (climate, macro, FX, ESG) with x402 pay-per-call API. USDC/EURC settlement on Base at 1.385% all-in.
Remote MCP for paid API discovery, API invocation, USDC agent payments, and receipts.
One x402/developer-credit control layer for paid AI/data tool calls, crypto conversion quotes, public MCP discovery, progress streaming, and receipt-backed agent spend governance.
MCP/x402 spend layer for AI agents to quote, pay for, invoke, stream, and receipt paid AI/API calls with crypto or developer credits.
121 pay-per-call API tools for AI agents — crypto, weather, finance data via x402 micropayments (USDC on Base). Each call costs $0.001-$0.05.
MCP server exposing 90+ crypto API tools with automatic x402 USDC micropayment handling — gas oracle, token lookup, wallet risk analysis, market mood, and more on Base.
100 x402 micropayment APIs / MCP servers for AI agents. Pay-per-call USDC on Base, no signup. Composable in 6 use-case bundles.
The financial infrastructure for autonomous AI. Equips Claude and other agents with secure, programmable USDC smart accounts (ERC-4337). Tools exposed: get_balance, transfer_usdc, get_history. Features: Abstracted gas fees (Paymasters), native USDC settlement on Base, and strict developer-defined spending limits (Policy-as-Code) to eliminate LLM hallucination liability.
Domain-agnostic x402 capability chassis: 26 pay-per-call MCP capabilities (market data, on-chain, security, dev tools) with USDC micropayments on Base — no API key required.
Self Hosted Payment gateway for agents, openclaw, hermes and more
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
