REST API Integration

For service-to-service integrations, you can call the Decision API directly without MCP or OpenClaw. The public hosted base URL is https://api.axon402.com; local development typically uses http://127.0.0.1:3030.

Setup

Choose your base URL:

export AXON_API_URL=https://api.axon402.com

For local development instead:

cd axon-402-mcp
npm run build
npm run start:decision-api
export AXON_API_URL=http://127.0.0.1:3030

Authenticate with a bearer token. AXON recognises two key types for REST integrations:

Authorization: Bearer <KEY>
Content-Type: application/json

Operator key — the static AXON_DECISION_API_KEY. Full trust; required for /v1/operator/*, /v1/repair/*, provider registry mutations, worker triggers, and global metrics.
Tenant API key (axon_sk_…) — scoped to an organization (and optionally to a single wallet). Can be minted via POST /v1/api-keys. Wallet-bound keys are the runtime credential shape for /v1/ssar/fetch, /v1/budget/status, /v1/approvals/*, and /v1/receipts/*. Org-wide keys (no wallet_id) are the operator-surface credential shape for seller and control-plane routes such as /v1/services/*.

Service-to-service integrations should almost always use a tenant key so access is scoped to the caller’s org. Reserve the operator key for the on-call runbook.

Wallet-bound runtime keys are rejected on seller/control-plane routes guarded by assertOperatorSurface(...). Those calls return 403 TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE.

POST /v1/orgs/bootstrap/browser is gated by the server-side AXON_HOSTED_BROWSER_BOOTSTRAP_DISABLED kill switch. When true, hosted deployments reject the request regardless of credentials.

Minimal Integration

Make a governed request

curl -X POST "$AXON_API_URL/v1/ssar/fetch" \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/data",
    "intent": "Fetch market data for analysis",
    "task_id": "task-001",
    "wallet_id": "<POCKET_WALLET_ID>",
    "idempotency_key": "unique-request-key"
  }'

Direct REST calls do not inject wallet_id from a wallet-scoped API key. Send wallet_id explicitly unless the daemon’s default AGENT_WALLET_ID is already pinned to the wallet you intend to use. If you bootstrapped with npx @axon402/init, read the correct wallet_id from ~/.axon/config.json.

Check budget

curl -s \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  "$AXON_API_URL/v1/budget/status?wallet_id=<WALLET_ID>"

Wallet-scoped tenant keys may omit wallet_id on this route; org-wide keys must provide it.

Handle approval flow

# 1. Original request returns APPROVAL_REQUIRED with approval_request_id

# 2. Check approval status
curl -s \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  "$AXON_API_URL/v1/approvals/$APPROVAL_ID/status"

# 3. After operator approves, consume the token
curl -X POST \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  "$AXON_API_URL/v1/approvals/$APPROVAL_ID/consume"

# 4. Retry with approval token (same idempotency_key)
curl -X POST "$AXON_API_URL/v1/ssar/fetch" \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/data",
    "intent": "Fetch market data for analysis",
    "task_id": "task-001",
    "wallet_id": "<POCKET_WALLET_ID>",
    "idempotency_key": "unique-request-key",
    "approval_token": "<APPROVAL_TOKEN>"
  }'

Health Checks

# Liveness
curl "$AXON_API_URL/v1/health"

# Readiness (checks DB, wallet, mandate, workers)
curl "$AXON_API_URL/v1/ready"

Only proceed if /ready returns 200. A green /health alone is not sufficient.

Operator-only endpoints

These endpoints require the static operator key. They are intended for AXON on-call operators, not for customer application code or normal tenant integrations.

Group	Paths	Purpose
Global controls	`POST /v1/operator/pause`, `/v1/operator/resume`, `GET /v1/operator/status`, `POST /v1/operator/emergency-stop`	Pause/resume traffic, inspect worker health, emergency-stop a pocket/department/org.
Launch gate	`GET /v1/operator/launch-gate`	Run data-integrity audits; returns `503` if not ready.
Manual trigger	`POST /v1/operator/trigger/repair-queue`	One-shot repair-queue run for game-day scenarios.
Webhook repair	`GET /v1/repair/webhooks/dead-letter`, `POST /v1/repair/webhooks/:id/replay`, `/v1/repair/webhooks/replay-all`	Inspect and requeue dead-letter webhooks.
Repair queue	`GET /v1/repair/queue`, `POST /v1/repair/queue/:id/retry`, `/v1/repair/queue/retry-all`	Inspect and retry dead-letter or stuck `repair_queue` items.
Journal repair	`GET /v1/repair/journals/incomplete`, `POST /v1/repair/journals/:id/reconcile`	Manually recover an earning from a settlement journal that never completed end-to-end.

See the full API Reference for all endpoints.

Getting Started

CLI

Core Concepts

Integrations

Operations

REST API Integration

Setup

Minimal Integration

Make a governed request

Check budget

Handle approval flow

Health Checks

Operator-only endpoints

​Setup

​Minimal Integration

​Make a governed request

​Check budget

​Handle approval flow

​Health Checks

​Operator-only endpoints

Setup

Minimal Integration

Make a governed request

Check budget

Handle approval flow

Health Checks

Operator-only endpoints