CLI Reference

The x402cli tool provides command-line access to x402-protected resources and facilitator services.

Installation

# Build from source
go build ./cmd/x402cli

# Or run directly
go run ./cmd/x402cli <command> [flags]

Commands

x402cli
├── browse       Fetch the /.well-known/x402 discovery document
├── check        Check if a resource requires payment
├── pay          Pay for a resource with a payment payload
├── supported    Query facilitator for supported schemes/networks
├── verify       Verify a payment payload via facilitator
├── settle       Settle a payment payload via facilitator
├── payload      Generate a payment payload with EIP-3009 authorization
├── req          Generate a payment requirements object
└── proof
    ├── gen      Generate an ownership proof signature
    └── verify   Verify an ownership proof signature

---

browse

Fetch the /.well-known/x402 discovery document from a server. Returns the list of x402-protected endpoint URLs and optional metadata.

x402cli browse -u https://api.example.com
x402cli browse -u https://api.example.com -o discovery.json

Flags:

Flag	Description
-u, --url	Base URL of the server (required)
-o, --output	File path to write JSON output (default: stdout)

Example output:

{
  "version": 1,
  "resources": [
    "https://api.example.com/api/data",
    "https://api.example.com/api/premium"
  ],
  "ownershipProofs": [
    "0xabc123...",
    "0xdef456..."
  ],
  "instructions": "This API provides premium data. Pay per request."
}

---

check

Check if a resource requires x402 payment. Outputs the full PaymentRequired JSON response if the resource returns 402.

x402cli check -u <url>
x402cli check -u <url> -m POST
x402cli check -u <url> -o requirements.json

Flags:

Flag	Description
-u, --url	URL of the resource to check (required)
-m, --method	HTTP method, GET or POST (default: GET)
-d, --data	Request body data (optional)
-o, --output	File path to write JSON output (default: stdout)

---

pay

Pay for a resource by sending a request with a PAYMENT-SIGNATURE header. Constructs the full PaymentPayload from the inner payload and requirements, base64 encodes it, and sends it to the resource server.

x402cli pay -u <url> -p <json|file> --req <json|file>
x402cli pay -u <url> -m POST -p payload.json --req requirements.json -d '{"key":"value"}'

Flags:

Flag	Description
-u, --url	URL of the resource (required)
-m, --method	HTTP method, GET or POST (default: GET)
-p, --payload	Inner payload as JSON or file path (required, output of payload command)
-r, --req, --requirements	PaymentRequirements as JSON or file path (required)
-d, --data	Request body as JSON string or file path (optional)
-o, --output	File path to write response body (default: stdout)

On success (200), prints the response body and decodes the PAYMENT-RESPONSE settlement header to stderr. On 402, prints the PaymentRequired JSON.

---

supported

Query a facilitator for its supported schemes, networks, and signers.

x402cli supported -u <url>

Flags:

Flag	Description
-u, --url	Facilitator URL (required)

Example output:

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:84532"
    }
  ],
  "extensions": [],
  "signers": {
    "eip155:8453": ["0xYourSignerAddress"],
    "eip155:84532": ["0xYourSignerAddress"]
  }
}

---

verify

Verify a payment payload against a facilitator. Takes a payload object and requirements object (as JSON strings or file paths).

x402cli verify -u <facilitator-url> -p <json|file> -r <json|file>

Flags:

Flag	Description
-u, --url	Facilitator URL (required)
-p, --payload	Payload object as JSON or file path (required)
-r, --req, --requirements	Payment requirements as JSON or file path (required)

---

settle

Settle a payment payload via a facilitator. Same interface as verify, but calls /settle.

x402cli settle -u <facilitator-url> -p <json|file> -r <json|file>

Flags:

Flag	Description
-u, --url	Facilitator URL (required)
-p, --payload	Payload object as JSON or file path (required)
-r, --req, --requirements	Payment requirements as JSON or file path (required)

---

payload

Generate a payment payload with EIP-3009 authorization. Optionally signs with a private key.

x402cli payload --to <address> --value <amount> [options]
x402cli payload --req requirements.json --private-key 0x...

Flags:

