CLI - BoltzPay

Install

npm
pnpm

npm install -g @boltzpay/cli

pnpm add -g @boltzpay/cli

Or run directly without installing:

npx @boltzpay/cli <command> [options]

Global Flags

Every command accepts these flags:

Flag	Short	Description
`--json`	`-j`	Output as a structured JSON envelope
`--verbose`	`-v`	Show protocol and timing details
`--debug`		Full request/response dump (to stderr)
`--version`	`-V`	Print version number
`--help`	`-h`	Print help text

boltzpay --json fetch https://invy.bot/api
boltzpay -v quote https://invy.bot/api

Commands

`fetch`

Detect the payment protocol, pay, and return the response body.

boltzpay fetch <url> [options]

Flag	Short	Default	Description
`--method <m>`	`-m`	`GET`	HTTP method
`--header <h>`	`-H`	—	Headers as `key:value` (repeatable)
`--data <body>`	`-d`	—	Request body
`--chain <c>`	`-c`	—	Force chain (`evm` or `svm`)

Human output:

$ boltzpay fetch https://invy.bot/api

Payment
  Protocol:  x402
  Amount:    $0.05
  Tx Hash:   0xabc123...

Response
  URL:       https://invy.bot/api
  Status:    200
  Type:      application/json

Body
{"holdings": [...]}

JSON output:

{
  "success": true,
  "data": "{\"holdings\": [...]}",
  "payment": {
    "protocol": "x402",
    "amount": "$0.05",
    "currency": "USD",
    "txHash": "0xabc123..."
  },
  "metadata": { "url": "https://invy.bot/api", "status": 200, "duration": 2345 }
}

`quote`

Check the cost of a paid endpoint without paying. No credentials needed.

boltzpay quote <url>

Human output:

$ boltzpay quote https://invy.bot/api

Quote
  Protocol:  x402
  Amount:    $0.05
  Currency:  USD
  Network:   eip155:8453 (Base)
  Alternatives:
    - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp (Solana) — $0.05

Prints This endpoint is free (no payment required) for free endpoints. JSON output (data field):

{
  "protocol": "x402",
  "amount": "$0.05",
  "currency": "USD",
  "network": "eip155:8453",
  "alternatives": [
    { "chain": "Solana", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "amount": "$0.05" }
  ]
}

`discover`

Browse paid API endpoints from the BoltzPay registry. Supports filtering by protocol, score, category, and free-text search.

boltzpay discover [options]

Flag	Short	Type	Description
`--category <category>`	`-c`	`string`	Filter by category
`--protocol <protocol>`	`-p`	`string`	Filter by protocol (`x402`, `l402`, `mpp`)
`--min-score <score>`		`number`	Minimum trust score (0-100)
`--query <query>`	`-q`	`string`	Search by name, URL, or description

Human output:

$ boltzpay discover --protocol x402 --min-score 70

BoltzPay Registry — Paid API Endpoints

  Invy — Token Holdings (score: 85)
    Token holdings lookup across Base, Ethereum, and Solana
    URL:   https://invy.bot/api
    Protocol: x402 | Category: crypto-data

12 endpoint(s) matching filters

JSON output (data is an array of entries):

[
  {
    "slug": "invy-token-holdings",
    "name": "Invy — Token Holdings",
    "url": "https://invy.bot/api",
    "protocol": "x402",
    "score": 85,
    "health": "healthy",
    "category": "crypto-data",
    "isPaid": true,
    "badge": "established"
  }
]

`budget`

Show remaining spending budget. No credentials needed.

boltzpay budget

Human output:

$ boltzpay budget

Budget Status

  Daily
    Spent:     $1.25 / $10.00
    Remaining: $8.75

  Per Transaction: max $1.00

Prints No budget limits configured if no limits are set. JSON output (data field):

{ "dailySpent": "$0.00", "dailyLimit": "$10.00", "dailyRemaining": "$10.00",
  "monthlySpent": "$0.00", "monthlyLimit": null, "monthlyRemaining": null,
  "perTransactionLimit": "$1.00" }

`history`

Show payment history. History is persistent when the SDK persistence option is enabled. No credentials needed.

boltzpay history

Human output:

$ boltzpay history

Payment History

  Date                 Protocol   Amount       Chain    URL
  ----------------------------------------------------------------------
  2026-02-19 14:30:00  x402       $0.05        Base     https://invy.bot/api

1 payment(s) total
By chain: Base $0.05

JSON output (data is an array):

[{ "url": "https://invy.bot/api", "protocol": "x402", "amount": "$0.05",
   "timestamp": "2026-02-19T14:30:00.000Z", "txHash": "0xabc...", "chain": "Base" }]

`demo`

Interactive walkthrough: checks your wallet, selects an appropriate endpoint (testnet or mainnet, x402 or L402), gets a quote, and optionally fetches with payment.

boltzpay demo [options]

Flag	Short	Default	Description
`--yes`	`-y`	—	Skip confirmation prompts
`--testnet`		—	Force testnet mode

Endpoints are selected based on wallet capabilities: L402 if NWC is configured, x402 if Coinbase keys are set, read-only otherwise.

`diagnose`

Full diagnostic of a paid API endpoint: DNS resolution, protocol detection, format version, pricing, health, and latency. No credentials needed.

boltzpay diagnose <url>

Human output:

$ boltzpay diagnose https://invy.bot/api

Endpoint Diagnosis
  URL:            https://invy.bot/api
  Classification: paid
  Protocol:       x402
  Format:         V2 header
  Scheme:         exact
  Health:         healthy
  Amount:         $0.05
  Network:        eip155:8453
  Latency:        234ms

