CLI

@x402r/cli makes a single x402 payment from the command line. You point it at an address, provide a signer, and get back the response body plus a settlement transaction hash. The CLI carries zero provider SDK dependencies. Raw private keys, JSON-RPC signers (Privy, Turnkey, Fireblocks, Safe), and custom signer modules all work through the same interface.

Install

npx @x402r/cli pay <url> [options]

pnpm dlx @x402r/cli pay <url> [options]

bunx @x402r/cli pay <url> [options]

No project install required. Pin the version (for example, @x402r/cli@0.2.0) for reproducible scripted workflows.

Usage

x402r pay <url> [signer flags] [--chain <eip155:id>] [--rpc <url>] [--max-amount N] [--json]

If the endpoint does not return HTTP 402, the CLI short-circuits and prints the response body with exit code 0. The CLI sends no payment.

Signer configuration

Configure exactly one signer source. CLI flags take precedence over environment variables. If the CLI finds zero or more than one source, it exits with code 6.

Source	Flag	Environment variable
Raw private key	`--key 0x...`	`PRIVATE_KEY`
Remote JSON-RPC	`--signer-url <url>` and `--signer-address 0x...`	`SIGNER_URL` and `SIGNER_ADDRESS`
Custom module	`--signer-module <pkg-or-path>`	`SIGNER_MODULE`

Environment variable names use no X402R_ prefix to match Foundry, Hardhat, and x402-reference conventions.

Request options

Flag	Description
`--chain <eip155:id>`	Select a specific `accepts[]` entry when the merchant offers more than one chain. Required when more than one option exists.
`--asset-transfer-method <eip3009\|permit2>`	Select the token-collection path when the chosen `accepts[]` entry supports both EIP-3009 and Permit2. Required when more than one option exists.
`--rpc <url>`	Override the RPC endpoint for on-chain reads. Required for chain IDs not in `viem/chains`.
`--max-amount <n>`	Refuse to pay more than `n` atomic token units. Exits with code 3 if the price exceeds this.
`--json`	Emit a single JSON envelope to stdout instead of plain text.

Supported chains

The CLI reads the chain from the 402 response’s accepts[].network field. Any EVM chain known to viem/chains works, including Base and Base Sepolia. For chain IDs viem/chains does not recognize, pass --rpc <url> with an RPC endpoint.

Exit codes

Code	Meaning
0	Success
1	Network error
2	Malformed 402 response or unusable `accepts[]`
3	Price exceeds `--max-amount`
4	Signature rejected
5	Settlement failed (merchant error after payment, or facilitator error)
6	Signer resolution failed (none, more than one, or incomplete configuration)

Examples

Raw private key

PRIVATE_KEY=0xabc123... npx @x402r/cli pay https://api.example.com/paid-endpoint

JSON-RPC signer

Any endpoint that speaks eth_signTypedData_v4 works: Privy wallet RPC, Turnkey, Fireblocks, Safe, a local cast wallet endpoint, or a hardware wallet behind an RPC bridge.

npx @x402r/cli pay https://api.example.com/paid-endpoint \
  --signer-url https://signer.example/rpc \
  --signer-address 0x586486394C38A2a7d36B16a3FDaF366cd202d823

Custom module (Privy)

privy-signer.js

import { PrivyClient } from "@privy-io/server-auth";
import { createViemAccount } from "@privy-io/server-auth/viem";

export default async function () {
  const privy = new PrivyClient(
    process.env.PRIVY_APP_ID,
    process.env.PRIVY_APP_SECRET
  );
  return createViemAccount({
    walletId: process.env.PRIVY_WALLET_ID,
    address: process.env.PRIVY_WALLET_ADDRESS,
    privy,
  });
}

npx @x402r/cli pay https://api.example.com/paid-endpoint \
  --signer-module ./privy-signer.js

Custom module (Coinbase CDP)

cdp-signer.js

import { CdpClient } from "@coinbase/cdp-sdk";
import { toAccount } from "viem/accounts";

export default async function () {
  const cdp = new CdpClient();
  const acct = await cdp.evm.getOrCreateAccount({
    name: process.env.CDP_ACCOUNT_NAME,
  });
  return toAccount(acct);
}

npx @x402r/cli pay https://api.example.com/paid-endpoint \
  --signer-module ./cdp-signer.js

JSON output

With --json, the CLI writes a single JSON envelope to stdout:

{
  "body": "<merchant response body>",
  "status": 200,
  "tx": "0x...",
  "elapsedMs": 1234,
  "signer": { "kind": "key", "address": "0x..." }
}

The CLI drops the signer field when the endpoint returned a non-402 response (the CLI sent no payment).

Signer module contract

A custom signer module must default-export a factory function with the signature () => Promise<Account>. The returned object must be a viem Account with at least address and signTypedData. The CLI only needs typed-data signatures; the facilitator broadcasts the transaction.

Programmatic usage

You can also use the pay function and resolveSigner directly from TypeScript:

import { pay } from "@x402r/cli";
import type { PayResult } from "@x402r/cli";

const result: PayResult = await pay({
  url: "https://api.example.com/paid-endpoint",
  key: process.env.PRIVATE_KEY,
  json: true,
});

console.log(result.body);
console.log(result.tx);

The programmatic API uses the same PayFlags interface as the CLI binary. All options (chain, rpc, maxAmount, signer flags) are available.

Exports

The @x402r/cli package exports:

Export	Type	Description
`pay`	function	Execute a one-shot payment against an endpoint
`resolveSigner`	function	Resolve a signer from flags and environment variables
`CliError`	class	Base error class with typed exit codes
`NetworkError`	class	Exit code 1
`Malformed402Error`	class	Exit code 2
`MaxAmountExceededError`	class	Exit code 3
`SignatureRejectedError`	class	Exit code 4
`SettlementError`	class	Exit code 5
`SignerResolutionError`	class	Exit code 6

Install

Usage

Signer configuration

Request options

Supported chains

Exit codes

Examples

Raw private key

JSON-RPC signer

Custom module (Privy)

Custom module (Coinbase CDP)

JSON output

Signer module contract

Programmatic usage

Exports

Next steps

Merchant guide

Examples

​Install

​Usage

​Signer configuration

​Request options

​Supported chains

​Exit codes

​Examples

​Raw private key

​JSON-RPC signer

​Custom module (Privy)

​Custom module (Coinbase CDP)

​JSON output

​Signer module contract

​Programmatic usage

​Exports

​Next steps

Merchant guide

Examples

Install

Usage

Signer configuration

Request options

Supported chains

Exit codes

Examples

Raw private key

JSON-RPC signer

Custom module (Privy)

Custom module (Coinbase CDP)

JSON output

Signer module contract

Programmatic usage

Exports

Next steps