Flag	Description
--to	Recipient address (required)
--value	Amount in smallest unit (required)
--private-key	Hex private key for EIP-712 signing
--from	Payer address (derived from key if omitted)
--asset	Token contract address (required with --private-key)
--name	EIP-712 domain name (required with --private-key)
--version	EIP-712 domain version (required with --private-key)
--chain-id	Chain ID (required with --private-key)
-r, --req, --requirements	PaymentRequirements as JSON or file path
--valid-after	Unix timestamp (default: now)
--valid-before	Unix timestamp (default: now + 10min)
--valid-duration	Seconds, alternative to --valid-before
--nonce	Hex bytes32 nonce (default: random)
-o, --output	File path to write output (default: stdout)

When --req is provided, the requirements object populates default values:

• --to from payTo
• --value from amount
• --asset from asset
• --name from extra.name
• --version from extra.version
• --chain-id from network

Individual flags always override values from requirements.

---

req

Generate a payment requirements object, either from individual flags or by fetching from a resource server.

# Generate from flags
x402cli req --scheme exact --network eip155:8453 --amount 1000000

# Fetch from resource server
x402cli req -u http://localhost:3000/api/data
x402cli req -u http://localhost:3000/api/data -m POST -d '{"key":"value"}'
x402cli req -u http://localhost:3000/api/data -i 1 --amount 5000 -o requirements.json

Flags:

Flag	Description
-u, --url	URL of resource to fetch requirements from
-m, --method	HTTP method when fetching requirements (default: GET)
-d, --data	Request body data (optional)
-i, --index	Index into the accepts array (default: 0)
--scheme	Payment scheme (e.g., exact)
--network	CAIP-2 network (e.g., eip155:8453)
--amount	Amount in smallest unit
--asset	Token contract address
--pay-to	Recipient address
--max-timeout	Max timeout in seconds
--extra-name	EIP-712 domain name (e.g., USD Coin)
--extra-version	EIP-712 domain version (e.g., 2)
-o, --output	File path to write output (default: stdout)

When -u is provided, the command fetches the PaymentRequired response from the resource server and uses accepts[index] as the base. Individual flags override fields from the fetched requirements.

---

proof gen

Generate an EIP-191 personal sign ownership proof for a resource URL.

x402cli proof gen -u https://api.example.com --private-key 0x...

Flags:

Flag	Description
-u, --url	URL to sign (required)
--private-key	Hex-encoded private key for signing (required)

The generated signature can be used in the ownershipProofs field of a /.well-known/x402 discovery response.

---

proof verify

Verify an ownership proof signature against an expected address.

x402cli proof verify -u https://api.example.com -p 0x... -a 0x...

Flags:

Flag	Description
-u, --url	URL that was signed (required)
-p, --proof	Proof signature in hex (required)
-a, --address	Expected signer address (required)

---

Docker

A multi-stage Dockerfile is provided at cmd/x402cli/Dockerfile. It produces a minimal Alpine-based image containing only the x402cli binary.

Building

# From the project root
docker build -f cmd/x402cli/Dockerfile -t x402cli .

Running

# Run any CLI command
docker run --rm x402cli supported -u http://host.docker.internal:4020

# Pass a private key for signing operations
docker run --rm -e X402_FACILITATOR_PRIVATE_KEY=0x... x402cli payload \
  --req requirements.json --private-key 0x...

Docker Compose

The CLI is defined as a service in the project-level docker-compose.yml under the cli profile.

# Run CLI commands via compose (has network access to the facilitator service)
docker compose run --rm x402cli supported -u http://facilitator:4020
docker compose run --rm x402cli check -u https://api.example.com/data

---

Example Workflow

A typical workflow for paying for a protected resource:

# 1. Check if resource requires payment
x402cli check -u https://api.example.com/data -o check.json

# 2. Generate requirements (from the check response)
x402cli req -u https://api.example.com/data -o requirements.json

# 3. Generate signed payload
x402cli payload --req requirements.json --private-key 0x... -o payload.json

# 4. Pay for the resource
x402cli pay -u https://api.example.com/data \
  -p payload.json --req requirements.json