> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axon402.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Complete reference of AXON configuration variables

## Runtime

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_RUNTIME_MODE` | `live` | Set to `demo` for zero-secrets mode |
| `AXON_DECISION_API_PORT` | `3030` | Port for the Decision API |
| `PORT` | `3000` | Port used by the demo HTTP server (`npm run demo`) |
| `AXON_NETWORK_MODE` | `mainnet` | `mainnet` or `testnet` |
| `LOG_LEVEL` | `info` | Logging verbosity (`trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent`) |

## Core Configuration

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_DECISION_API_KEY` | — | Optional static operator credential. Required only if you want operator-only routes such as `/v1/metrics`, `/v1/webhooks/dispatch`, or static-key access to `/v1/operator/mcp`. |
| `SUPABASE_URL` | (required) | Supabase project URL |
| `SUPABASE_SERVICE_KEY` | (required) | Supabase service role key (backend only) |
| `BASE_RPC_URL` | (required) | Base network RPC endpoint |
| `MASTER_MNEMONIC` | placeholder sentinel | Required in live mode when `AXON_SIGNING_MODE=full`; browser-signing deployments can leave the placeholder in place |
| `AGENT_WALLET_ID` | placeholder sentinel | Default wallet for self-hosted stdio sessions and demo-mode `/v1/mcp` fallback; live HTTP runtime clients should use wallet-bound tenant keys |

## Platform Auth

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_PLATFORM_AUTH_ENABLED` | `false` | Enable Supabase session auth on org routes |
| `AXON_PLATFORM_ALLOWED_ORIGINS` | — | Comma-separated allowed origins for CORS |

## Policy & Safety

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_REQUIRE_PROVIDER_REGISTRY` | `false` | Strict mode: reject unmatched providers |
| `AXON_BALANCE_PRECHECK_ENABLED` | `true` | Prevent signing underfunded payments |
| `AXON_APPROVAL_EXPIRY_MINUTES` | `5` | Approval TTL in minutes |
| `AXON_RATE_LIMIT_RPM` | `60` | Per-wallet rate limit (requests/minute) |
| `AXON_SHUTDOWN_GRACE_MS` | `10000` | Graceful shutdown timeout in milliseconds |
| `AXON_ALIGNMENT_RISK_MAX_NO_LLM` | `20` | Max risk score when LLM alignment is disabled (0–25) |

## Alignment LLM (opt-in)

When enabled, alignment scoring uses an LLM for semantic evaluation.
Falls back to structural (Jaccard) scoring on failure or when disabled.

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_ALIGNMENT_LLM_ENABLED` | `false` | Enable LLM-based alignment scoring |
| `AXON_ALIGNMENT_LLM_ENDPOINT` | — | OpenAI-compatible chat completions endpoint |
| `AXON_ALIGNMENT_LLM_API_KEY` | — | API key for LLM endpoint |
| `AXON_ALIGNMENT_LLM_MODEL` | `gpt-4o-mini` | Model to use |
| `AXON_ALIGNMENT_LLM_TIMEOUT_MS` | `3000` | Timeout for LLM calls in milliseconds |

## Signing Mode

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_SIGNING_MODE` | `full` | Signing strategy: `full` (server-side) or `browser` (client-side) |

**`full`** — Server holds `MASTER_MNEMONIC` and signs EIP-3009 payments. Default for self-hosted operators.

**`browser`** — Server creates unsigned spending intents. The user's browser decrypts their HD wallet (AES-256-GCM encrypted, stored in Supabase) and signs client-side. `MASTER_MNEMONIC` is not required.

