# Configuration Reference This is the authoritative reference for **every** environment variable read by SettleKit. It is generated from the actual configuration loaders in the source tree, not from documentation prose: | Component | Config source | | --- | --- | | API (`apps/api`) | `apps/api/src/config/env.ts`, plus direct `process.env` reads in `src/context.ts`, `src/middleware/auth.ts`, `src/routes/auth.ts`, `src/routes/x402.ts`, `src/server.ts` | | Worker (`apps/worker`) | `apps/worker/src/config.ts` | | x402 Gateway (`services/x402-gateway`) | `config.go` | | Arc Indexer (`services/arc-indexer`) | `src/config.rs` | | License Gateway (`services/license-gateway`) | `src/config.rs` | | Webhook Relay (`services/webhook-relay`) | `src/config.rs` | | Node SDK (`packages/sdk`) | `src/index.ts` | | Python SDK (`sdks/python`) | `settlekit/_transport.py`, `settlekit/x402.py` | | Go CLI (`clis/agentpay`) | `internal/client/client.go` | | Next.js apps (`apps/dashboard`, `checkout`, `marketplace`, `admin`, `docs`, `web`, `portal`) | `process.env.NEXT_PUBLIC_API_URL`, `PORT` | ## How configuration is loaded ### API — every integration is optional The API loader (`loadConfig` in `apps/api/src/config/env.ts`) is designed so the API **boots with zero integrations configured**. Each integration group is one of three states: - **Absent** — none of the group's keys are set → the in-memory client double in `apps/api/src/clients/` is used instead of the real integration. - **Present** — all of the group's required keys are set → the real client is constructed and a `has*` flag flips to `true`. - **Partial** — some but not all keys set → boot fails fast with a `ConfigError` listing exactly which keys to set or unset. This prevents silent half-wired integrations. Persistence follows the same rule: set `DATABASE_URL` and the API/worker use Postgres via `@settlekit/persistence`; leave it unset and they run against a process-local in-memory store. ### Worker — integrations are required Unlike the API, the worker (`apps/worker/src/config.ts`) **requires** Arc, email, GitHub, Discord, file-delivery, license, and the webhook signing secret to be present, because every background job depends on at least one of them. Missing required values fail fast at boot with a precise message. `DATABASE_URL` remains optional (in-memory fallback). Numeric job intervals are range-bounded so a bad value cannot turn a sweep into a tight CPU loop. ### Services — fail-fast Rust/Go loaders Each Rust/Go service validates its own environment at startup and refuses to start on a missing required value or a malformed one (bad port, non-hex address, zero timeout, etc.). --- ## API (`apps/api`) — port 8787 Built from `apps/api/src/config/env.ts` plus the direct `process.env` reads noted above. ### Always-present settings (have defaults) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `PORT` | no | `8787` | TCP port the API binds to. Range 1–65535. Also read directly in `server.ts`. | | `LICENSE_TOKEN_SECRET` | no | `settlekit-dev-license-secret` | HMAC secret used to sign license-key tokens. **Override in production.** | | `WEBHOOK_SIGNING_SECRET` | no | `settlekit-dev-webhook-secret` | HMAC secret used to sign outbound webhook payloads so receivers can verify them. **Override in production.** | | `AUTH_COOKIE_SECRET` | no | `settlekit-dev-auth-cookie-secret` | HMAC secret used to sign the `sk_session` auth cookie. **Override in production.** | | `FILE_DOWNLOAD_BASE_URL` | no | `http://localhost:8787/v1/files/download` | Base URL embedded in signed file-download links. | | `FILE_DOWNLOAD_SECRET` | no | `settlekit-dev-file-secret` | HMAC secret used to sign file-download URLs. **Override in production.** | | `FILE_DOWNLOAD_EXPIRES_SEC` | no | `3600` | Default lifetime (seconds) of a signed download link. Range 60–2,592,000. | | `FILE_DOWNLOAD_MAX_DOWNLOADS` | no | `3` | Default max downloads per signed link. Range 1–10,000. | > Note: the API and worker use **different** env-var names for the file-delivery > group (`FILE_DOWNLOAD_*` in the API vs `FILE_DELIVERY_*` in the worker). Set > both if you run both processes. ### Authentication, merchant identity, runtime (direct `process.env`) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `API_BOOTSTRAP_KEY` | no | _(unset)_ | Static bootstrap Bearer key accepted by `authMiddleware` so the very first authenticated call can create real API keys. Read in `src/middleware/auth.ts`. Leave unset once real keys exist. | | `NODE_ENV` | no | _(unset)_ | When `production`, the `sk_session` auth cookie is set `Secure`. Read in `src/routes/auth.ts`. | | `MERCHANT_NAME` | no | `SettleKit Merchant` | Display name for the merchant identity used on invoices/receipts. Read in `src/context.ts`. | | `MERCHANT_EMAIL` | no | _(unset)_ | Optional merchant contact email surfaced on invoices/receipts. | | `MERCHANT_WEBSITE` | no | _(unset)_ | Optional merchant website surfaced on invoices/receipts. | | `X402_PAY_TO` | no | `0x0000000000000000000000000000000000000000` | Destination USDC address advertised in the `/v1/paid/research` x402 challenge. Read in `src/routes/x402.ts`. Set to your real wallet to actually receive payment. | ### Database (optional group) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `DATABASE_URL` | no | _(unset → in-memory)_ | PostgreSQL connection string. When set, the API persists via `@settlekit/persistence` (drizzle, document-projection). When unset, an in-memory store is used. | ### Arc / USDC settlement (optional group — all-or-none) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `ARC_RPC_URL` | group | _(unset)_ | JSON-RPC endpoint for the Arc network used to read/verify USDC transfers. Required if any `ARC_*` is set. | | `ARC_USDC_ADDRESS` | group | _(unset)_ | USDC ERC-20 contract address on Arc. Must be a `0x`-prefixed 20-byte address. Required if any `ARC_*` is set. | | `ARC_CHAIN_ID` | group | _(unset)_ | Numeric chain id for the Arc network. Range 1–2,147,483,647. Required if any `ARC_*` is set. | | `ARC_MIN_CONFIRMATIONS` | no | `3` | Confirmations required before a payment is treated as settled. Range 1–1000. | Setting any one of `ARC_RPC_URL` / `ARC_USDC_ADDRESS` / `ARC_CHAIN_ID` without the other two fails boot. Without the Arc group, x402 paid endpoints return an honest rejection (`x402 settlement requires Arc (set ARC_RPC_URL)`). ### Circle (optional group) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `CIRCLE_API_KEY` | group | _(unset)_ | Circle API key for Gateway / x402 settlement rails. Presence enables the real Circle client. | | `CIRCLE_BASE_URL` | no | _(SDK default)_ | Override Circle API base URL (e.g. for sandbox). Only meaningful when `CIRCLE_API_KEY` is set. | ### GitHub App (optional group — all-or-none) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `GITHUB_APP_ID` | group | _(unset)_ | Numeric GitHub App id. Range 1–2,147,483,647. | | `GITHUB_APP_PRIVATE_KEY` | group | _(unset)_ | GitHub App private key (PEM). Use literal `\n` escapes or a single-line PEM. | | `GITHUB_INSTALLATION_ID` | group | _(unset)_ | Default installation id the API/worker authenticate as. Range 1–2,147,483,647. | | `GITHUB_WEBHOOK_SECRET` | no | _(unset)_ | Secret used to verify inbound GitHub webhook signatures. Optional within the group. | Required group keys: `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_INSTALLATION_ID`. Setting some but not all fails boot. ### Discord (optional group) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `DISCORD_BOT_TOKEN` | group | _(unset)_ | Bot token used to add/remove Discord roles on purchase. Presence enables the real Discord client. | ### Email / Resend (optional group — all-or-none) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `RESEND_API_KEY` | group | _(unset)_ | Resend API key for transactional delivery/receipt email. | | `EMAIL_FROM` | group | _(unset)_ | From address for outbound transactional email. | Setting one without the other fails boot. ### S3 / R2 object storage (optional group — all-or-none) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `S3_BUCKET` | group | _(unset)_ | Bucket holding sellable file assets. | | `S3_REGION` | group | _(unset)_ | S3/R2 region. Use `auto` for Cloudflare R2. | | `S3_ACCESS_KEY_ID` | group | _(unset)_ | S3/R2 access key id. | | `S3_SECRET_ACCESS_KEY` | group | _(unset)_ | S3/R2 secret access key. | | `S3_ENDPOINT` | no | _(native AWS S3)_ | S3/R2 endpoint URL. Required for R2; omit for native AWS S3. Optional within the group. | Required group keys: `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`. --- ## Worker (`apps/worker`) Built from `apps/worker/src/config.ts`. The worker runs the recurring jobs (delivery, payment confirmation, access sync, renewals, webhook retry, and the email sweeps). Required variables fail boot if missing. ### Required integrations | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `ARC_RPC_URL` | **yes** | — | JSON-RPC endpoint used to confirm on-chain USDC settlement. | | `ARC_USDC_ADDRESS` | **yes** | — | USDC contract address (`0x` 20-byte). | | `ARC_CHAIN_ID` | no | `1` | Arc chain id. Range 1–2,147,483,647. | | `ARC_MIN_CONFIRMATIONS` | no | `3` | Confirmations before a payment is settled. Range 1–1000. | | `RESEND_API_KEY` | **yes** | — | Resend API key for receipt/reminder/dunning/access emails. | | `EMAIL_FROM` | no | `SettleKit ` | From address for worker-sent email. | | `GITHUB_APP_ID` | no | `1` | GitHub App id used for access reconciliation. Range 1–2,147,483,647. | | `GITHUB_APP_PRIVATE_KEY` | **yes** | — | GitHub App private key (PEM). | | `GITHUB_INSTALLATION_ID` | no | `1` | Installation id the worker authenticates as. Range 1–2,147,483,647. | | `DISCORD_BOT_TOKEN` | **yes** | — | Bot token used to revoke/grant Discord roles during access sync. | | `FILE_DELIVERY_BASE_URL` | **yes** | — | Base URL embedded in worker-generated signed download links. | | `FILE_DELIVERY_SECRET` | **yes** | — | HMAC secret used to sign worker-generated download URLs. | | `FILE_DELIVERY_EXPIRES_SEC` | no | `3600` | Signed-link lifetime (seconds). Range 60–2,592,000. | | `FILE_DELIVERY_MAX_DOWNLOADS` | no | `5` | Max downloads per signed link. Range 1–10,000. | | `LICENSE_TOKEN_SECRET` | **yes** | — | HMAC secret used to sign license tokens (must match the API). | | `WEBHOOK_SIGNING_SECRET` | **yes** | — | HMAC secret used to sign outbound webhooks dispatched by delivery actions (must match the API). | ### Subscription / dunning tuning | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `SUBSCRIPTION_GRACE_DAYS` | no | `3` | Grace window (days) applied when a renewal is missed. Range 1–365. | | `SUBSCRIPTION_RENEWAL_REMINDER_DAYS` | no | `7` | Send a renewal reminder when `currentPeriodEnd` is within this many days. Range 1–365. | ### Job intervals (milliseconds) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `WORKER_DELIVERY_INTERVAL_MS` | no | `5000` | How often pending delivery runs execute. Range 250–3,600,000. | | `WORKER_PAYMENT_INTERVAL_MS` | no | `10000` | How often pending payments are polled for on-chain confirmation. Range 250–3,600,000. | | `WORKER_ACCESS_SYNC_INTERVAL_MS` | no | `300000` | How often access is reconciled and expired grants revoked. Range 1,000–86,400,000. | | `WORKER_RENEWAL_INTERVAL_MS` | no | `600000` | How often subscriptions are advanced/graced/expired. Range 1,000–86,400,000. | | `WORKER_WEBHOOK_RETRY_INTERVAL_MS` | no | `30000` | How often failed webhooks are redelivered. Range 1,000–86,400,000. | | `WORKER_RECEIPT_EMAIL_INTERVAL_MS` | no | `60000` | How often confirmed payments are swept for an unsent receipt email. Range 1,000–86,400,000. | | `WORKER_RENEWAL_REMINDER_INTERVAL_MS` | no | `3600000` | How often upcoming renewals are swept for a reminder email. Range 1,000–86,400,000. | | `WORKER_DUNNING_EMAIL_INTERVAL_MS` | no | `3600000` | How often grace/past-due subscriptions are swept for a dunning email. Range 1,000–86,400,000. | | `WORKER_ACCESS_EMAIL_INTERVAL_MS` | no | `60000` | How often succeeded delivery runs are swept for an access-granted email. Range 1,000–86,400,000. | ### Persistence | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `DATABASE_URL` | no | _(unset → in-memory)_ | Shared Postgres connection. When set, the worker reads/persists to the shared database; when unset it runs against a process-local in-memory store. | --- ## x402 Gateway (`services/x402-gateway`) — Go Standalone reverse proxy that gates an upstream origin behind an x402 USDC paywall. Built from `services/x402-gateway/config.go`. Fails fast on any missing required var or malformed value. | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `LISTEN_ADDR` | no | `:8402` | TCP address the HTTP server binds to. | | `UPSTREAM_URL` | **yes** | — | Origin that paid requests are reverse-proxied to. Must be a valid URL. | | `PRICE` | **yes** | — | Decimal major-unit price owed per call, e.g. `0.005`. Must be a non-negative decimal. | | `CURRENCY` | no | `USDC` | Settlement asset. Only `USDC` is supported. | | `NETWORK` | **yes** | — | Chain a payment must settle on. One of `arc`, `base`, `ethereum`. | | `PAY_TO` | **yes** | — | Destination address payments must be sent to. | | `PRODUCT_ID` | **yes** | — | Product id attributing the gated call for usage accounting. | | `RESOURCE` | **yes** | — | Canonical identifier of the protected resource. | | `VERIFY_URL` | no | _(local verify)_ | When set, a payment proof is POSTed here; the verifier must respond `{ "ok": true }`. Must be a valid URL. | | `NONCE` | conditional | _(derived)_ | Stable nonce advertised in every challenge. If empty, an HMAC-derived nonce is used instead. | | `X402_HMAC_SECRET` | conditional | — | Secret that signs derived nonces. **Either `NONCE` or `X402_HMAC_SECRET` must be set**, or boot fails. | --- ## Arc Indexer (`services/arc-indexer`) — Rust Polls an Arc/EVM node for USDC `Transfer` events to a watched address and posts confirmations to the SettleKit API. Built from `services/arc-indexer/src/config.rs`. Addresses are normalized to lowercase `0x` + 40 hex; required vars fail fast. | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `ARC_RPC_URL` | **yes** | — | JSON-RPC HTTP endpoint of the Arc/EVM node. | | `ARC_USDC_ADDRESS` | **yes** | — | USDC ERC-20 contract address (20-byte hex, with or without `0x`). | | `WATCH_ADDRESS` | **yes** | — | Payout address to watch as the `to` of relevant Transfer events. | | `SETTLEKIT_API_URL` | **yes** | — | Base URL of the SettleKit API (trailing slash trimmed). | | `SETTLEKIT_API_KEY` | **yes** | — | Bearer API key used to authenticate confirmation requests. | | `POLL_INTERVAL_SECS` | no | `12` | Seconds between RPC polls. Must be greater than zero. | | `CONFIRMATIONS` | no | `3` | Confirmations required before a transfer is posted to the API. | | `START_BLOCK` | no | _(chain head)_ | Optional starting block. When unset, the indexer starts at the chain head. | --- ## License Gateway (`services/license-gateway`) — Rust, port 8090 Edge service that verifies license keys against the SettleKit API with a local verification cache. Built from `services/license-gateway/src/config.rs`. | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `SETTLEKIT_API_URL` | no | `http://localhost:8787` | Base URL of the upstream SettleKit API (trailing slash trimmed). | | `SETTLEKIT_API_KEY` | **yes** | — | Bearer API key used to authenticate against the SettleKit API. | | `PORT` | no | `8090` | TCP port the gateway binds to. Must be 1–65535. | | `CACHE_TTL_SECS` | no | `30` | How long a cached verification result remains valid. | | `REQUEST_TIMEOUT_SECS` | no | `10` | Timeout applied to each upstream HTTP request. Must be greater than zero. | --- ## Webhook Relay (`services/webhook-relay`) — Rust, port 8091 Standalone HMAC-signing webhook fan-out/redelivery service. Built from `services/webhook-relay/src/config.rs`. | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `PORT` | no | `8091` | TCP port the HTTP server binds to. | | `SIGNING_SECRET` | **yes** | — | HMAC-SHA256 secret applied to every outbound delivery body. Must be at least 8 characters. | | `MAX_RETRIES` | no | `5` | Max delivery attempts per subscriber before giving up. Must be greater than zero. | | `RETRY_BASE_MS` | no | `500` | Base delay (ms) for the exponential backoff schedule. Must be greater than zero. | --- ## SDKs and CLIs All first-party SDKs and the CLI resolve the API base URL and key from the same two environment variables (constructor arguments take precedence). | Variable | Required | Default | Read by | Purpose | | --- | --- | --- | --- | --- | | `SETTLEKIT_API_URL` | no | `http://localhost:8787` | Python SDK, Go CLI (`agentpay`), Arc Indexer, License Gateway; Node SDK by convention | Base URL of the SettleKit HTTP API. | | `SETTLEKIT_API_KEY` | yes¹ | _(none)_ | Node SDK, Python SDK, Go CLI, Arc Indexer, License Gateway | Bearer token sent as `Authorization: Bearer `. | ¹ Required for authenticated calls. The Python SDK raises if neither an argument nor `SETTLEKIT_API_KEY` is provided. The Go CLI sends it only when set (unauthenticated public endpoints work without it). ### Python SDK x402 example helpers (`sdks/python/examples`) These are read only by the bundled paid-API example, not by the core SDK: | Variable | Default | Purpose | | --- | --- | --- | | `SETTLEKIT_PAY_TO` | `0xYourMerchantWalletAddress` | Destination wallet advertised in the example's x402 challenge. | | `SETTLEKIT_NETWORK` | `base` | Settlement network for the example. | | `SETTLEKIT_VERIFY_MODE` | `accept` | Verifier mode; set to `api` to verify proofs against the API. | --- ## Next.js apps (dashboard 3001, marketplace 3002, checkout 3003, admin 3004, docs 3005) | Variable | Required | Default | Purpose | | --- | --- | --- | --- | | `NEXT_PUBLIC_API_URL` | no | `http://localhost:8787` | Public base URL of the SettleKit API, read by the browser-facing Next apps. Must be `NEXT_PUBLIC_*` to be exposed to the client bundle. | | `PORT` | no | per-app | Listen port when an app is started with `next dev/start -p $PORT`. Default ports: dashboard 3001, marketplace 3002, checkout 3003, admin 3004, docs 3005. | --- ## Quick start ### Minimal local development (in-memory, no integrations) The API boots with **no** variables set — every integration falls back to its in-memory double and persistence is in-memory: ```bash pnpm --filter @settlekit/api dev ``` Optionally pin a port and a bootstrap key so you can create real API keys: ```bash PORT=8787 API_BOOTSTRAP_KEY=dev_bootstrap_key pnpm --filter @settlekit/api dev ``` ### With Postgres persistence ```bash export DATABASE_URL="postgresql://settlekit:settlekit@localhost:5432/settlekit" pnpm --filter @settlekit/database db:migrate # or: make db-migrate pnpm --filter @settlekit/api dev ``` ### Production secrets to override These have insecure development defaults and **must** be set to strong, unique values in production (and must match between the API and worker where noted): - `LICENSE_TOKEN_SECRET` (API + worker — must match) - `WEBHOOK_SIGNING_SECRET` (API + worker — must match) - `AUTH_COOKIE_SECRET` (API) - `FILE_DOWNLOAD_SECRET` (API) / `FILE_DELIVERY_SECRET` (worker) - `SIGNING_SECRET` (webhook-relay, ≥ 8 chars) - `X402_HMAC_SECRET` (x402-gateway) - Unset `API_BOOTSTRAP_KEY` once real API keys exist. ### API envelope and auth recap - Success responses: `{"data": T}`. Errors: `{"error": {"code", "message"}}`. - Authenticated endpoints require `Authorization: Bearer `. - x402 paid endpoints under `/v1/paid/*` are public and return HTTP 402 + `PaymentRequirements` until a valid USDC payment proof is supplied; settlement is verified on-chain via Arc when `ARC_*` is configured.