JSON output (data field):

{
  "url": "https://invy.bot/api",
  "isPaid": true,
  "classification": "paid",
  "protocol": "x402",
  "formatVersion": "V2 header",
  "scheme": "exact",
  "health": "healthy",
  "amount": "$0.05",
  "network": "eip155:8453",
  "latencyMs": 234,
  "timing": { "detectMs": 120, "quoteMs": 114 }
}

`wallet`

Show wallet addresses, balances, network, active protocols, and budget status.

boltzpay wallet

Human output:

$ boltzpay wallet

Wallet & Configuration

  EVM address:    0x1234...abcd
  Solana address: 7xKX...9mNq
  Balance:        Base $12.50 · Solana $5.00
  Network:        base
  Protocols:      x402, l402
  Budget:         Daily: $8.75 remaining

JSON output (data field):

{
  "network": "base",
  "protocols": ["x402", "l402"],
  "addresses": { "evm": "0x1234...abcd", "svm": "7xKX...9mNq" },
  "balances": { "evm": "$12.50", "svm": "$5.00" },
  "budget": { "configured": true, "dailyLimit": "$10.00" }
}

JSON Output

The --json flag wraps every command’s output in a standard envelope:

{
  success: boolean;
  data: unknown;          // Command-specific payload
  payment: {              // Present on fetch, null otherwise
    protocol: string;
    amount: string;
    currency: string;
    txHash: string | null;
  } | null;
  metadata: {
    url: string;
    status: number;
    duration: number;     // Milliseconds
  };
}

On errors:

{
  "success": false,
  "error": {
    "code": "daily_budget_exceeded",
    "message": "Budget exceeded: requested $0.50, limit $5.00"
  }
}

Error codes map directly to exit codes and error classes. See the Errors section for the full list.

Exit Codes

Code	Meaning	Error class
`0`	Success	—
`1`	General / unknown error	Any unrecognized error
`2`	Configuration / credentials error	`ConfigurationError`
`3`	Budget exceeded	`BudgetExceededError`
`4`	Payment / protocol error	`ProtocolError`
`5`	Network error	`NetworkError`
`6`	Insufficient funds	`InsufficientFundsError`

Python Bridge

The CLI’s --json mode makes it trivial to call from Python (or any language). This is the recommended pattern for using BoltzPay with LangChain, CrewAI, or any Python framework.

import subprocess
import json


def boltzpay_fetch(url: str) -> dict:
    """Fetch a paid API endpoint via BoltzPay CLI."""
    result = subprocess.run(
        ["npx", "@boltzpay/cli", "fetch", url, "--json"],
        capture_output=True,
        text=True,
        check=True,
    )
    return json.loads(result.stdout)


def boltzpay_quote(url: str) -> dict:
    """Get a price quote for an endpoint (no keys needed)."""
    result = subprocess.run(
        ["npx", "@boltzpay/cli", "quote", url, "--json"],
        capture_output=True,
        text=True,
        check=True,
    )
    return json.loads(result.stdout)


# Example: quote then fetch
quote = boltzpay_quote("https://invy.bot/api")
print(f"Price: {quote['data']['amount']}")

data = boltzpay_fetch("https://invy.bot/api")
print(f"Response: {data['data']}")

Set environment variables (COINBASE_API_KEY_ID, etc.) in your shell before running. The CLI reads them automatically via process.env.

Error Handling in Python

import subprocess
import json


def boltzpay_fetch(url: str) -> dict:
    try:
        result = subprocess.run(
            ["npx", "@boltzpay/cli", "fetch", url, "--json"],
            capture_output=True,
            text=True,
        )
        data = json.loads(result.stdout)
        if not data.get("success"):
            error = data.get("error", {})
            raise RuntimeError(f"BoltzPay error [{error['code']}]: {error['message']}")
        return data
    except json.JSONDecodeError:
        raise RuntimeError(f"CLI failed (exit {result.returncode}): {result.stderr}")

Environment Variables

The CLI reads configuration from environment variables. A .env file in your working directory is loaded automatically.

Variable	Required	Description
`COINBASE_API_KEY_ID`	For payments	Coinbase CDP API key ID
`COINBASE_API_KEY_SECRET`	For payments	Coinbase CDP API key secret
`COINBASE_WALLET_SECRET`	For payments	Coinbase CDP wallet secret
`NWC_CONNECTION_STRING`	No	Enables L402 protocol
`BOLTZPAY_NETWORK`	No	`base` (default) or `base-sepolia`
`BOLTZPAY_DAILY_BUDGET`	No	Daily spending limit in USD
`BOLTZPAY_MONTHLY_BUDGET`	No	Monthly spending limit in USD
`BOLTZPAY_PER_TRANSACTION`	No	Per-transaction limit in USD
`TEMPO_PRIVATE_KEY`	No	Tempo wallet private key (enables MPP)
`STRIPE_SECRET_KEY`	No	Stripe secret key (enables Stripe MPP)

Read-only commands (quote, discover, diagnose, budget, history, wallet) work without Coinbase credentials. Only fetch requires them. See Configuration for constructor options, .env examples, and budget details.

​Install

​Global Flags

​Commands

​fetch

​quote

​discover

​budget

​history

​demo

​diagnose

​wallet

​JSON Output

​Exit Codes

​Python Bridge

​Error Handling in Python

​Environment Variables

Install

Global Flags

Commands

`fetch`

`quote`

`discover`

`budget`

`history`

`demo`

`diagnose`

`wallet`

JSON Output

Exit Codes

Python Bridge

Error Handling in Python

Environment Variables