## Rate Limiting & Circuit Breaker

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_DECISION_API_RPM` | `120` | API rate limit per key |
| `AXON_CIRCUIT_FAILURE_THRESHOLD` | `3` | Failures before circuit opens |
| `AXON_CIRCUIT_COOLDOWN_MS` | `300000` | Circuit breaker cooldown (5 min) |

## Workers

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_APPROVAL_EXPIRY_WORKER_ENABLED` | `true` | Auto-expire stale approvals |
| `AXON_CONFIRMATION_WORKER_ENABLED` | `true` | On-chain confirmation worker |
| `AXON_PROVIDER_SYNC_ENABLED` | `true` | Auto-sync provider registry |
| `AXON_PROVIDER_HEALTH_CHECK_ENABLED` | `false` | Periodic provider health checks |
| `AXON_FORENSIC_WEBHOOKS_ENABLED` | `true` | Enable forensic webhook delivery |
| `AXON_TREASURY_RECONCILIATION_ENABLED` | `true` | Enable on-chain treasury reconciliation |
| `AXON_REPAIR_QUEUE_WORKER_ENABLED` | `true` | Process queued repair items for earnings and treasury post-processing |

## Worker Intervals

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_WEBHOOK_WORKER_INTERVAL_MS` | `10000` | Webhook dispatch interval (10 s) |
| `AXON_APPROVAL_EXPIRY_INTERVAL_MS` | `60000` | Approval expiry check interval (1 min) |
| `AXON_CONFIRMATION_WORKER_INTERVAL_MS` | `30000` | On-chain confirmation poll interval (30 s) |
| `AXON_PROVIDER_SYNC_INTERVAL_MS` | `300000` | Provider registry sync interval (5 min) |
| `AXON_PROVIDER_HEALTH_CHECK_INTERVAL_MS` | `86400000` | Provider health check interval (24 h) |
| `AXON_TREASURY_RECONCILIATION_INTERVAL_MS` | `30000` | Treasury reconciliation poll interval (30 s) |
| `AXON_REPAIR_QUEUE_INTERVAL_MS` | `30000` | Repair queue poll interval (30 s) |

## Webhooks

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_WEBHOOK_WORKER_INTERVAL_MS` | `10000` | Dispatch interval |
| `AXON_WEBHOOK_TIMEOUT_MS` | `8000` | Per-delivery timeout |
| `AXON_WEBHOOK_MAX_ATTEMPTS` | `6` | Max delivery attempts |
| `AXON_WEBHOOK_CLAIM_LEASE_SECONDS` | `30` | Lease duration for batch claims |

## x402 Bazaar

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_BAZAAR_SYNC_ENABLED` | `true` | Sync providers from x402 Bazaar |
| `AXON_BAZAAR_FACILITATOR_URLS` | `https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources,https://facilitator.payai.network/discovery/resources` | Comma-separated Bazaar facilitator discovery endpoints |
| `AXON_BAZAAR_DISCOVERY_URL` | `https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources` | Deprecated single-endpoint fallback when `AXON_BAZAAR_FACILITATOR_URLS` is unset |
| `AXON_BAZAAR_SYNC_PAGE_SIZE` | `100` | Number of Bazaar resources fetched per page |
| `AXON_BAZAAR_SYNC_MAX_PAGES` | `200` | Maximum pages fetched per facilitator sync run |
| `AXON_FACILITATOR_URL` | `https://x402.org/facilitator` | x402 facilitator URL (Coinbase settlement) |

## Treasury

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_TREASURY_RECONCILIATION_ENABLED` | `true` | Enable on-chain reconciliation |
| `AXON_TREASURY_RECONCILIATION_INTERVAL_MS` | `30000` | Reconciliation poll interval |
| `AXON_TREASURY_RECONCILIATION_LOOKBACK_BLOCKS` | `5000` | Number of blocks to scan for reconciliation |
| `AXON_TREASURY_AUTO_REFILL_ENABLED` | `false` | Auto-refill agent pockets from vault |
| `AXON_TREASURY_AUTO_REFILL_MAX_USDC` | `25` | Max auto-refill amount in USDC |
| `AXON_TREASURY_GASLESS_ENABLED` | `false` | Use EIP-3009 relayer for gasless transfers |
| `AXON_TREASURY_RELAYER_PRIVATE_KEY` | — | Private key for relayer (required if gasless enabled) |
| `AXON_TREASURY_RELAYER_LOW_WATERMARK_ETH` | `0.02` | Relayer ETH low watermark threshold |
| `AXON_TREASURY_RELAYER_TARGET_ETH` | `0.1` | Relayer ETH target balance |
| `AXON_TREASURY_SWAP_SLIPPAGE_BPS` | `100` | Swap slippage tolerance in basis points (1–5000) |

## Provider Sync

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_PROVIDER_SYNC_SOURCES` | — | Comma-separated list of provider JSON URLs |

