x402-proxy

curl for x402 and MPP paid APIs with MCP proxy support. Auto-pays HTTP 402 on Base, Solana, and Tempo.

Zero crypto code on the buyer side. One mnemonic derives both EVM (Base/Tempo) and Solana keypairs - fund any chain and go. Supports one-time payments (x402, MPP charge) and pay-per-token streaming (MPP sessions). Use it as a CLI, an MCP proxy for AI agents, or as a Node.js library.

Table of Contents

• Install
• Usage
• Commands
• MCP Proxy
• Wallet
• Env Vars
• Library Usage
• OpenClaw Plugin
• Contributing
• License

Install

npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw

That's it. The endpoint returns 402, x402-proxy pays and streams the response.

No wallet? It'll walk you through setup automatically. One mnemonic derives both EVM (Base/Tempo) and Solana keypairs. Fund any chain and go.

Usage

Works like curl. Response body streams to stdout, payment info goes to stderr.

# GET request
$ npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw

# POST with body and headers (curl-style short flags: -X, -H, -d)
$ npx x402-proxy -X POST \
  -H "Content-Type: application/json" \
  -d '{"url":"https://x402.org"}' \
  https://surf.cascade.fyi/api/v1/web/crawl

# Force a specific network
$ npx x402-proxy --network base https://api.example.com/data

# Debug protocol negotiation and payment flow
$ npx x402-proxy --verbose https://api.example.com/data

# Use MPP protocol for streaming payments
$ npx x402-proxy --protocol mpp \
  -X POST -H "Content-Type: application/json" \
  -d '{"model":"minimax/minimax-m2.5","stream":true,"messages":[{"role":"user","content":"Hello"}]}' \
  https://surf.cascade.fyi/api/v1/inference/v1/chat/completions

# Pipe-safe
$ npx x402-proxy https://api.example.com/data | jq '.results'

Commands

$ npx x402-proxy <url>                    # paid HTTP request (default command)
$ npx x402-proxy serve                    # local paid inference proxy server
$ npx x402-proxy claude                   # run Claude Code through a paid local proxy
$ npx x402-proxy mcp <url>                # MCP stdio proxy for agents
$ npx x402-proxy mcp add <name> <url>     # install MCP server into your AI client
$ npx x402-proxy setup                    # onboarding wizard
$ npx x402-proxy status                   # config + wallet + spend summary
$ npx x402-proxy config                   # show current configuration
$ npx x402-proxy config set <key> <value> # set a config value
$ npx x402-proxy config unset <key>       # remove a config value
$ npx x402-proxy wallet                   # show addresses and balances
$ npx x402-proxy wallet history           # payment history
$ npx x402-proxy wallet export-key <target> # bare key/mnemonic to stdout (evm|solana|mnemonic)

All commands support --help for details. Use -c <dir> to override the config directory.

MCP Proxy

Let your AI agent consume any paid MCP server.

Quick setup

npx x402-proxy mcp add surf https://surf.cascade.fyi/mcp

Auto-detects installed AI clients (Claude Code, Cursor, VS Code, and 16+ others), shows a config preview, and writes it for you. Runs wallet setup if needed.

Manual config

Or add to your client config directly:

{
  "mcpServers": {
    "surf": {
      "command": "npx",
      "args": ["-y", "x402-proxy", "mcp", "https://surf.cascade.fyi/mcp"]
    }
  }
}

The proxy auto-generates a wallet on first run and uses ~/.config/x402-proxy/wallet.json. No env vars needed. Your agent never touches crypto.

For OpenClaw:

openclaw mcp set surf '{"command":"npx","args":["-y","x402-proxy","mcp","https://surf.cascade.fyi/mcp"]}'

Wallet

A single BIP-39 mnemonic derives both chains:

• Solana: SLIP-10 Ed25519 at m/44'/501'/0'/0'
• EVM: BIP-32 secp256k1 at m/44'/60'/0'/0/0

Config stored at $XDG_CONFIG_HOME/x402-proxy/ (default ~/.config/x402-proxy/).

Export keys for other tools

# Pipe-safe - outputs bare key/mnemonic to stdout
$ MY_KEY=$(npx x402-proxy wallet export-key evm)
$ MY_MNEMONIC=$(npx x402-proxy wallet export-key mnemonic)

Env Vars

Override wallet per-instance (fallback for environments where the wallet file isn't accessible):

X402_PROXY_WALLET_MNEMONIC     # BIP-39 mnemonic (derives both chains)
X402_PROXY_WALLET_EVM_KEY      # EVM private key (hex)
X402_PROXY_WALLET_SOLANA_KEY   # Solana private key (base58)

Resolution order: flags > env vars > mnemonic env > wallet.json file.

Library Usage

import {
  createX402ProxyHandler,
  createMppProxyHandler,
  extractTxSignature,
  detectProtocols,
  appendHistory,
  readHistory,
  calcSpend,
} from "x402-proxy";

See the library API docs for details.

OpenClaw Plugin

The OpenClaw plugin ships as a separate npm package: x402-proxy-openclaw.

openclaw plugins install x402-proxy-openclaw

It gives your gateway automatic x402 and MPP payment capabilities. Registers x_wallet and x_request tools (aliased as x_balance/x_payment), /x_wallet and /x_send commands, and an HTTP route proxy for upstream inference endpoints.

By default, the plugin registers a built-in surf provider at /x402-proxy/v1 that points at https://surf.cascade.fyi/api/v1/inference and prefers MPP. Uses the standard wallet resolution (env vars or wallet.json).

For MPP-backed inference, make sure the wallet source includes an EVM key as well as Solana. npx x402-proxy setup does this automatically.

Contributing

PRs welcome. Feel free to open an issue for bug reports or feature requests.

License

Apache-2.0 (c) Cascade Protocol