A CLI that lets an AI agent discover x402-paywalled services, inspect what they cost, and pay for them — autonomously, with no human confirmation step. request pay moves real funds (Base USDC) the instant it runs. The safeguard is bounded wallet funding (see Setup), not a confirmation prompt — if you need a confirmation gate, add it in your own orchestration layer before calling this CLI.
Skill Files
File
Purpose
SKILL.md (this file)
How to use the CLI
x402_cli.py
CLI implementation
requirements.txt
Python dependencies
DISCLOSURES.md
Detailed risk disclosures and safeguard requirements
NOTICE.md
Legal notice, liability limitations, and third-party service disclaimers
Quick Reference
Command
Wallet secret required
Moves funds
Writes a file by default
Purpose
discover list
no
no
no (--save to opt in)
Paginated catalog of x402 services
discover search <query>
no
no
no (--save to opt in)
Semantic search over the catalog
request info <url>
no
no
no (--save to opt in)
Inspect payment requirements, no payment sent
request pay <url>
yes
yes
no (--save to opt in)
Pay and fetch the service response
Typical flow: discover → request info → request pay. See Workflow.
Setup
Get a wallet. This CLI only reads a private key from CLIENT_EVM_WALLET_SECRET — it never generates or stores one. Use create-crypto-wallets to generate one and keepass-cli to store it (see Integration Guidance for exact commands).
Fund it, deliberately small. The wallet's balance is the security boundary for this skill:
Normal use: 5–10 USDC on Base
Higher-volume use: up to 50–100 USDC, only if you trust the calling agent's spending behavior
Never fund with a personal or high-value key — always a fresh, dedicated wallet
Install deps and export the key before invoking the CLI:
bash
python -m pip install -r requirements.txt
export CLIENT_EVM_WALLET_SECRET="0x..." # retrieve from keepass-cli at runtime, never hardcode!
There is no --key flag by design — a CLI argument would leak into shell history, process listings, and logs.
Same flags as discover list. query is a free-text string matched semantically against service descriptions/tags. Response includes partialResults: true if the search timed out with incomplete results.
request info <url>
bash
python x402_cli.py request info https://example.com/paywalled-endpoint \
--method post --data '{"foo":"bar"}' --header '{"Authorization":"Bearer ..."}'
Sends a plain HTTP request with no payment — the endpoint typically replies 402 Payment Required with payment instructions. Does not require CLIENT_EVM_WALLET_SECRET. Always run this before request pay to confirm amount, network, and recipient.
Same flags as request info, plus it requires CLIENT_EVM_WALLET_SECRET. Signs an x402 payment, sends it on Base mainnet, then sends the request and returns the service's response.
Flag
Default
Meaning
--spend-limit
1.0
Maximum USDC to authorize for the payment request
⚠️ This authorizes an on-chain payment the moment it runs — there is no confirmation prompt. A warning is printed to stderr immediately beforehand as a last reminder, but it does not block execution. Always inspect with request info first.
Output Contract
Every invocation prints exactly one JSON object to stdout, then exits with:
Match errors on error_code (stable across versions), not on the human-readable error string:
error_code
Meaning
invalid_argument
Bad CLI arguments
invalid_json
--data / --header wasn't valid JSON
missing_env_var
CLIENT_EVM_WALLET_SECRET not set (only for request pay)
network_error
Transport failure — DNS, timeout, connection refused
internal_error
Unexpected exception; check the accompanying type field for the Python exception class
Security warnings (the request pay payment notice) print to stderr, never stdout — stdout always contains exactly one JSON object regardless of what's on stderr.
data is the endpoint's JSON body, or {"raw": "..."} if it wasn't valid JSON.
HTTP 4xx/5xx from the destination is still "ok": true — it's a valid response, not a CLI failure. Only transport-level failure produces "ok": false" / network_error.
Saved Request/Response Files
request info and request pay can write a JSON file with --save (opt-in, disabled by default; --output-dir/-o to choose where). A stderr notice is printed whenever saving is enabled. Filename pattern: x402_request_info_<timestamp>.json / x402_request_pay_<timestamp>.json.
input.header / input.data are what was passed via --header / --data (null if omitted). Header values matching common auth conventions (Authorization, Cookie, Set-Cookie, X-API-Key, etc., case-insensitive) are replaced with "[REDACTED]" before writing — only header values are redacted; the request body/data and the service's response are stored as-is. If either may carry secrets or sensitive data, omit --save.
response is {"status_code": ..., "data": ...} on success, or {"error": "...", "error_code": "..."} on failure — the file is written either way, giving you an audit trail even for failed/rejected payments.
For request pay, treat these files as your local payment ledger.
Workflow
text
1. discover list / discover search <query>
→ get candidate "resource" URLs
↓
2. request info <resource_url> (no cost, no wallet needed)
→ confirm scheme/network/amount/payTo match what you expect
→ confirm input/output format via extensions.bazaar in the discovery entry
↓
3. request pay <resource_url> (moves real funds — no confirmation prompt)
→ signs payment with CLIENT_EVM_WALLET_SECRET, sends it, returns the service response
Skipping step 2 means authorizing a payment blind. Always run request info first unless you already know the exact payment requirements for that URL.
Networks & Security Model
Base mainnet only (eip155:8453). Testnets are not supported and will fail — confirm your wallet holds Base-mainnet funds before calling request pay.
No confirmation gate by design. This skill is built for autonomous use: an agent can discover, inspect, and pay without stopping for human approval. The risk boundary is the wallet's funding limit, not the CLI. Wrap it in your own orchestration if you need a human-in-the-loop step.
Capabilities (explicit declaration)
This is a high-impact financial tool. Its full runtime capability surface:
Capability
Scope
Detail
Environment read
CLIENT_EVM_WALLET_SECRET only
Read once per request pay invocation, held in memory only, never written to disk or logs by this CLI. See metadata.openclaw in the frontmatter for the declared env var.
Network (fixed)
Coinbase CDP discovery endpoints
discover list / discover search call api.cdp.coinbase.com only.
Network (arbitrary)
Any URL passed to request info / request pay
The URL, HTTP method, --header, and --data you supply are sent as-is to that third-party endpoint — treat it as untrusted.
Blockchain write
Base mainnet (eip155:8453)
Only from request pay; signs and submits a real, irreversible USDC transfer using CLIENT_EVM_WALLET_SECRET.
File write
Local disk, opt-in only
Only when --save is passed to discover ... / request info / request pay; see Saved Request/Response Files. No files are written otherwise.
Process execution
None
No shell/subprocess execution anywhere in this CLI.
No other environment variables, files, or subprocesses are touched.
Discovery Response Schema
Both discover list and discover search return an array of resources shaped like:
upto: the same amount field is phase-dependent — at verification it's the max you authorize, at settlement it's what the server actually charges. Your wallet is only ever charged the settlement-time amount, never more than the authorized max.
batch-settlement: backed by either capital (client's own pre-funded escrow/channel) or credit (a network intermediary underwrites and bills later). The CLI handles commitment signing; redemption timing/mechanism is defined by the network binding, not by this CLI.
scheme and network are independent axes — a resource can advertise the same scheme across multiple networks (e.g. exact on both Base and Solana). The CLI matches whichever combination your wallet supports (currently: exact/eip155:8453 only).
Integration Guidance
Setting up with other skills
To securely manage your x402 wallet, combine this skill with create-crypto-wallets and keepass-cli:
1. Generate a dedicated wallet with create-crypto-wallets:
openclaw skills install @beocca/keepass-cli
# Store in your KeePass database
python keepass_cli.py add-entry \
--title "x402-wallet" \
--username "$ADDRESS" \
--password "$PRIVATE_KEY" \
--group "Wallets"
3. Fund the wallet on Base mainnet with 10–20 USDC
4. Retrieve and use at runtime:
bash
# Retrieve the private key from KeePass
PRIVATE_KEY=$(python keepass_cli.py show-entry --title "x402-wallet" --show-secrets | jq -r '.password')
# Set and use
export CLIENT_EVM_WALLET_SECRET="$PRIVATE_KEY"
python x402_cli.py discover list --limit 5
Reducing shell exposure of the private key: commands above and in these examples pass the key through shell variables, which can be recovered from shell history, process listings (ps), crash dumps, or inherited subprocess environments. To reduce this risk:
Disable history for the session before exporting secrets (set +o history, then set -o history afterward), or run the retrieval/export/CLI sequence inside a script instead of an interactive shell.
Unset the variable as soon as the CLI call completes (unset CLIENT_EVM_WALLET_SECRET PRIVATE_KEY).
Never pass the key as a CLI argument (there is no --key flag by design) or print it with echo/logging.
Prefer piping the secret directly into the environment of the single python x402_cli.py ... invocation (e.g. CLIENT_EVM_WALLET_SECRET=$(...) python x402_cli.py ...) over multi-step export so it isn't retained in the shell's exported-variable table for the rest of the session.
Example workflow: discover, inspect, pay
bash
# Search for a service
SEARCH=$(python x402_cli.py discover search "your_query")
RESOURCE=$(echo "$SEARCH" | jq -r '.resources.resources[0].resource')
# Inspect what it costs (no payment required)
INFO=$(python x402_cli.py request info "$RESOURCE" --method GET)
echo "$INFO" | jq '.data'
# If satisfied, pay for the service
RESULT=$(python x402_cli.py request pay "$RESOURCE" --method GET)
echo "$RESULT" | jq '.data'
Related Skills
keepass-cli to manage your passwords, credentials, and secrets. Install via openclaw skills install @beocca/keepass-cli
create-crypto-wallets is a more sophisticated skill to create crypto wallets using the python-hdwallet library. Install via openclaw skills install @beocca/create-crypto-wallets
agmsg-cli allows you to interact with AgMsg — the communication layer for autonomous agents. Install via openclaw skills install @beocca/agmsg-cli
agnet-cli allows you to interact with AgNet — the collective brain of the agentic web. There, you can publish, reply to, and react to other agents' content. Install via openclaw skills install @beocca/agnet-cli
x402-seller explains to you how to sell your own services using x402. Install via openclaw skills install @beocca/x402-seller