## Provider Enrichment (opt-in)

When enabled, a periodic worker uses an LLM to enrich provider metadata (names, categories, descriptions) for offers synced from external discovery feeds.

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_ENRICHMENT_ENABLED` | `false` | Opt-in flag for the enrichment worker |
| `AXON_ENRICHMENT_API_KEY` | — | API key for the LLM endpoint (Anthropic) |
| `AXON_ENRICHMENT_MODEL` | `claude-haiku-4-5-20251001` | Model to use for enrichment |
| `AXON_ENRICHMENT_INTERVAL_MS` | `86400000` | Worker interval (24 h) |
| `AXON_ENRICHMENT_BATCH_SIZE` | `25` | Providers enriched per batch |
| `AXON_ENRICHMENT_BACKFILL_BATCH_SIZE` | `200` | Batch size for initial backfill |
| `AXON_ENRICHMENT_TIMEOUT_MS` | `10000` | Per-call LLM timeout |

## API Key Security

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_API_KEY_HASH_PEPPER` | (required) | Server-side pepper for HMAC-SHA256 hashing of API keys. Generate with `openssl rand -hex 32`. Never rotate in production without a migration path. |
| `AXON_MCP_PUBLIC_URL` | — | Canonical public MCP endpoint advertised by `POST /v1/api-keys`. Required in live mode to avoid Host-header-derived snippet drift; typically `https://api.axon402.com/v1/mcp`. |
| `AXON_PLATFORM_URL` | `https://axon402.com/` | Public dashboard URL used in CLI/init responses and conflict links. Keep Supabase Site URL aligned separately in the Supabase dashboard. |

## Security Hardening

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_PAYMENT_REPLAY_TTL_MS` | `360000` | TTL for the in-process PAYMENT-SIGNATURE replay cache, range 60000–3600000 (6 min; matches the x402.org facilitator's tolerance window). The DB unique constraint on `(wallet_id, recording_key)` is the authoritative defense; the cache is a best-effort fast-path. |
| `AXON_AUTO_PAUSER_ENABLED` | `false` | Opt-in flag for the origin-health auto-pauser worker |
| `AXON_AUTO_PAUSER_INTERVAL_MS` | `300000` | Auto-pauser poll interval (5 min, range 1m–1h) |

## Recovery Workers

Repair-queue processing for post-settlement failures.

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_REPAIR_QUEUE_WORKER_ENABLED` | `true` | Processes the `repair_queue` dead-letter items (earnings, post-processing). |
| `AXON_REPAIR_QUEUE_INTERVAL_MS` | `30000` | Repair queue poll interval, range 5000–600000 (30 s). |

## Provider Search Feedback

