Agent guide

Start here for LLM agents, Cursor, and CI automation. Machine-readable index: /llms.txt. OpenAPI contract: openapi/openapi.json.

Bootstrap flow

POST /auth/signup or POST /auth/login → JWT
POST /auth/verify-email with token from email (required before writes)
POST /auth/api-keys with scopes (JWT only) → ax402_live_... key (shown once)
Use API key for automation: header X-API-Key: ax402_live_...

Scope presets

readonly — apis:read, endpoints:read, domains:read, stats:read, settlements:read, openapi:read
apiManager — apis/endpoints/domains read+write, openapi:read
analytics — stats:read, settlements:read

CLI: ax402 scopes presets --json

Wrap an upstream API

1. GET /config/platform
2. POST /apis { name, slug, upstream_base_url, pay_to_mode, pay_to_address? }
3. POST /apis/{id}/endpoints { method, path_pattern, accepts[] }
4. Gateway URL: https://{slug}.{platform_domain}{path}

Import OpenAPI

1. POST /openapi/parse { spec: "<yaml or json>" }  → operations[] (includes request_schema/response_schema when present)
2. POST /apis/{id}/openapi/import { operations[], accepts[] }

Custom domain

1. POST /apis/{id}/domains { hostname }
2. Response includes verification_record, cname_target, verification_token
3. POST /apis/{id}/domains/{domainId}/verify

CLI quick reference

ax402 apis list --json
ax402 apis create --name "My API" --slug my-api --upstream https://api.example.com \
  --discovery-guidance "Use GET /v1/*." --json
ax402 apis discovery --id ID --json
ax402 discovery urls --api-id ID --json
ax402 apis get --id ID --json
ax402 apis delete --id ID --json
ax402 endpoints list --api-id ID --json
ax402 endpoints create --api-id ID --method GET --path "/v1/*" --price-usdc 0.10 --json
ax402 endpoints update --api-id ID --endpoint-id EP --request-schema '{"type":"object"}' --json
ax402 endpoints delete --api-id ID --endpoint-id EP --json
ax402 domains suggest --apex example.com --json
ax402 domains add --api-id ID --hostname api.example.com --json
ax402 domains verify --api-id ID --domain-id DOM --json
ax402 keys list --json
ax402 keys create --name ci --scopes apis:read,apis:write --json
ax402 keys revoke --id KEY --json
ax402 auth login --email you@example.com --password secret --json
ax402 openapi parse --file spec.yaml --json
ax402 openapi import --api-id ID --file spec.yaml --price-usdc 0.10 --json
ax402 stats overview --days 30 --json
ax402 config platform --json
ax402 networks supported --json
ax402 pay url --url https://my-api.ax402.io/v1/foo --json

Full details: CLI reference. Exit codes: 0 success, 1 API error, 2 usage error.

MCP tools

Requires AX402_API_KEY and AX402_BASE_URL (API key only — no JWT).

Discovery-related:

ax402_discovery_urls — apis:read
ax402_set_discovery_guidance — apis:write
ax402_update_endpoint_schemas — endpoints:write
ax402_create_api — apis:write + verified email (optional discovery fields)
ax402_import_openapi — openapi:read

Common seller tools: ax402_list_apis, ax402_get_api, ax402_list_endpoints, ax402_add_endpoint, ax402_add_domain, ax402_verify_domain, ax402_domain_suggest, ax402_stats_overview, ax402_supported_networks, ax402_platform_config.

Buyer: ax402_inspect_url, ax402_pay_url (needs AX402_EVM_PRIVATE_KEY and/or Hedera keys).

Full tool list: MCP server · API discovery

Buyer payments

Pay gateway hostnames, not the seller API. Example: https://my-api.ax402.io/v1/foo. Full guide: Buyer clients.

# Inspect 402 requirements (no wallet spend)
ax402 inspect url --url https://my-api.ax402.io/v1/foo --json
# Pay with funded wallet
export AX402_EVM_PRIVATE_KEY=0x...
ax402 pay url --url https://my-api.ax402.io/v1/foo --json

TypeScript: buyerClientFromEnv() + client.pay() — exact and batch-settlement
Go: buyer.NewFromPrivateKey + Get(ctx, url) — exact and batch-settlement
Python: BuyerClient.from_env().get(url) or AsyncBuyerClient — exact and batch-settlement
MCP: ax402_pay_url when wallet credentials are set
Browser SPA: React paywall

Protocol: x402-foundation/x402.

Errors

JSON body: {"error":"message"}. Common:

401 unauthorized / invalid token
403 insufficient scope / email verification required / jwt required
409 email already registered / slug already exists

Idempotency

POST /apis duplicate slug → 409
OpenAPI import skips existing method+path keys
Domain verify on already-verified domain → status already verified

On this page