settlekit/docs/CONFIGURATION.md
2026-06-17 02:09:36 +03:00

20 KiB
Raw Permalink Blame History

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 <receipts@settlekit.dev> 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 <key>.

¹ 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:

pnpm --filter @settlekit/api dev

Optionally pin a port and a bootstrap key so you can create real API keys:

PORT=8787 API_BOOTSTRAP_KEY=dev_bootstrap_key pnpm --filter @settlekit/api dev

With Postgres persistence

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 <apiKey>.
  • 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.