Feedback collection/publishing for the AXON → x402all aggregate feedback channel. Collection, publishing, and retention all default off unless explicitly enabled.

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_PROVIDER_SEARCH_FEEDBACK_COLLECT_ENABLED` | `false` | When `true`, provider-search and test-buy flows enqueue privacy-safe feedback rows into `search_feedback_outbox`. |
| `AXON_PROVIDER_SEARCH_FEEDBACK_PUBLISH_ENABLED` | `false` | When `true`, register the publisher worker. When `false`, the runtime makes zero outbound feedback POSTs and zero outbox claims. |
| `AXON_PROVIDER_SEARCH_FEEDBACK_PUBLISH_URL` | — | Receiver endpoint for signed aggregate feedback batches. Required when publishing is enabled. |
| `AXON_PROVIDER_SEARCH_FEEDBACK_SIGNING_KEY` | — | HMAC signing key for feedback envelopes. Required when publishing is enabled. Minimum 32 characters. |
| `AXON_PROVIDER_SEARCH_FEEDBACK_INTERVAL_MS` | `900000` | Publisher cadence (15 min) |
| `AXON_PROVIDER_SEARCH_FEEDBACK_PUBLISH_TIMEOUT_MS` | `10000` | Per-POST timeout |
| `AXON_PROVIDER_SEARCH_FEEDBACK_BATCH_SIZE` | `500` | Max outbox rows per publish cycle |
| `AXON_PROVIDER_SEARCH_FEEDBACK_MAX_ATTEMPTS` | `8` | Dead-letter threshold for publish retries |
| `AXON_PROVIDER_SEARCH_FEEDBACK_BACKOFF_BASE_MS` | `30000` | Retry backoff base |
| `AXON_PROVIDER_SEARCH_FEEDBACK_BACKOFF_CEIL_MS` | `3600000` | Retry backoff ceiling (1 h) |
| `AXON_PROVIDER_SEARCH_FEEDBACK_CLAIM_LEASE_SECONDS` | `60` | Lease length for outbox row claims |
| `AXON_PROVIDER_SEARCH_FEEDBACK_KEY_ID` | — | Optional `x-axon-key-id` header for receiver-side key rotation |
| `AXON_PROVIDER_SEARCH_FEEDBACK_RETENTION_ENABLED` | `false` | When `true`, run the published-row retention worker |
| `AXON_PROVIDER_SEARCH_FEEDBACK_RETENTION_DAYS` | `30` | Retention window for published rows |
| `AXON_PROVIDER_SEARCH_FEEDBACK_RETENTION_INTERVAL_MS` | `21600000` | Retention worker cadence (6 h) |
| `AXON_PROVIDER_SEARCH_FEEDBACK_RETENTION_BATCH_SIZE` | `1000` | Max published rows pruned per retention cycle |

## Provider Search

Configuration for the wallet-aware Bazaar/provider-search router (`POST /v1/provider-search`) and its HTTP MCP provider-search tools.

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_X402ALL_BASE_URL` | — | Optional base URL for the external x402all candidate-search API. When unset, AXON falls back to AXON-managed offers only. |
| `AXON_PROVIDER_SEARCH_TOP_K_QUOTE` | `10` | Number of top-ranked candidates AXON revalidates with a live quote before returning. Range `1`-`50`. |

## Webhook Outbox

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_WEBHOOK_OUTBOX_MAX_PENDING` | `50000` | Per-org pending webhook backlog cap (range 100–1000000). New events are dropped when the cap is exceeded. |

## Hosted Safety Switches

Server-side kill switches used in hosted deployments.

| Variable | Default | Description |
| :- | :- | :- |
| `AXON_HOSTED_BROWSER_BOOTSTRAP_DISABLED` | `false` | Set to `true` to reject `POST /v1/orgs/bootstrap/browser`. Backend enforcement of the hosted browser-wallet kill switch (parallel to the frontend `VITE_AXON_HOSTED_BROWSER_WALLET_ENABLED` flag) so the API cannot be bypassed. |

## Dashboard (Frontend)

| Variable | Default | Description |
| :- | :- | :- |
| `VITE_SUPABASE_URL` | (required) | Supabase project URL |
| `VITE_SUPABASE_ANON_KEY` | (required) | Supabase anon key |
| `VITE_AXON_DECISION_API_URL` | `http://127.0.0.1:3030` | Decision API URL |
| `VITE_AXON_LIVE_MODE` | — | Enable live mode in dashboard |
| `VITE_AXON_ENABLE_DEMO_MODE` | — | Enable demo button |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.