elizaOS

elizaOS 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

Unlike the OpenClaw and Hermes integrations (which wire the @piprail/mcp server over stdio), elizaOS gets a native plugin — @piprail/elizaos-plugin. It wraps the SDK’s paymentTools directly into six elizaOS actions. It has no payment logic of its own — it delegates to the published @piprail/sdk, so the agent’s own key signs against your own RPC: self-custody, no facilitator, no fee, and a spend policy the model cannot exceed.

Setup

npm install @piprail/elizaos-plugin

List the plugin in your character and give it a funded wallet key + caps:

{
  "name": "PayBot",
  "plugins": ["@piprail/elizaos-plugin"],
  "settings": {
    "PIPRAIL_CHAIN": "base",
    "PIPRAIL_MAX_AMOUNT": "0.10",   // per-payment cap
    "PIPRAIL_MAX_TOTAL": "5.00",    // lifetime cap
    "secrets": { "PIPRAIL_PRIVATE_KEY": "0x-your-funded-key" }
  }
}

In a TypeScript character you can instead import { piprailPlugin } from '@piprail/elizaos-plugin' and put the object in plugins: [piprailPlugin]. See character.example.json.

Wallet required. The plugin needs PIPRAIL_PRIVATE_KEY (a self-custodial key) — every action validates against the wallet, so set it before the agent will offer any PipRail action. (For a key-less read-only mode — discover / quote / budget / guide with no wallet — use the MCP server instead, which boots read-only.)

Configure

The plugin reads these from the character’s settings / settings.secrets (via runtime.getSetting):

Setting	Required	Default	Purpose
`PIPRAIL_PRIVATE_KEY`	yes	—	Self-custodial wallet key (EVM `0x…`, Solana base58, …). Put it in `settings.secrets`. Every action requires it. Not an API key.
`PIPRAIL_CHAIN`	—	`base`	Which chain to pay on — any EVM, or `solana`/`ton`/`tron`/`near`/`sui`/`aptos`/`algorand`/`stellar`/`xrpl`.
`PIPRAIL_MAX_AMOUNT`	—	`0.10`	Max per payment → `policy.maxAmount`
`PIPRAIL_MAX_TOTAL`	—	`5.00`	Lifetime budget → `policy.maxTotal`

The plugin pays with schemes: ['onchain-proof', 'exact'], so it also settles standard x402 servers (gasless for the buyer on the exact rail). Full policy surface: Payment policy.

The actions

Action	Similes	What it does	Moves money?
`PIPRAIL_PAY`	PAY · BUY · PURCHASE	Pay a gated x402 URL and return the unlocked resource	yes
`PIPRAIL_QUOTE`	PRICE · HOW_MUCH · COST	Price a 402 URL without paying	no
`PIPRAIL_PLAN`	CAN_I_AFFORD · AFFORD	Check affordability + the cheapest rail	no
`PIPRAIL_DISCOVER`	FIND_API · SEARCH_X402	Find x402-payable APIs matching a query	no
`PIPRAIL_BUDGET`	SPENT · REMAINING	What’s been spent / what remains under the policy	no
`PIPRAIL_GUIDE`	HOW_TO_PAY · PAYMENT_HELP	Explain the payment tools + the spend policy	no

Only PIPRAIL_PAY moves funds — and it’s offered only when the message contains a URL. These wrap six of the eight PipRail tools; the programmatic piprail_register + piprail_verify_receipt stay available via @piprail/sdk or @piprail/mcp.

The agent workflow

discover → quote → plan → pay.

User:  Find me a crypto price API I can pay for.
Agent: [PIPRAIL_DISCOVER]  → 3 x402 resources found.
User:  Can I afford the first one?
Agent: [PIPRAIL_PLAN(url)]  → Payable — best rail: eip155:8453.
User:  Pay it.
Agent: [PIPRAIL_PAY(url)]  → Paid (tx 0x…). <resource>

Verify

Point the plugin at the live demo (0.01 USDC on Base):

Quote — PIPRAIL_QUOTE on https://piprail.com/x402/demo → Price: 0.01 USDC on eip155:8453.
Pay — PIPRAIL_PAY → Paid (tx 0x…). and the unlocked body.
Budget holds — set PIPRAIL_MAX_TOTAL below the price and confirm the agent is declined, no funds moved.

The runnable plugin lives at integrations/elizaos/piprail/ — npm run build, npm run typecheck, npm run smoke. It’s proven on Base mainnet by driving the plugin’s own action handlers (a real on-chain settle, the budget cap enforced).