Hermes

Hermes (NousResearch) agents get a budget-bound payment wallet with PipRail: they can pay x402-gated APIs, data feeds, and AI services on their own, across every supported chain — and they cannot spend more than the cap you set.

How it works

PipRail plugs into Hermes as a standard MCP server — the published @piprail/mcp (npx -y @piprail/mcp). Hermes spawns it over stdio, the agent gets all the PipRail tools (namespaced mcp_piprail_*, e.g. mcp_piprail_piprail_pay_request — Hermes prefixes the server name, so the piprail_pay_request tool surfaces as mcp_piprail_piprail_pay_request; the doubled prefix is expected, not a typo), and a spend policy the model cannot exceed is baked in. There’s no bespoke plugin to build — Hermes is Python and @piprail/sdk is TypeScript, so the MCP server is the integration, plus one config entry.

Hermes has no native payment rail

Nous Portal is fiat-subscription only — there’s even an open RFC for an agent wallet (Issue #38280). PipRail is the drop-in answer: backendless, no fee, self-custodial, every chain — funds settle straight to the provider’s wallet, verified locally against your own RPC.

Setup

Quickest — one command. Adds the server and (after a quick “enable all tools?” prompt) saves it to ~/.hermes/config.yaml:

hermes mcp add piprail --command npx --args -y @piprail/mcp

Once the catalog entry lands it gets shorter still — hermes mcp install piprail. Or wire it by hand — Hermes nests MCP servers under the top-level mcp_servers key in ~/.hermes/config.yaml:

mcp_servers:
  piprail:
    command: "npx"
    args: ["-y", "@piprail/mcp"]
    enabled: true
    env:
      PIPRAIL_PRIVATE_KEY: "${PIPRAIL_PRIVATE_KEY}"   # from ~/.hermes/.env
      PIPRAIL_CHAIN: "base"
      PIPRAIL_MAX_AMOUNT: "0.10"
      PIPRAIL_MAX_TOTAL: "5.00"
      PIPRAIL_TOKENS: "USDC"
    tools:
      prompts: false
      resources: false
      include:
        - piprail_discover
        - piprail_quote_payment
        - piprail_plan_payment
        - piprail_pay_request
        - piprail_register
        - piprail_budget
        - piprail_guide
        - piprail_verify_receipt

Run /reload-mcp in a session (or start a new one) and the mcp_piprail_* tools appear.

Danger

Two secret gotchas. Hermes does not inherit your shell environment into the subprocess, so PIPRAIL_PRIVATE_KEY must be in the server’s env: block — otherwise pay stays WALLET_REQUIRED. Keep the literal key in ~/.hermes/.env (chmod 600) and reference it as ${PIPRAIL_PRIVATE_KEY} — Hermes expands ${VAR} but not bare $VAR. Never commit the key.

Read-only first run: omit the key and PipRail boots key-less — discover/quote/register/budget/guide all work; only pay/plan need the wallet.

There’s also a skill

Beyond the MCP server (which is what actually pays), PipRail ships a small Hermes skill — usage guidance for the agent. It’s discoverable with hermes skills search piprail, or add the tap directly: hermes skills tap add piprail/skills. The skill only teaches the quote → plan → pay workflow — install the MCP server above to get the tools.

Configure

Variable	Required	Default	Purpose
PIPRAIL_PRIVATE_KEY	only to pay	—	Self-custodial wallet key/seed (EVM 0x…, Solana base58, or a mnemonic). Omit it for read-only — discover/quote/register/budget/guide still work. Not an API key.
PIPRAIL_CHAIN	—	base	Which chain to pay on — any EVM, or solana/ton/tron/near/sui/aptos/algorand/stellar/xrpl. NEAR also requires PIPRAIL_NEAR_ACCOUNT_ID to pay (e.g. you.near).
PIPRAIL_CHAINS	—	—	Pay across several chains (instead of PIPRAIL_CHAIN) — e.g. base,polygon,solana, each with its own PIPRAIL_<CHAIN>_KEY; pays whichever chain a 402 asks for. See Configuration.
PIPRAIL_MAX_AMOUNT	—	0.10	Max per payment, in the token’s units (≈ $ for USDC/USDT; native-coin units on a native rail)
PIPRAIL_MAX_TOTAL	—	10.00	Lifetime budget per token; in multi-chain mode, per chain+token
PIPRAIL_TOKENS	—	chain stables	Allowed tokens, comma-separated
PIPRAIL_SCHEMES	—	onchain-proof	Add exact to also pay standard x402 servers
PIPRAIL_RPC_URL	—	chain default	Custom RPC (recommended in production)

Defaults are deliberately small and safe (0.10 per payment, 10.00 lifetime, USDC on Base). The full env reference is on the Configuration page; the wallet key format your chain expects is in Wallets by family.

The tools

Tool	What it does	Moves money?
piprail_discover	Find payable x402 APIs on the open indexes	no
piprail_quote_payment	Get a URL’s price without paying	no
piprail_plan_payment	Check you can afford it (balance + gas + recipient-ready)	no
piprail_pay_request	Pay the 402 and return the resource	yes
piprail_register	List your own x402 API so other agents find it	no
piprail_budget	Read remaining spend + time leash	no
piprail_guide	Read the agent contract (quote → plan → pay)	no
piprail_verify_receipt	Re-verify a receipt against the chain (wallet-free)	no

Only piprail_pay_request moves funds; in Hermes they surface as mcp_piprail_*. To let the agent read and plan but never auto-spend, drop piprail_pay_request from the server’s tools.include. Full reference: the tools.

The agent workflow

discover → quote → plan → pay.

User:  Find me a crypto price API I can pay for.
Agent: [piprail_discover("crypto price")]  → cheapest is 0.001 USDC/call on Base.
User:  Can I afford it?
Agent: [piprail_plan_payment(url)]  → yes; 4.82 USDC left of 5.00, recipient ready, gas ~$0.05.
User:  Get me the ETH price.
Agent: [piprail_pay_request(url)]  → paid 0.001 USDC (tx 0x…). ETH: $3,247.18. 4.819 USDC left.

Discover & publish

PipRail is added to Hermes two ways — both PRs into NousResearch/hermes-agent:

1. MCP catalog (primary) — a optional-mcps/piprail/manifest.yaml entry makes hermes mcp install piprail work natively, carrying the “Nous-approved” label.
2. Skills Hub — a SKILL.md published via hermes skills publish, or contributed to optional-skills/.

Both ship in the runnable folder below.

Verify

1. Quote the live demo — piprail_quote_payment("https://piprail.com/x402/demo") returns a real price (0.01 USDC on Base).
2. Pay it — piprail_pay_request("https://piprail.com/x402/demo") returns a 200 + a receipt.
3. Budget holds — set PIPRAIL_MAX_TOTAL below the price and confirm the agent is refused (declined: true), no funds moved.

The runnable folder lives at integrations/hermes/piprail/ — manifest.yaml (the catalog entry), config.yaml, SKILL.md, .env.example, and a zero-dep verify.mjs (node verify.mjs --live).

See also

• MCP overview · Client setup · Tools
• Spend controls — how the cap is enforced
• Chains — every chain PipRail supports