Ax402Docs

CLI reference

Full ax402 command reference

The @ax402/cli package automates seller API operations from shell scripts and CI. Same routes as the TypeScript SDK. Agent quick start: Agent guide.

Install and run

npm install -g @ax402/cli
ax402 apis list --json

Or run without installing:

npx @ax402/cli apis list --json

From source

git clone https://github.com/AxLabs/ax402-sdks.git
cd ax402-sdks && pnpm install
pnpm --filter @ax402/cli build
node tools/cli/dist/index.js apis list --json

Global flags

  • --json — JSON output on any command
  • --sandbox — target Sandbox / Test mode (development): fork USDC accepts and X-Ax402-Environment: development. Same as AX402_ENVIRONMENT=development or AX402_SANDBOX=1.

Full Sandbox guide (RPC, wallet private key, SDK/MCP/API): Sandbox.

Environment

VariablePurpose
AX402_BASE_URLSeller API base URL (default https://api.ax402.io)
AX402_API_KEYScoped API key (ax402_live_... or ax402_sandbox_...)
AX402_JWTAlternative to API key; required for keys and sandbox-wallet
AX402_ENVIRONMENTdevelopment for Sandbox
AX402_SANDBOX1 / true — alias for development
AX402_EVM_PRIVATE_KEYBuyer signing for pay url (EVM)
HEDERA_ACCOUNT_IDBuyer signing for pay url (Hedera)
HEDERA_PRIVATE_KEYBuyer signing for pay url (Hedera)
HEDERA_NETWORKOptional Hedera network (hedera:mainnet)

Environment pairing (API keys)

API key environment is fixed by prefix — AX402_SANDBOX and --sandbox do not retarget an API key to a different control plane. Pair key and base URL:

Key prefixAX402_BASE_URL
ax402_sandbox_...https://api.staging.ax402.io
ax402_live_...https://api.ax402.io (default)

Wrong pairing → 401 {"error":"invalid token"} (not insufficient scope). With AX402_JWT, use --sandbox or X-Ax402-Environment: development on either host instead.

Command reference

apis

ax402 apis list [--json]
ax402 apis create --name NAME --slug SLUG --upstream URL [--pay-to 0x...] [--webhook-url URL] [--webhook-secret SECRET] [--discovery-guidance TEXT] [--discovery-contact-email EMAIL] [--openapi-version VER] [--json]
ax402 apis get --id ID [--json]
ax402 apis discovery --id ID [--json]
ax402 apis update --id ID [--name NAME] [--slug SLUG] [--upstream URL] [--pay-to 0x...] [--webhook-url URL] [--webhook-secret SECRET] [--clear-webhook] [--discovery-guidance TEXT] [--discovery-contact-email EMAIL] [--openapi-version VER] [--json]
ax402 apis webhook-deliveries --id ID [--json]
ax402 apis delete --id ID [--json]
ax402 apis slug-check --slug SLUG [--exclude-api-id ID] [--json]
ax402 apis probe-upstream --api-id ID [--endpoint-id EP] [--path PATH] [--json]
ax402 apis cors-list --api-id ID [--json]
ax402 apis cors-set --api-id ID --origins ORIGIN[,ORIGIN...] [--json]
ax402 apis cors-add --api-id ID --origin ORIGIN [--json]
ax402 apis cors-remove --api-id ID --origin ORIGIN [--json]

endpoints

ax402 endpoints list --api-id ID [--json]
ax402 endpoints create --api-id ID --path "/v1/*" [--method GET] [--price-usdc 0.10] [--scheme exact|batch-settlement] [--network CAIP2] [--asset ADDR] [--decimals N] [--ttl SECONDS] [--request-schema JSON] [--response-schema JSON] [--json]
ax402 endpoints update --api-id ID --endpoint-id EP [--enabled true|false] [--network CAIP2 --asset ADDR --price 0.10] [--accepts JSON] [--request-schema JSON] [--response-schema JSON] [--clear-schemas] [--json]
ax402 endpoints delete --api-id ID --endpoint-id EP [--json]

discovery

ax402 discovery urls --api-id ID [--json]
ax402 discovery check --url "https://myapi.example.com" [--json]

Validate the gateway origin with AgentCash:

npx -y @agentcash/discovery@latest check "https://myapi.example.com/"
npx -y @agentcash/discovery@latest discover "https://myapi.example.com/"

See API discovery.

domains

ax402 domains suggest --apex example.com [--prefix x402] [--json]
ax402 domains add --api-id ID --hostname HOST [--json]
ax402 domains list --api-id ID [--json]
ax402 domains verify --api-id ID --domain-id ID [--json]
ax402 domains delete --api-id ID --domain-id ID [--json]

keys

ax402 keys list [--json]
ax402 keys create --name NAME --scopes apis:read,apis:write [--json]
ax402 keys revoke --id ID [--json]

keys commands require AX402_JWT.

sandbox-wallet

ax402 --sandbox sandbox-wallet get [--wait|--no-wait] [--json]
ax402 --sandbox sandbox-wallet reset [--wait|--no-wait] [--json]

Requires AX402_JWT and --sandbox (or development env). Returns a funded fork wallet; --json includes private_key for AX402_EVM_PRIVATE_KEY. See Sandbox.

auth

ax402 auth login --email EMAIL --password PASS [--json]
ax402 auth me [--json]

openapi

ax402 openapi parse [--file PATH] [--spec YAML_OR_JSON] [--json]
ax402 openapi import --api-id ID [--file PATH] [--spec YAML_OR_JSON] [--price-usdc 0.10] [--json]

stats / settlements / batch

ax402 stats overview [--days 30] [--json]
ax402 stats api --api-id ID [--days 30] [--json]
ax402 settlements list --api-id ID [--json]
ax402 settlements batch --api-id ID [--json]
ax402 settlements history [--days 30] [--api-id ID] [--limit N] [--offset N] [--json]
ax402 settlements export --format csv|json [--days 30] [--api-id ID] [--json]
ax402 batch overview --api-id ID [--json]
ax402 batch settings --api-id ID --claim-interval-secs N --settle-interval-secs N --refund-interval-secs N [--json]

billing / income / facilitator

ax402 billing overview [--json]
ax402 billing packages [--json]
ax402 billing invoices [--json]
ax402 income summary [--json]
ax402 income ledger [--limit N] [--offset N] [--api-id ID] [--network NET] [--json]
ax402 income payout-requests [--json]
ax402 facilitator stats [--days 30] [--json]
ax402 facilitator events [--days 30] [--limit N] [--offset N] [--json]

config / networks / scopes

ax402 config platform [--json]
ax402 config billing [--json]
ax402 networks supported [--json]
ax402 scopes presets [--json]
ax402 scopes list [--json]
ax402 exchange-rates list [--quote usd] [--date YYYY-MM-DD] [--json]
ax402 exchange-rates supported [--json]
ax402 exchange-rates lookup --network NET --asset ADDR [--quote USD] [--date YYYY-MM-DD] [--json]

inspect / pay (buyer)

ax402 inspect url --url GATEWAY_URL [--method GET] [--json]
ax402 pay url --url GATEWAY_URL [--method GET] [--json]

inspect url fetches a gateway hostname and parses HTTP 402 payment requirements (no wallet). pay url requires AX402_EVM_PRIVATE_KEY and/or Hedera credentials.

Exit codes

  • 0 — success
  • 1 — API error
  • 2 — usage / validation error

Control plane API

REST contract, auth, API keys

MCP server

Cursor / Claude agent tools

On this page

Install and runFrom sourceGlobal flagsEnvironmentEnvironment pairing (API keys)Command referenceapisendpointsdiscoverydomainskeyssandbox-walletauthopenapistats / settlements / batchbilling / income / facilitatorconfig / networks / scopesinspect / pay (buyer)Exit codesRelated