Agent guide

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

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[]
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 --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 --enabled true --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://gateway.example/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).

• ax402_list_apis — apis:read
  • ax402_create_api — apis:write + verified email
  • ax402_add_endpoint — endpoints:write
  • ax402_import_openapi — openapi:read
  • ax402_add_domain — domains:write
  • ax402_verify_domain — domains:write
  • ax402_domain_suggest — domains:read
  • ax402_stats_overview — stats:read
  • ax402_supported_networks — auth
  • ax402_platform_config — public
  • ax402_pay_url — buyer; uses AX402_EVM_PRIVATE_KEY when set MCP server guide

Buyer payments

Pay gateway hostnames, not the control plane. Staging smoke test: https://echo.staging.ax402.io/echo/get?test=1. Full guide: Buyer clients .

# Inspect 402 requirements (no wallet spend)
ax402 inspect url --url https://echo.staging.ax402.io/echo/get?test=1 --json
# Pay with funded wallet
export AX402_EVM_PRIVATE_KEY=0x...
ax402 pay url --url https://echo.staging.ax402.io/echo/get?test=1 --json

• TypeScript: buyerClientFromEnv() + client.pay() with a URL — supports batch-settlement
• Go: buyer.NewFromPrivateKey + Get(ctx, url)
• Python: BuyerClient.from_env().get(url) or AsyncBuyerClient
• MCP: ax402_pay_url when AX402_EVM_PRIVATE_KEY is 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