Give an OpenClaw agent an x402 wallet

OpenClaw 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 OpenClaw as a standard MCP server, the published @piprail/mcp (npx -y @piprail/mcp). OpenClaw spawns it over stdio, the agent gets all the PipRail tools natively, and a spend policy the model cannot exceed is baked in. There’s no bespoke plugin to build or maintain: the integration is the MCP server plus one config entry.

Setup

Add PipRail to ~/.openclaw/openclaw.json. OpenClaw nests MCP servers under mcp.servers (not a top-level mcpServers), and you can manage the block with openclaw mcp set / openclaw mcp list:

{
  "mcp": {
    "servers": {
      "piprail": {
        "command": "npx",
        "args": ["-y", "@piprail/mcp"],
        "env": {
          "PIPRAIL_CHAIN": "base"
        }
      }
    }
  }
}

No key needed. This is the whole config and it boots read-only (discover/quote/register/budget/guide all work). Add PIPRAIL_PRIVATE_KEY plus a cap (PIPRAIL_MAX_TOTAL) only when you want the agent to actually pay:

{
  "mcp": {
    "servers": {
      "piprail": {
        "command": "npx",
        "args": ["-y", "@piprail/mcp"],
        "env": {
          "PIPRAIL_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
          "PIPRAIL_CHAIN": "base",
          "PIPRAIL_MAX_AMOUNT": "0.10",
          "PIPRAIL_MAX_TOTAL": "5.00",
          "PIPRAIL_TOKENS": "USDC"
        }
      }
    }
  }
}

Restart OpenClaw and the piprail_* tools appear. You can also discover PipRail on ClawHub with clawhub install piprail, which carries this same setup.

Configure

Variable	Required	Default	Purpose
`PIPRAIL_PRIVATE_KEY`	only to pay	none	Self-custodial wallet key/seed (EVM `0x…`, Solana base58, or a mnemonic). Omit it for read-only, since discover/quote/register/budget/guide still work. Not an API key.
`PIPRAIL_CHAIN`	no	`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`	no	none	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`	no	`0.10`	Max per payment, in the token’s units (≈ $ for USDC/USDT; native-coin units on a `native` rail)
`PIPRAIL_MAX_TOTAL`	no	`10.00`	Lifetime budget per token; in multi-chain mode, per chain+token
`PIPRAIL_TOKENS`	no	chain stables	Allowed tokens, comma-separated
`PIPRAIL_SCHEMES`	no	`onchain-proof`	Add `exact` to also pay standard x402 servers
`PIPRAIL_RPC_URL`	no	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. 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.

Verify

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

The runnable skill folder lives at integrations/openclaw/piprail/: SKILL.md, an example openclaw.json, and .env.example.