x402-proxy

curl for x402 paid APIs. Auto-pays HTTP 402 responses with USDC on Base and Solana - zero crypto code on the buyer side.

Quick Start

npx x402-proxy https://twitter.surf.cascade.fyi/user/cascade_fyi

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) and Solana keypairs. Fund either chain and go.

MCP Proxy

Let your AI agent consume any paid MCP server. Configure in Claude, Cursor, or any MCP client:

{
  "mcpServers": {
    "paid-service": {
      "command": "npx",
      "args": ["x402-proxy", "mcp", "https://mcp.example.com/sse"],
      "env": {
        "X402_PROXY_WALLET_MNEMONIC": "your 24 words here"
      }
    }
  }
}

The proxy sits between your agent and the remote server, intercepting 402 responses, paying automatically, and forwarding the result. Your agent never touches crypto.

HTTP Requests

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

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

# POST with body and headers
$ npx x402-proxy --method POST \
  --header "Content-Type: application/json" \
  --body '{"url":"https://x402.org"}' \
  https://web.surf.cascade.fyi/v1/crawl

# 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 mcp <url>                # MCP stdio proxy for agents
$ npx x402-proxy setup                    # onboarding wizard
$ npx x402-proxy status                   # config + wallet + spend summary
$ 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.

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 (useful for MCP configs):

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,
  extractTxSignature,
  appendHistory,
  readHistory,
  calcSpend,
} from "x402-proxy";

See the library API docs for details.

License

Apache-2.0