Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
# ────────────────────────────────────────────────────────────────────────────
# three.ws — backend environment
# Copy to .env.local for local dev. Production runs on Cloud Run; store secrets
# in Google Secret Manager and attach them as Cloud Run secret references.
# ────────────────────────────────────────────────────────────────────────────
# Public site origin (no trailing slash)
PUBLIC_APP_ORIGIN=https://three.ws
# Postgres (Neon serverless driver — HTTPS connection string)
DATABASE_URL=postgres://user:[email protected]/neondb?sslmode=require
# S3-compatible storage (AWS S3, Cloudflare R2, Backblaze B2, etc.). Treat both
# credential fields as secrets in production; see docs/ops/hosting-and-credentials.md.
S3_ENDPOINT=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
S3_BUCKET=3d-agent-avatars
# Public CDN base URL for the bucket (custom domain or provider default)
S3_PUBLIC_DOMAIN=https://pub-<hash>.r2.dev
# Public asset URLs are published as https://three.ws/cdn/<r2-key> (api/cdn-object.js),
# not as the bucket origin above: that origin is rate-limited and CORS-restricted.
# Upstash Redis — REQUIRED in production for x402 payment idempotency (USE-15).
# Without these, every /api/x402/* endpoint exits with code 1 on cold-start (500).
# Create a database at https://console.upstash.com → Redis, then copy the REST URL
# and REST token. If you linked via the Vercel KV integration the vars are named
# three_KV_REST_API_URL / three_KV_REST_API_TOKEN — re-add them under these names.
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
# Optional dedicated CACHE store (recommended at scale). The vars above back the
# fail-closed rate limiter; pointing the best-effort caches (galaxy feed, pulse,
# agent lists, …) at a SECOND Upstash store stops large cache writes from contending
# with — and burning the command quota of — the limiter. That contention is what
# causes the redis SET timeouts on /api/galaxy/flows. Co-locate this store with your
# production Cloud Run region for low write latency. Unset = caches share the store
# above (no behavior change). Legacy KV integrations may prefix the second store
# with `cache`: cache_KV_REST_API_*.
UPSTASH_CACHE_REST_URL=
UPSTASH_CACHE_REST_TOKEN=
# Optional cache tuning (api/_lib/cache.js). CMD timeout: per-command deadline in ms
# before falling back to memory (default 3000, clamped 500–30000) — raise it when the
# cache store is not co-located with the function region. Max value bytes: values whose
# serialized JSON exceeds this stay memory-only instead of timing out over REST and
# flapping the write-suppression gate (default 262144 = 256KB, clamped 16KB–8MB).
CACHE_REDIS_CMD_TIMEOUT_MS=
CACHE_REDIS_MAX_VALUE_BYTES=
# Optional: Error monitoring
SENTRY_DSN=
# Optional: Payment/business metrics → Axiom (success rate, p95 latency, per network).
# Unset = no-op (see api/_lib/axiom.js). Create an API token + dataset at axiom.co,
# then set both. AXIOM_URL overrides the host (e.g. https://api.eu.axiom.co for EU).
AXIOM_TOKEN=
AXIOM_DATASET=
# JWT signing — rotate by appending to key set, never remove the old one mid-rotation
# Generate with: openssl rand -base64 64
JWT_SECRET=
# Active key id (for future rotation)
JWT_KID=k1
# Dedicated secret for encrypting custodial agent wallet private keys at rest
# (AES-256-GCM via HKDF, with a random per-record salt). Keep this DISTINCT from
# JWT_SECRET so wallet confidentiality never depends on the session secret and
# rotating one doesn't affect the other. If unset, the app falls back to
# JWT_SECRET (with a warning). Generate with: openssl rand -base64 48
WALLET_ENCRYPTION_KEY=
# Password hashing cost (bcryptjs rounds)
PASSWORD_ROUNDS=11
# /api/chat picks a provider in this order (first key found wins, unless the
# client explicitly sets `provider` in the request body):
# 1. ANTHROPIC_API_KEY → Claude Sonnet 5 (best tool calling)
# 2. OPENROUTER_API_KEY → free-tier models (Llama 3.3 70B, GPT-OSS, Hermes 3)
# 3. GROQ_API_KEY → Llama 3.3 70B on Groq (sub-second latency)
# 4. OPENAI_API_KEY → gpt-4o-mini
# Anthropic — get a key at https://console.anthropic.com
ANTHROPIC_API_KEY=
# Optional overrides for chat model + output cap.
CHAT_MODEL=claude-sonnet-5
CHAT_MAX_TOKENS=1024
# Admin key for three.ws chat brand config. Store in Secret Manager and attach to
# Cloud Run; enter it in chat settings to unlock the branding panel.
# Generate with: openssl rand -base64 32
CHAT_ADMIN_KEY=
# OpenRouter — powers free-tier models in /api/chat AND the built-in proxy at
# /api/chat/proxy. Free-tier (`:free` suffix) models include Llama 3.3 70B,
# GPT-OSS 120B, Hermes 3 405B. Sign up free at https://openrouter.ai
OPENROUTER_API_KEY=
# Groq — fastest hosted Llama (sub-second). Get a key at https://console.groq.com
GROQ_API_KEY=
# NVIDIA NIM — free, OpenAI-compatible inference for 100+ hosted models
# (Nemotron, DeepSeek, Kimi, MiniMax, Llama 4). One key unlocks all of them at
# https://integrate.api.nvidia.com/v1. Powers the NVIDIA providers in
# /api/brain/chat and a free fallback tier in the embed proxy (/api/llm/anthropic).
# Get a free key (no credit card) at https://build.nvidia.com → any model → "Get API Key".
# NOTE: this is the hosted-API var. NGC_API_KEY is only for self-hosted NIM Docker
# containers (nvcr.io) — not used here. Same secret value, different name/path.
NVIDIA_API_KEY=
# Total time the text-to-image paint ladder (Vertex -> NIM FLUX -> Livepeer ->
# Replicate) may spend before the forge answers a fast, retryable 429. Each lane
# keeps its own ceiling; this bounds the ladder as a whole so a stalled leading
# lane cannot hold a submit open past the caller's socket. Default 60000.
# TEXT_TO_IMAGE_BUDGET_MS=60000
#
# The concept-image ladder, free-first: Vertex Imagen (when GOOGLE_CLOUD_PROJECT
# is set and billing is live) -> NVIDIA NIM FLUX.1-dev (NVIDIA_API_KEY) -> HF
# routed providers fal-ai then nscale (HF_TOKEN also unlocks two image rungs,
# billed through the HF account) -> Pollinations (keyless, always present) ->
# Replicate (REPLICATE_API_TOKEN, paid backstop). No single provider outage
# can leave text-to-3D without an image.
# SambaNova Cloud (free tier, no card): Llama 3.3 70B on its own free quota
# pool (about 20 req/min, 200K tokens/day per model). Optional rung in the
# shared LLM chain (api/_lib/llm.js). Sign up at https://cloud.sambanova.ai
SAMBANOVA_API_KEY=
# Mistral Experiment tier (free, no card): about 1B tokens/month at 1 req/sec
# in exchange for opting the account into data training. The largest free
# quota in the shared LLM chain. Get a key at https://console.mistral.ai
MISTRAL_API_KEY=
# Z.AI (Zhipu) key: permanently free, rate-limited GLM Flash models
# (glm-4.7-flash) on an OpenAI-compatible endpoint. Optional rung in the
# shared LLM chain. Sign up at https://z.ai, docs at https://docs.z.ai
ZAI_API_KEY=
# SiliconFlow international (free tier): Qwen3 8B step-down rung near the end
# of the free section of the shared LLM chain. Get a key at
# https://siliconflow.com
SILICONFLOW_API_KEY=
# LLM7.io: Gemma 4 31B on an OpenAI-compatible endpoint. The rung is KEYLESS
# (anonymous access reaches LLM7's turbo models); a free key only raises the
# rate limit. Free key at https://dash.llm7.io/#/api-keys
LLM7_API_KEY=
# Kilo Code gateway: Nemotron 3 Ultra 550B and Super 120B on its free pool.
# The rungs are KEYLESS (about 200 req/hr anonymous) and only ever request
# ':free' models; a key from https://app.kilo.ai/profile only raises the limit.
KILO_API_KEY=
# Cloudflare Workers AI (free tier, 10,000 neurons/day): 70B-class Llama at
# the edge. The rung needs BOTH values; the OpenAI-compatible URL embeds the
# account id. Create a Workers AI scoped token at https://dash.cloudflare.com
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_AI_API_TOKEN=
# OpenAI — used for gpt-4o-mini fallback. Get a key at https://platform.openai.com
OPENAI_API_KEY=
# xAI Grok: paid OpenAI-compatible inference (grok-4.5 flagship, grok-4.3
# long-context, grok-4.1-fast budget). Selectable in /api/chat, /api/brain/chat,
# the embed proxy, and a paid rung in the shared LLM chain. Users can also bring
# their own key (Settings > AI Provider Keys). XAI_API_KEY works as an alias.
# Get a key at https://console.x.ai
GROK_API_KEY=
# Alibaba Cloud DashScope (international) — direct Qwen access for the brain
# demo (/api/brain/chat). When unset, Qwen requests fall back to OpenRouter.
# Get a key at https://dashscope-intl.console.aliyun.com
DASHSCOPE_API_KEY=
# ModelScope — Alibaba's model hub. Optional; enables Qwen3-Coder-480B and
# other ModelScope-hosted models via their OpenAI-compatible inference API.
# Get a token at https://modelscope.cn
MODELSCOPE_API_KEY=
# IBM watsonx.ai — adds IBM Granite as a selectable brain in /api/chat (the 3D
# avatar) and /api/brain/chat (the model playground). The key is exchanged for
# a short-lived IAM bearer token and every call is scoped to your project, so
# both WATSONX_API_KEY and WATSONX_PROJECT_ID (or WATSONX_SPACE_ID) are required
# for Granite to appear. Create an API key at https://cloud.ibm.com/iam/apikeys
# and find the project id under watsonx.ai → project → Manage → General.
WATSONX_API_KEY=
WATSONX_PROJECT_ID=
# WATSONX_SPACE_ID= # alternative to WATSONX_PROJECT_ID
# WATSONX_URL=https://us-south.ml.cloud.ibm.com # regional host (eu-de, jp-tok, …)
# WATSONX_MODEL_ID=ibm/granite-3-8b-instruct # default Granite chat model
# WATSONX_API_VERSION=2024-05-31
# IBM watsonx Orchestrate — adds a "watsonx Orchestrate" brain to /api/chat so a
# three.ws 3D avatar becomes the embodied front-end of an enterprise Orchestrate
# agent. The URL is the agent's OpenAI-compatible chat-completions endpoint (the
# Orchestrate instance "Test URL"; "/chat/completions" is appended if omitted).
# The key is the bearer token from the agent's Agent Connect config. Both are
# required for the provider to appear.
WATSONX_ORCHESTRATE_URL=
WATSONX_ORCHESTRATE_API_KEY=
# WATSONX_ORCHESTRATE_AGENT=orchestrate-agent # agent id sent as the model field
# Privy wallet auth (client-side — get app ID from https://dashboard.privy.io)
VITE_PRIVY_APP_ID=
# Privy app ID (server-side — for verifying identity tokens in /api/auth/privy/verify)
PRIVY_APP_ID=
# Privy app secret — from https://dashboard.privy.io → Settings → API keys.
# Used to fetch linked wallets from the Privy user API after login.
# Optional: when unset, wallet sync is skipped (login still works).
PRIVY_APP_SECRET=
# Avaturn (photo-to-avatar pipeline). API key lives server-side; used by
# /api/onboarding/avaturn-session to exchange 3 selfies for a session URL.
# Sign up at https://avaturn.me/developer.
AVATURN_API_KEY=
# Optional override for self-hosted / staging Avaturn deployments.
AVATURN_API_URL=https://api.avaturn.me
# Avaturn default editor — opened by the "Use default avatar" card at /create.
# No session API / no photos required. Point at the hosted editor URL provided
# by Avaturn; the developer ID (if needed) is appended as a query param.
VITE_AVATURN_EDITOR_URL=https://editor.avaturn.me/
VITE_AVATURN_DEVELOPER_ID=
# Avatar regeneration provider (optional, auto-detected when omitted).
# Resolution order when AVATAR_REGEN_PROVIDER is unset:
# 1. REPLICATE_API_TOKEN present → "replicate" (paid, fast, reliable)
# 2. GCP_RECONSTRUCTION_URL set → "gcp" (self-hosted, custom GPU)
# 3. HF_TOKEN present → "huggingface" (free HF Spaces queue)
# 4. otherwise → "none" (501 returned)
# Set this explicitly to force a provider (or "stub" for queue-only testing,
# or "none" to disable selfie reconstruct entirely).
AVATAR_REGEN_PROVIDER=
# Replicate (when AVATAR_REGEN_PROVIDER=replicate). Get an API token at
# https://replicate.com/account/api-tokens. Each mode maps to a model version
# hash from replicate.com — pick a model that takes a GLB URL (or text prompt
# for restyle, or image URL(s) for reconstruct) and returns a GLB asset.
#
# Recommended commercial-OK starting points (2026-05):
# reconstruct → tencent/hunyuan-3d-3.1 (image-to-textured-GLB, ~30-60s, best quality/price)
# OR camenduru/tripo-sr (cheaper fallback, ~$0.0023/run, no PBR textures)
# restyle → tencent/hunyuan-3d-3.1 (same engine, text or image conditioning)
# remesh → mesh-cleanup pipelines on replicate
# retex → image-conditioned texturing models on replicate
# rerig → VAST-AI-Research/UniRig (MIT, SIGGRAPH 2025 SOTA — deploy via cog from HF
# weights until on Replicate, or proxy a dedicated GPU)
#
# Copy the version hash from each model's "Run with API" tab on replicate.com.
REPLICATE_API_TOKEN=
REPLICATE_RECONSTRUCT_MODEL=
REPLICATE_RESTYLE_MODEL=
REPLICATE_REMESH_MODEL=
REPLICATE_RETEX_MODEL=
REPLICATE_RERIG_MODEL=
# /forge text→3D — reference-image model for the flux pass that precedes TRELLIS
# reconstruction. Optional: defaults to black-forest-labs/flux-schnell (Apache-2.0,
# fast). Override with any owner/name[:version] or version hash on Replicate.
REPLICATE_TXT2IMG_MODEL=
# /forge persists every generation (durable GLB + reference image + the human
# keep/discard verdict — the text→3D data flywheel) when BOTH a database
# (DATABASE_URL) and object storage (S3_* above) are configured. With either
# missing, /forge still generates models; it just doesn't retain them or show
# the "Your creations" gallery. No extra config needed beyond those two.
# Hugging Face provider (when AVATAR_REGEN_PROVIDER=huggingface, or auto-
# detected when only HF_TOKEN is set). Read-only token is sufficient since
# the default target Space is public. Get one at huggingface.co/settings/tokens.
#
# Hits the Gradio /call/<api_name> queue endpoint of a public image-to-3D
# Space. Default targets tencent/Hunyuan3D-2's generation_all API, which
# accepts our 3 selfie photos as mv_image_{front,left,right} and returns
# a textured GLB. Override the target by setting the two env vars below.
#
# Reliability note: HF Spaces share free GPU pools (ZeroGPU). Queue waits
# and per-Space quotas can cause 30s-2min latency or outright rejection
# during peak hours. For production traffic, prefer REPLICATE_API_TOKEN.
HF_TOKEN=
HF_RECONSTRUCT_SPACE=tencent/Hunyuan3D-2
HF_RECONSTRUCT_API_NAME=generation_all
# ── Persona Hub (optional) ────────────────────────────────────────────────────
# When set, /api/auth/persona/issue signs tokens with ES256 (asymmetric) so
# tenants can verify offline via the JWK Set at /.well-known/jwks.json. When
# unset, persona tokens are signed with HS256 (shared JWT_SECRET) and tenants
# must hit /api/auth/persona/verify to validate.
#
# Generate a fresh keypair with:
# node scripts/generate-persona-key.mjs
# then keep the private value local or add it to Google Secret Manager. Attach
# the production secret to Cloud Run; never pass it in a command argument.
PERSONA_JWKS_KID=
PERSONA_JWKS_PRIVATE_KEY_PEM=
# Optional — auto-derived from the private key if omitted:
PERSONA_JWKS_PUBLIC_KEY_PEM=
# ── ERC-7710 Delegation Relayer (POST /api/permissions/redeem) ───────────────
# Enable the server-side relayer endpoint (default: false).
PERMISSIONS_RELAYER_ENABLED=false
# Hex private key of the relayer EOA that pays gas for redeemDelegations.
# This is NOT the user's key — only the agent's server-side relayer.
# Generate: node -e "const {Wallet} = require('ethers'); const w = Wallet.createRandom(); console.log(w.privateKey, w.address)"
# NEVER commit a real value. Rotate through Google Secret Manager and update
# the Cloud Run secret reference.
AGENT_RELAYER_KEY=0x...
# EIP-55 checksummed address derived from AGENT_RELAYER_KEY — fund with testnet ETH.
AGENT_RELAYER_ADDRESS=0x...
# Per-chain RPC URLs for DelegationManager calls.
# Pattern: RPC_URL_<CHAINID>. Override the default public RPCs with Alchemy/Infura for production.
RPC_URL_1=https://cloudflare-eth.com # Ethereum mainnet (use Alchemy/Infura in prod)
RPC_URL_8453=https://mainnet.base.org # Base mainnet (use Alchemy/Infura in prod)
RPC_URL_84532=https://sepolia.base.org # Base Sepolia (primary dev chain)
RPC_URL_11155111=https://rpc.sepolia.org # Ethereum Sepolia
RPC_URL_421614=https://sepolia-rollup.arbitrum.io/rpc # Arbitrum Sepolia (use Alchemy/Infura in prod)
RPC_URL_11155420=https://sepolia.optimism.io # Optimism Sepolia (use Alchemy/Infura in prod)
# Optional PAID metered reserve per chain (e.g. a Quicknode credit-funded
# endpoint). Pattern: RPC_URL_<CHAINID>_LAST_RESORT. Tried AFTER every free
# public fallback so its monthly quota is only spent when the free chain fails.
# RPC_URL_8453_LAST_RESORT=
# Per-chain DelegationManager contract address overrides (optional).
# Defaults are from MetaMask Delegation Toolkit v1. Override if you deploy a custom instance.
# DELEGATION_MANAGER_ADDRESS_84532=0x...
# DELEGATION_MANAGER_ADDRESS_11155111=0x...
# ── IPFS pinning — used by POST /api/pinning/pin before on-chain registration.
# Pinata (preferred): get JWT from https://app.pinata.cloud/keys
PINATA_JWT=
# Web3.Storage (fallback): get token from https://web3.storage/tokens
# (legacy v1 API — upload endpoint: https://api.web3.storage/upload)
WEB3_STORAGE_TOKEN=
# ── KOL wallet P&L analytics (api/kol/[action].js wallets handler) ─────────
# Birdeye API key for Solana wallet portfolio + P&L data.
# Get one at https://birdeye.so — free tier allows ~100 req/min.
BIRDEYE_API_KEY=
# ── EVM gas oracle chain (api/_lib/gas-oracles.js, GET /api/v1/gas) ────────
# Both optional: the keyless path fully works without them.
# Blocknative Gas API (https://www.blocknative.com/gas-platform); a key raises rate limits.
BLOCKNATIVE_API_KEY=
# Owlracle (https://owlracle.info); a key swaps the shared guest quota for a private one.
OWLRACLE_API_KEY=
# ── Pump.fun live feed integration (api/_lib/pumpfun-mcp.js) ──────────────
# Upstream pumpfun-claims-bot MCP server URL. When set, /api/agents/pumpfun
# and /api/agents/pumpfun-feed are enabled, the cron at /api/cron/pumpfun-signals
# starts crawling, and the pumpfun-watch agent skills become functional.
# Run `npx pumpfun-claims-bot` (or deploy via Railway) to host the upstream MCP.
PUMPFUN_BOT_URL=
# Optional bearer token if the upstream MCP requires auth.
PUMPFUN_BOT_TOKEN=
# ── aixbt intelligence bridge (api/_lib/aixbt.js, api/aixbt/*) ───────────────
# Connects three.ws agents to aixbt's live narrative + momentum intelligence.
# When set, /api/aixbt/{intel,projects,grounding,chat} go live, the aixbt agent
# skills (aixbt-intel, aixbt-scan) work, and the paid MCP tools (aixbt_intel,
# aixbt_projects) return real data. Without it those endpoints return a designed
# "not configured" 503 — never fake data.
# Get a key with a full aixbt.tech subscription or by paying for a time-boxed
# x402 key pass: POST https://api.aixbt.tech/x402/v2/api-keys/{1d|1w|4w} (USDC on Base).
AIXBT_API_KEY=
# Optional override for the aixbt REST base (defaults to the v2 API).
AIXBT_API_BASE=https://api.aixbt.tech/v2
# ── ERC-8004 agent registry crawler (api/cron/erc8004-crawl) ─────────────────
# Blocks to scan on first run (no cursor). Default 2000 keeps cron under 300s.
# For a one-time backfill, set to 50000 and trigger the endpoint manually —
# do NOT leave this value set for normal cron operation.
ERC8004_CRAWL_LOOKBACK=
# ── Rider VR gate — token-gated access via $THREE payments ───────────────────
# Solana wallet that receives 8,000 $THREE to unlock the VR experience.
RIDER_VAULT_ADDRESS=wwwDoZ4C3qcqeBWCugzAGAikPyEPSfmRJ3Lyi9dWE3T
# Shared secret sent by Helius in the 'authorization' header on webhook pushes.
# Generate: openssl rand -base64 32
RIDER_HELIUS_WEBHOOK_SECRET=
# ── Helius — NFT portfolio, enhanced transactions, wallet monitoring ──────────
# Used by: /api/agents/nfts (nft-portfolio + wallet-activity skills),
# /api/nft/resolve, /api/wallet/balances, /api/tx/explain,
# and pump.fun wallet webhooks.
# Get a free key at https://dev.helius.xyz (free tier: 100k req/mo DAS + RPC).
HELIUS_API_KEY=
# Shared secret echoed by Helius in the 'authorization' header on webhook pushes.
# Generate: openssl rand -base64 32
HELIUS_WEBHOOK_AUTH=
# ── Solana RPC overrides (used by Solana attestation crawler + pump skills) ──
# Defaults to public mainnet/devnet — set Helius/Triton/QuickNode for prod.
SOLANA_RPC_URL=
SOLANA_RPC_URL_DEVNET=
# ── Solana Developer Platform (SDP) — custodial wallets, SPL issuance, ───────
# payments, and compliance screening via the Solana Foundation's enterprise API
# (https://platform.solana.com). Used by the same-origin proxy at /api/sdp/* and
# the helpers in api/_lib/sdp.js.
# When set, /api/sdp/v1/{wallets,issuance,payments,compliance,...} go live under
# our origin (the key stays server-side, never reaches the browser). Without it,
# authenticated routes return a designed "not configured" 503 — never fake data;
# the unauthenticated /api/sdp/health probe still works.
# Get a project-scoped key from https://platform.solana.com (sandbox keys hit
# the same wire surface — swap the key to go to production).
SDP_API_KEY=
# Optional override for the SDP API host. Defaults to the production API; point
# at the sandbox or a self-hosted Worker deployment if needed.
SDP_API_BASE=https://api.solana.com
# ── x402 micropayments (POST /api/mcp) ─────────────────────────────────────
# Per-network payTo wallets that receive USDC for paid MCP calls.
X402_PAY_TO_SOLANA=wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU
X402_PAY_TO_BASE=0x4022de2d36c334e73c7a108805cea11c0564f402
# ── BNB Chain gasless sends (MegaFuel) ─────────────────────────────────────
# Optional NodeReal MegaFuel API key. NOT used by api/_lib/bnb/megafuel.js at
# send time — pm_isSponsorable / eth_sendRawTransaction run unauthenticated
# against the public bsc-megafuel(-testnet).nodereal.io endpoints; sponsorship
# is resolved server-side purely by matching the tx's `from` address against a
# pre-provisioned sponsor policy. This key is only needed for the separate
# ONE-TIME policy-management step (pm_createPolicy/pm_updatePolicy against
# open-platform-ap.nodereal.io/{key}/megafuel(-testnet), not yet implemented
# here) that whitelists a sender/contract. Until a policy exists for your
# sender, every send transparently self-pays — the feature works end-to-end
# without this key. Provision at https://dashboard.nodereal.io (MegaFuel
# product). Never commit a real key.
NODEREAL_MEGAFUEL_KEY=
# Funded BSC testnet (chainId 97) deployer/sender key for live gasless + contract
# proofs. Generate a throwaway: node -e "console.log(require('viem/accounts').generatePrivateKey())"
# then fund the address from https://www.bnbchain.org/en/testnet-faucet. Never commit a real key.
BNB_TESTNET_DEPLOYER_KEY=
# Deployed WorldMoves.sol (contracts/src/WorldMoves.sol) contract address per
# network, read by api/_lib/bnb/world-moves.js's worldMovesAddress(). BSC
# mainnet is unused this campaign; BSC testnet deploy is currently blocked on
# BNB_TESTNET_DEPLOYER_KEY above (see contracts/DEPLOYMENTS.md's WorldMoves
# section) — set this the moment `forge script script/DeployWorldMoves.s.sol
# --broadcast` produces a real public-testnet address. Until set, any call
# that needs the address (buildMoveTx/sendMove without an explicit
# opts.address) throws a clear "not deployed yet" error rather than guessing.
WORLD_MOVES_ADDRESS_MAINNET=
WORLD_MOVES_ADDRESS_TESTNET=
# Greenfield vault platform account (prompt 09/11 — api/_lib/bnb/greenfield-write.js,
# api/bnb/vault-upload.js). Creates buckets/objects on Greenfield on behalf of
# sellers; same secp256k1 curve as a BSC EOA, so it falls back to
# BNB_TESTNET_DEPLOYER_KEY above when unset — one funded throwaway key can drive
# both legs. Generate + fund the same way as BNB_TESTNET_DEPLOYER_KEY. Never
# commit a real key.
GREENFIELD_VAULT_OPERATOR_KEY=
# Greenfield bucket that hosts every vault object (default matches
# specs/vault-manifest.md's example). Must be a globally unique, DNS-safe
# Greenfield bucket name (lowercase letters/digits/hyphens, 3-63 chars).
GREENFIELD_VAULT_BUCKET_TESTNET=three-ws-vault-testnet
GREENFIELD_VAULT_BUCKET_MAINNET=three-ws-vault-mainnet
# Deployed GreenfieldVault.sol (contracts/src/GreenfieldVault.sol) address per
# network, read raw by api/bnb/vault-upload.js's vaultContractAddress(). Deploy
# is blocked on BNB_TESTNET_DEPLOYER_KEY above (see contracts/DEPLOYMENTS.md's
# GreenfieldVault section) — until set, vault-upload records the manifest spec's
# own placeholder address and returns contractDeployed:false, never a fabricated
# real-looking address.
GREENFIELD_VAULT_ADDRESS_MAINNET=
GREENFIELD_VAULT_ADDRESS_TESTNET=
# Dedicated EIP-712 signing key for signed offers and payment receipts (USE-17).
# This is a dedicated signing key, NOT a wallet that holds funds. Generate with:
# node -e "console.log(require('viem/accounts').generatePrivateKey())"
# Never reuse an X402_PAY_TO_* address here — the issuer module rejects it on boot.
# Rotate by changing the value and bumping `#key-1` -> `#key-2` in code if needed.
# When unset, signed offers/receipts are silently disabled (rollback without redeploy).
X402_RECEIPT_SIGNING_KEY=0xREPLACE_WITH_DEDICATED_SIGNING_KEY_HEX_64_CHARS
# Prepaid credits (POST /api/credits/deposit): the Solana wallet users send SOL or
# $THREE to when topping up their balance. Defaults to X402_PAY_TO_SOLANA, then the
# $THREE treasury, if unset — set it to route deposits to a dedicated wallet.
CREDITS_DEPOSIT_WALLET_SOLANA=
# USDC asset addresses (mainnet).
X402_ASSET_MINT_SOLANA=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
X402_ASSET_ADDRESS_BASE=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
# Price in base units (USDC = 6 decimals; 1000 = 0.001 USDC).
X402_MAX_AMOUNT_REQUIRED=1000
# Skill royalties (docs/skill-royalties.md). The platform's share of each paid
# call to a marketplace skill, in basis points; the author keeps the rest and
# wins the rounding. Defaults to 250 (2.5%, the marketplace fee rate) and is
# clamped to 5000 in code, so a misconfig can never take more than half a call.
X402_SKILL_ROYALTY_PLATFORM_BPS=250
# The in-app runtime royalty lane settles through EIP-7710 delegated
# permissions. Leave false: with it off, settleRoyalties and the daily
# settle-royalties cron leave pending rows untouched and redeem nothing.
# Turning it on starts moving real USDC on a schedule: read the activation
# checklist in docs/skill-royalties.md first. The per-call x402 rail does NOT
# depend on this flag; it pays authors at settlement either way.
SKILL_ROYALTIES_EVM_7710_ENABLED=false
# USE-15 — TTL (seconds) for the payment-identifier idempotency cache.
# Same paymentId within the window returns the cached response without
# re-charging. Per-route override via paidEndpoint({ paymentIdentifier:
# { ttlSeconds } }). 3600s = "long TTL" per x402 docs.
X402_IDEMPOTENCY_TTL_SECONDS=3600
# Per-network facilitators. PayAI supports both Solana and Base mainnet;
# x402.org's reference facilitator only supports base-sepolia, so do not point
# X402_FACILITATOR_URL_BASE at it for production.
#
# SOLANA ROUTING (the real defaults — see api/_lib/x402/ring-config.js):
# 1. If X402_FACILITATOR_URL_SOLANA is set explicitly, it ALWAYS wins.
# 2. Else, if X402_SELF_FACILITATOR_ENABLED=true, Solana settlement DEFAULTS to
# this deploy's own self-hosted facilitator ($APP_ORIGIN/api/x402-facilitator).
# 3. Else it falls back to the external PayAI facilitator below.
# So the self-hosted facilitator is NOT "always-on": it is the default ONLY when
# X402_SELF_FACILITATOR_ENABLED=true AND no explicit URL overrides it. Leave the
# line below commented for stock (external) routing; uncomment + point it at your
# self facilitator to force in-house settlement regardless of the flag.
# X402_FACILITATOR_URL_SOLANA=https://three.ws/api/x402-facilitator
X402_FACILITATOR_URL_BASE=https://facilitator.payai.network
# Advertise the Base (eip155:8453) payment rail WITHOUT CDP credentials. OFF by
# default: setting X402_FACILITATOR_URL_BASE alone is NOT treated as proof the
# facilitator settles — a stale/decommissioned host answers /verify with 404 and
# every Base-preferring buyer would pay, fail verification, and get a 502. Set to
# true ONLY after confirming your non-CDP Base facilitator actually verifies+settles.
# With CDP creds set (CDP_API_KEY_ID + CDP_API_KEY_SECRET), Base routes to Coinbase
# and this flag is unnecessary.
X402_ADVERTISE_BASE=false
# Optional bearer tokens for self-hosted/private facilitators.
X402_FACILITATOR_TOKEN_SOLANA=
X402_FACILITATOR_TOKEN_BASE=
# Solana fee payer advertised to clients (must match facilitator's /supported).
X402_FEE_PAYER_SOLANA=2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
# ── Closed-loop x402 ring (self-hosted facilitator) ────────────────────────
# The self-cycled agent economy: platform-controlled wallets pay the platform's
# OWN x402 endpoints in real USDC, settled by the platform's OWN facilitator, so
# no third party ever touches a ring settlement. All OFF by default — the
# facilitator answers 503 and nothing settles until you turn it on. Full guide:
# docs/x402-ring-economy.md. Generate the wallets with:
# node scripts/x402-ring-setup.mjs
#
# Turn the facilitator ON. BOTH of these are required for in-house settlement:
# - X402_SELF_FACILITATOR_ENABLED=true (else /api/x402-facilitator → 503)
# - X402_FACILITATOR_URL_SOLANA pointed at your self facilitator, OR left unset
# so the flag's default (this deploy's /api/x402-facilitator) applies.
# Setting the flag WITHOUT correcting an external X402_FACILITATOR_URL_SOLANA is
# the mis-envelope /api/x402-ring and /api/x402-status report as a config_warning.
X402_SELF_FACILITATOR_ENABLED=false
# Extra treasury/payTo addresses the self facilitator will settle to, beyond
# X402_PAY_TO_SOLANA (comma-separated). Only platform-controlled wallets belong
# here — this allowlist is what keeps every settled dollar inside the platform.
X402_SELF_FACILITATOR_PAYTO_ALLOWLIST=
# Sponsor (fee-payer) secret the facilitator co-signs with in SPONSOR mode. Its
# pubkey MUST equal X402_FEE_PAYER_SOLANA. Not needed in self-pay mode (below).
X402_FEE_PAYER_SECRET_BASE58=
# Sponsor SOL floor (lamports). Below this the facilitator refuses to settle,
# pausing the loop before it can drain your SOL. Default 0.02 SOL.
X402_SPONSOR_SOL_FLOOR_LAMPORTS=20000000
# Ring payer USDC float floor (atomic, 6dp). Below this the wallet-balance monitor
# raises an ops alert to top up the payer's recirculating USDC. Default $5.
X402_RING_PAYER_USDC_FLOOR_ATOMIC=5000000
# Self-pay mode (RECOMMENDED, lowest fee): the payer pays its own 1-signature fee
# (5000 lamports) and no sponsor key is needed. Off = sponsor mode (2 signatures,
# ~2× the base fee). When off, /api/x402-ring flags ring_self_pay_off.
X402_RING_SELF_PAY=true
# Ring payer wallet secret — the wallet that pays the ring (USDC float that
# recirculates). Fund with USDC + a little SOL for its own fees in self-pay mode.
X402_SEED_SOLANA_SECRET_BASE58=
# Treasury secret — used by the rebalancer to sweep treasury→payer so the float
# never drains one-way. Pubkey is X402_PAY_TO_SOLANA. Missing → warn.
X402_TREASURY_SECRET_BASE58=
# Per-call ring settlement size (USDC atomics, 6dp). Bigger = fewer txs = less
# SOL burned for the same gross volume. $1.00 default; raise to $10–$100 for
# near-zero SOL. MUST be ≤ X402_VOLUME_PER_RUN_CAP_ATOMIC (5-min volume loop) AND
# ≤ X402_RING_TICK_CAP_ATOMIC (per-minute ring tick) or ring-settle is skipped
# every tick (flagged ring_price_exceeds_run_cap; payX402 also logs it loudly).
# The two cap defaults below are set to fit this price out of the box.
X402_PRICE_RING_SETTLE=1000000
# Per-tick spend ceiling for the 5-min VOLUME LOOP (USDC atomics). One tick can't
# exceed this on top of the daily cap. Default $1.10 — RAISED from the old $0.05
# so it accommodates the $1.00 ring-settle it rotates (at $0.05 ring-settle was
# silently skipped every cycle). Keep it ≥ X402_PRICE_RING_SETTLE.
X402_VOLUME_PER_RUN_CAP_ATOMIC=1100000
# Daily spend cap for the autonomous loop (USDC atomics) — your daily volume
# target. Leave unset for the loop's built-in default. SEPARATE from the ring
# tick's own daily cap (X402_RING_DAILY_CAP_ATOMIC below) — the two never mix.
X402_AUTONOMOUS_DAILY_CAP_ATOMIC=
# ── Fresh-wallet workers (api/cron/x402-fresh-workers.js) ──────────────────────
# Every minute: mint brand-new wallets, fund each with one job's USDC plus its
# own fees, have each buy real work (a 3D prop for /forged or a dataset for
# /data-desk) over x402, then empty and close it. Fired by the economy
# heartbeat; ON by default; the global X402_AUTONOMOUS_ENABLED=false pauses it.
# Docs: docs/x402-fresh-workers.md.
X402_FRESH_WORKERS_ENABLED=true
# Fresh wallets minted (and jobs bought) per minute. Default 3.
X402_FRESH_WORKERS_PER_TICK=3
# One paid Forge generation every N ticks; the other slots buy datasets.
# Default 10 → ~144 new library props a day.
X402_FRESH_WORKERS_FORGE_EVERY_N_TICKS=10
# The lane's OWN daily USDC ceiling (atomics), summed from x402_autonomous_log
# rows tagged pipeline='fresh-workers'. Default $40. The USDC recirculates to
# the treasury; this bounds the float in flight, not a cost.
X402_FRESH_WORKERS_DAILY_CAP_ATOMIC=40000000
# Wall-clock budget per tick (ms), kept under the heartbeat's 60 s abort.
X402_FRESH_WORKERS_TICK_BUDGET_MS=50000
# A wallet left mid-flight for this long (s) is reclaimed by the next tick.
X402_FRESH_WORKERS_RECLAIM_AFTER_S=90
# Sweep retries before a wallet is marked stranded and an ops alert fires.
X402_FRESH_WORKERS_MAX_SWEEP_ATTEMPTS=20
# How long (h) a fresh wallet stays in the controlled-wallet set so the leak
# scanner classifies its funding leg as internal.
X402_FRESH_WORKERS_MEMBERSHIP_HOURS=36
# ── Per-minute ring tick (api/cron/x402-ring-tick.js) ──────────────────────────
# A dedicated * * * * * cron that produces steady, capped, fee-minimal paid
# traffic: cheap tips/services every minute plus a periodic ring-settle carrier.
# ON by default once the ring envelope above is valid (validateRingConfig clean);
# X402_RING_TICK_ENABLED=false or the global X402_AUTONOMOUS_ENABLED=false pause it.
X402_RING_TICK_ENABLED=true
# Paid calls attempted per minute (cheap tips dominate the count). Default 3.
X402_RING_TICK_CALLS=3
# Fire one ring-settle every Nth tick (the fee-optimal large-volume carrier;
# 0 disables it). Default 5 → a settle roughly every 5 minutes.
X402_RING_SETTLE_EVERY_N_TICKS=5
# Per-tick spend ceiling (USDC atomics). MUST fit a settle tick: ring-settle
# price + the cheap co-riders. Default $1.10 (fits $1.00 ring-settle + 2 tips).
X402_RING_TICK_CAP_ATOMIC=1100000
# Ring tick's OWN daily ceiling (USDC atomics), summed from x402_autonomous_log
# rows tagged pipeline='ring-tick'. Does NOT consume the autonomous loop's cap.
# Default $50. At 3 calls/min the tick reaches this bound mid-day then no-ops
# cleanly until UTC midnight — raise it for full-day coverage.
X402_RING_DAILY_CAP_ATOMIC=50000000
# Minimum treasury→payer sweep the rebalancer bothers with (USDC atomics).
# Default $0.10. Lower it so the (120s) rebalancer tops the payer up sooner as
# the per-minute tick cycles the float in small increments.
X402_RING_MIN_SWEEP_ATOMIC=100000
# Revenue share of every treasury sweep routed to the economy master wallet, in
# basis points (default 2000 = 20%; 0 disables the leg). This is the ONE inflow
# that keeps the funding root's USDC stocked so economy-fuel can convert it to
# SOL and treasury-topup can hold every engine (circulation treasury, ring
# sponsor) above its floor. Ledgered as kind='revshare' in x402_ring_ledger and
# verified per-leg by the ring reconciler.
X402_RING_MASTER_REVSHARE_BPS=2000
# Hard per-payment network-fee ceiling (lamports). payX402 refuses to broadcast
# a ring payment whose fee configuration could exceed it. Default 10000 —
# double the 1-signature self-pay floor, so both modes fit with headroom.
X402_RING_MAX_FEE_PER_TX_LAMPORTS=10000
# Daily SOL fee budget for the whole ring (lamports). The nightly fee audit
# pages ops when the day's real, chain-read burn crosses it. Default 0.05 SOL.
X402_RING_DAILY_FEE_BUDGET_LAMPORTS=50000000
# Only OUR endpoints get paid — disables the external x402 section of the loop.
X402_EXTERNAL_ENABLED=false
# No charity split leaves the ring (basis points; 0 = nothing leaves).
X402_CHARITY_AUDIT_BPS=0
# ERC-8021 Schema 2 builder-code app identifier (USE-20). When set, every 402
# challenge advertises the `builder-code` extension, every paid request must
# echo it (anti-tamper), and settlement-tx calldata is suffixed with a CBOR
# map for on-chain attribution. Pattern: ^[a-z0-9_]{1,32}$. Leave unset to
# disable. Coinbase builder rewards / x402scan analytics use this to credit
# the app that exposed the paid endpoint.
X402_BUILDER_CODE_APP=three_d_agent
# Wallet builder code our own buyer client attributes itself with when
# making outbound paid calls (USE-20). Distinct from X402_BUILDER_CODE_APP:
# this populates `w` on PaymentPayload.extensions["builder-code"] so the
# settlement CBOR records both who exposed the endpoint AND who paid for it.
X402_BUILDER_CODE_WALLET=3d_agent
# Spending caps for buyer clients (USE-22). All values are micro-USD
# (6-decimal atomics of USDC); leave any line blank to skip that cap.
# Example: 1_000_000 = $1.00; 100_000 = $0.10; 1_000 = $0.001.
# Per-call ceiling enforced before signing; hourly/daily are sliding
# windows tracked in Redis (server) or localStorage (browser).
X402_MAX_PER_CALL_ATOMIC=1000000
X402_MAX_PER_HOUR_ATOMIC=10000000
X402_MAX_PER_DAY_ATOMIC=100000000
# ── x402 access-control bypass (USE-23) ────────────────────────────────────
# Shared secret for internal service-to-service calls. Any Vercel function
# (cron job, webhook handler, the agent runtime) that hits one of our own
# paid /api/x402/* endpoints sends `X-API-Key: $INTERNAL_API_KEY` to skip
# the 402 challenge — we don't pay ourselves to call our own infra.
# Generate: openssl rand -base64 32
# Compared with constant-time equality in api/_lib/x402/access-control.js.
# Leave unset to disable internal bypass (subscription keys and OAuth bypass
# still work). Partner / subscription keys are issued at
# POST /api/x402/admin/subscriptions and stored hashed in x402_subscriptions.
INTERNAL_API_KEY=
# ── play / holder gate HMAC secret (REQUIRED IN PRODUCTION) ────────────────
# The single HMAC key that mints and verifies every short-lived entry credential:
# /play sign-in nonces + passes (api/_lib/play-pass.js), holder-world passes
# (api/_lib/holder-pass.js), guest/presence tokens, $THREE quote signing, clash,
# and world-service auth. The standalone Colyseus server (multiplayer/) verifies
# the same tokens, so it MUST be set to the IDENTICAL value there.
# Fail-closed by design: when unset with NODE_ENV=production, these modules refuse
# to sign/verify with the public dev secret and throw — surfacing as a 500 on
# GET /api/play/nonce (the first endpoint /play hits) and on the holder gate.
# Leave unset only in local dev / CI (an insecure dev secret is used, with a warning).
# Generate: openssl rand -base64 48
HOLDER_PASS_SECRET=
# ── multiplayer ↔ API shared secret (presence + world persistence) ─────────
# One HMAC secret shared between this API and the standalone Colyseus server
# (multiplayer/). The API mints presence tickets the realm rooms verify, and the
# server signs world-persistence writes (api/world/[action]) the API verifies.
# Falls back to HOLDER_PASS_SECRET so a single secret can configure every gate.
# Generate: openssl rand -base64 32
MULTIPLAYER_SHARED_SECRET=
# Base URL the multiplayer server uses to reach the persistence API for durable
# per-world saves. Defaults to https://three.ws; set to http://localhost:3000 in
# local dev so room builds persist against your dev API. (multiplayer-side env.)
WORLD_API_BASE=
# ── x402 Offer & Receipt extension (USE-17) ────────────────────────────────
# Signs every 402 offer and every settled-payment receipt so buyers get
# cryptographic proof of the interaction. Verifiers resolve the signer key via
# /.well-known/did.json (rewritten to /api/x402/did). Buyers can re-query their
# own receipts later via /api/x402/my-receipts.
#
# Key separation is CRITICAL — this MUST be a dedicated EOA/JWK, never one of
# the X402_PAY_TO_* wallets. Receipts are server claims about transactions;
# co-mingling with the funds-receiving wallet would imply the payment cosigner
# endorses every receipt ever issued. The issuer module fails loudly on boot
# if the derived address collides with any X402_PAY_TO_* key.
#
# EIP-712 mode (default): set OFFER_RECEIPT_SIGNING_PRIVATE_KEY to a fresh
# 0x-hex EVM private key. Generate with:
# node -e "console.log(require('viem/accounts').generatePrivateKey())"
# JWS mode (did:web): set OFFER_RECEIPT_FORMAT=jws + OFFER_RECEIPT_JWK to a
# JSON-encoded JWK private key. Vercel has no KMS; for production-grade key
# custody, swap the issuer for a Google KMS / AWS KMS / HashiCorp Vault signer.
# When all signing keys are unset, the extension is silently disabled and the
# 402/200 wire format stays valid (extension is purely additive).
OFFER_RECEIPT_SIGNING_PRIVATE_KEY=
OFFER_RECEIPT_FORMAT=eip712
OFFER_RECEIPT_JWK=
OFFER_RECEIPT_JWS_ALG=EdDSA
# Bare hostname used to build did:web identifiers (no scheme, no path).
# Defaults to the host parsed from PUBLIC_APP_ORIGIN.
SERVER_DOMAIN=
# Coinbase Developer Platform (CDP) facilitator. REQUIRED for agentic.market /
# CDP Bazaar listing — only endpoints whose first verify+settle is processed
# by CDP get cataloged. PayAI is a fine fallback for non-Bazaar use.
# When both keys are set, Base mainnet payments route to CDP automatically.
# Sign up at https://cdp.coinbase.com → Project → API keys → Generate.
X402_CDP_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402/facilitator
CDP_API_KEY_ID=
# Auto-detected. Either:
# * Newer Ed25519: base64-encoded 32-byte seed or 64-byte (seed||pub).
# * Legacy ECDSA P-256: PEM-encoded EC private key (paste the full
# "-----BEGIN EC PRIVATE KEY----- ... -----END EC PRIVATE KEY-----"
# value in Vercel; newlines are preserved).
CDP_API_KEY_SECRET=
# zauthx402 — telemetry + monitoring for x402 endpoints. Optional; when unset
# the SDK is not invoked. Get a key at https://zauth.inc/provider-hub.
ZAUTH_API_KEY=
# Set to "1" to enable verbose [zauthSDK:*] logs in Vercel.
ZAUTH_DEBUG=
# Set to "1" to include request/response bodies in zauth telemetry. OFF by
# default — these are payment + MCP endpoints, so bodies (payment payloads,
# tool args) are withheld from the third-party backend. Endpoint health is
# reported regardless. Enable only for short-lived debugging.
ZAUTH_INCLUDE_BODIES=
# Auto-refund hot wallets. When at least one is set, the SDK automatically
# refunds callers who pay and receive a 5xx or empty response. Use DEDICATED
# keypairs funded only with the refund float — never the main treasury keys.
#
# EVM (Base) refund wallet — hex private key (0x…). Generate:
# node -e "console.log(require('viem/accounts').generatePrivateKey())"
ZAUTH_REFUND_PRIVATE_KEY=
# Solana refund wallet — base58 secret key. Generate:
# node -e "const {Keypair}=require('@solana/web3.js');console.log(require('bs58').default.encode(Keypair.generate().secretKey))"
ZAUTH_SOLANA_PRIVATE_KEY=
# Per-refund ceiling in USD. Defaults to 0.10 (above our highest tool price $0.05).
ZAUTH_REFUND_MAX_USD=
# Daily / monthly spend caps across all auto-refunds. Defaults: $25 / $250.
ZAUTH_REFUND_DAILY_CAP_USD=
ZAUTH_REFUND_MONTHLY_CAP_USD=
# ── Resend (transactional email) ─────────────────────────────────────────────
# Powers: account welcome, email verification codes, password reset, subscription
# confirmations, dunning, and newsletter contact capture (/api/newsletter-subscribe).
# Sign up at https://resend.com → API Keys → Create.
RESEND_API_KEY=
# Sender identity. Domain MUST be verified in Resend (SPF + DKIM DNS records)
# before sends will succeed. Use Resend's [email protected] while verifying.
EMAIL_FROM=three.ws <[email protected]>
# Reply-To for transactional mail (defaults to [email protected] so replies reach a human).
[email protected]
# Audience UUID for /api/newsletter-subscribe. Without it, the endpoint silently
# no-ops. Create in Resend → Audiences, then paste the UUID here.
RESEND_AUDIENCE_ID=
# ── GitHub OAuth (social memory seeding) ─────────────────────────────────────
# Create an OAuth App at https://github.com/settings/developers.
# Callback URL: https://your-domain.com/api/auth/github/callback
GITHUB_OAUTH_CLIENT_ID=
GITHUB_OAUTH_CLIENT_SECRET=
# ── X (Twitter) OAuth 2.0 PKCE (social memory seeding) ───────────────────────
# Create an app at https://developer.twitter.com with Read + OAuth 2.0 enabled.
# Callback URL: https://your-domain.com/api/auth/x/callback
X_OAUTH_CLIENT_ID=
X_OAUTH_CLIENT_SECRET=
# ── Enterprise SAML 2.0 SSO (three.ws is the Service Provider) ───────────────
# Lets platform users sign in through your IdP (IBM Cloud App ID, Okta, Azure
# AD, Google Workspace, …). When configured, an "SSO" button appears on /login.
#
# Setup:
# 1. Register three.ws as a SAML app in your IdP using our SP details:
# Entity ID / Audience : https://your-domain.com/api/auth/saml/metadata
# ACS (Reply) URL : https://your-domain.com/api/auth/saml/acs
# Or just hand the IdP our metadata document (it has everything):
# https://your-domain.com/api/auth/saml/metadata
# 2. Point us at the IdP — EITHER paste its metadata URL (simplest)…
SAML_IDP_METADATA_URL=
# …OR set the fields explicitly (these win if both are present):
SAML_IDP_SSO_URL=
# IdP signing certificate — PEM block or bare base64. Literal "\n" escapes are
# fine (they're restored to newlines). Required for verifying assertions.
SAML_IDP_CERT=
# Optional: pins the expected assertion Issuer and enables IdP-initiated logout.
SAML_IDP_ENTITY_ID=
SAML_IDP_SLO_URL=
#
# IBM Cloud note: the IAM "Identity providers" screen makes IBM Cloud the SP and
# expects YOUR IdP — it is not itself a SAML IdP for third-party apps. To use IBM
# as the IdP here, create the SAML app in IBM Cloud App ID (or IBM Security
# Verify) and use ITS metadata URL / SSO URL / signing cert above.
#
# SP entity ID override (defaults to the metadata URL above). Set only if your
# IdP requires a specific Audience value.
SAML_SP_ENTITY_ID=
# Optional SP keypair (PEM) — when set, our AuthnRequests are signed and
# encrypted assertions can be decrypted. Most IdPs don't require this.
SAML_SP_PRIVATE_KEY=
SAML_SP_CERT=
# Security posture. The assertion must be signed by default; the response
# envelope signature is opt-in (many IdPs only sign the assertion).
SAML_WANT_ASSERTIONS_SIGNED=true
SAML_WANT_RESPONSE_SIGNED=false
SAML_SIGNATURE_ALGORITHM=sha256
# NameID format to request: "unspecified" (default — let the IdP decide) or a
# full URN, e.g. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
SAML_IDENTIFIER_FORMAT=unspecified
# Accepted clock skew (ms) between us and the IdP. Default 5s.
SAML_CLOCK_SKEW_MS=5000
# SP-initiated only by default (replay-resistant). Set true to also accept
# unsolicited IdP-initiated responses (no InResponseTo).
SAML_ALLOW_IDP_INITIATED=false
# Label on the /login SSO button.
SAML_BUTTON_LABEL=Single sign-on (SSO)
# ── News-feed syndication (admin "Publish" → Dev.to / Medium) ────────────────
# Used by /api/admin/news (the local-only CMS) to mirror newly-saved posts
# to external publishers. When unset, syndication for that target is silently
# skipped — the admin UI surfaces "skipped: <KEY> not set".
# See docs/syndication.md for setup details.
# Dev.to: generate at https://dev.to/settings/extensions ("Generate API Key")
DEV_TO_API_KEY=
# Medium: generate an integration token at https://medium.com/me/settings/security
# (Medium's API is deprecated for new accounts as of 2024 but still works for
# accounts that had API access enabled.) MEDIUM_AUTHOR_ID is optional —
# the syndicator auto-discovers it via /v1/me and caches in-memory.
MEDIUM_INTEGRATION_TOKEN=
MEDIUM_AUTHOR_ID=
# ── x402 MCP bridge (USE-11) ────────────────────────────────────────────────
# The mcp-bridge/ workspace is a Claude Desktop / Cursor MCP server that
# auto-pays for x402-paid HTTP endpoints. It registers a single
# `call_paid_endpoint` fallback tool plus one tool per resource discovered
# from the Coinbase x402 Bazaar. Channel state (batch-settlement vouchers)
# persists in ~/.x402-mcp-bridge/channels/client/ so Claude Desktop restarts
# don't re-deposit on the next call.
#
# Buyer keys — one of EVM or SVM is required for the bridge to start.
# These keys SIGN PAYMENTS. Never share them, never commit them, and never
# point them at a wallet you don't control.
MCP_BRIDGE_EVM_PRIVATE_KEY=
MCP_BRIDGE_SVM_PRIVATE_KEY=
# Per-call spending cap in atomic units of the accept's asset. Default 100000
# = $0.10 USDC (6 decimals). Payments above this are aborted with a clear
# error before any signature is created.
MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC=100000
# Max number of bazaar tools to register at startup. Set 0 to disable
# bazaar-driven dynamic tools (the fallback call_paid_endpoint still works).
MCP_BRIDGE_DISCOVER_LIMIT=20
# Override the bazaar discovery endpoint (default = CDP mainnet bazaar).
MCP_BRIDGE_BAZAAR_URL=https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources
# Batch-settlement tuning. The bridge pre-funds N request-amounts on the first
# call so subsequent voucher-only calls don't pay gas. MAX_DEPOSIT_ATOMIC is a
# hard ceiling on any single deposit (default $5).
MCP_BRIDGE_BATCH_DEPOSIT_MULTIPLIER=5
MCP_BRIDGE_MAX_DEPOSIT_ATOMIC=5000000
# Override where batch-settlement channel state is persisted. Defaults to
# ~/.x402-mcp-bridge/channels. Restart-safe.
X402_MCP_BRIDGE_CHANNELS_DIR=
# ── USE-10: @three-ws/mcp-server (paid MCP tools for Claude Desktop / Cursor) ─
# Bearer token for the hosted three.ws MCP endpoint (.mcp.json "3d-agent" remote).
# Get one from your three.ws dashboard. Never commit the literal value.
THREE_WS_MCP_TOKEN=
# Wallets that RECEIVE USDC payments when an MCP client pays for a tool call.
# Default to the existing X402_PAY_TO_* wallets when unset.
MCP_EVM_PAYMENT_ADDRESS=
# If unset, the stdio @three-ws/mcp-server still boots and routes paid-call USDC to the
# platform X402_PAY_TO_SOLANA payout; set a 32-44 char base58 wallet to collect it yourself.
MCP_SVM_PAYMENT_ADDRESS=
# Connector-review entitlement for the stdio @three-ws/mcp-server. Set MCP_REVIEW_SECRET on the
# server and hand a reviewer the SAME value as MCP_REVIEW_MODE in their client env; paid tools
# then run for real with NO charge. Off (no bypass) unless MCP_REVIEW_SECRET is set.
MCP_REVIEW_SECRET=
MCP_REVIEW_MODE=
# Max forge_free generations to prefer a durable result when the free NVIDIA lane degrades (1-4).
FORGE_FREE_ATTEMPTS=2
# Override the previewUrl returned by get_pose_seed.
MCP_POSE_PREVIEW_BASE=https://three.ws/pose
# Per-chain RPC override for agent_reputation reads. Example:
# MCP_AGENT_REP_RPC_8453=https://mainnet.base.org
# MCP_AGENT_REP_RPC_42161=https://arb1.arbitrum.io/rpc
# Block window scanned for recent ReputationSubmitted/Staked events (default
# 200000). Lower for high-RPS chains to keep RPC calls under provider limits.
MCP_AGENT_REP_LOG_WINDOW=200000
# ── @three-ws/omniology-mcp (Omniology contest MCP server) ────────────────────
# Stateless MCP server in packages/omniology-mcp: read tools wrap Omniology's
# PUBLIC contest feed; submit_entry settles USDC on Solana (x402) then forwards
# an authenticated POST to Omniology. Needs NO Redis/QStash — it proxies an
# external API. The stdio entry point fails fast at startup if the base URL is
# unset (config.js assertBaseUrl), so this is REQUIRED to run the server.
#
# Base URL of the Omniology contest API (serves /v1/contests/live and
# /v1/contests/{id}/entries). No default — point it at the live deployment.
OMNIOLOGY_BASE_URL=
# Optional bearer token sent to Omniology ONLY on the authenticated forward of a
# paid submit_entry. Never exposed to the MCP client. Leave unset for read-only.
OMNIOLOGY_API_KEY=
# Per-request timeout (ms) for calls to Omniology. Default 20000.
OMNIOLOGY_TIMEOUT_MS=20000
# Price charged for submit_entry (USDC), parsed as a "$X.XX" string. Default $0.05.
OMNIOLOGY_SUBMIT_PRICE_USD=$0.05
# x402 facilitator the submit_entry payment settles through. Both default to
# the payai network facilitator when unset; the token is only needed for
# facilitators that require auth.
X402_FACILITATOR_URL=https://facilitator.payai.network
X402_FACILITATOR_TOKEN=
# ── SNS subdomain minting on threews.sol ─────────────────────────────────────
# Base58-encoded 64-byte ed25519 secret for the wallet that owns the platform
# parent .sol domain (default `threews.sol`). The /api/sns-subdomain and
# /api/threews/subdomain endpoints use this key to sign createSubdomain +
# URL-record + transferSubdomain in a single atomic transaction, then hand the
# subdomain to the user. Leave unset to disable subdomain minting (both
# endpoints return 503 instead of attempting the on-chain write).
THREEWS_SOL_PARENT_SECRET_BASE58=
# Override the parent domain if the platform acquires a different root.
# Default: threews.sol.
THREEWS_SOL_PARENT_DOMAIN=threews.sol
# Origin used when writing the URL record on a freshly-minted subdomain.
# Brave's SNS resolver follows this URL when a user types `<label>.threews.sol`.
# Default: https://three.ws.
STOREFRONT_ORIGIN=https://three.ws
# ── Session + CSRF (server) ──────────────────────────────────────────────────
# Salt used to derive purchase-receipt keys and other internal HMACs. Falls
# back to the literal string "dev" if unset — that fallback is FINE in dev,
# CATASTROPHIC in prod (every install would share the same receipt namespace).
# Generate: openssl rand -base64 64
SESSION_SECRET=
# Escape hatch for CSRF enforcement on mutating endpoints. Set to "1" to
# disable for local automation / test harnesses. Leave UNSET in production —
# bearer-token requests are already exempt because the token itself proves
# intent (cookies aren't auto-attached on bearer requests).
CSRF_DISABLED=
# Generic bearer secret used by webhook handlers that don't have a provider-
# specific signing scheme (currently /api/webhooks/solana-pay). Senders must
# include `Authorization: Bearer $WEBHOOK_SECRET`. When unset, those webhooks
# reject every request.
# Generate: openssl rand -base64 32
WEBHOOK_SECRET=
# Legacy alias for PUBLIC_APP_ORIGIN used by api/_lib/email.js and a few
# auth callbacks. Always set BOTH to the same value during transition; the
# alias will be removed in a future cleanup pass.
APP_ORIGIN=https://three.ws
# ── Cron protection ──────────────────────────────────────────────────────────
# Shared secret expected as `Authorization: Bearer $CRON_SECRET` on calls to
# /api/cron/*. Google Cloud Scheduler supplies it to production jobs. The
# `x-vercel-cron` header is compatibility behavior, not the production auth
# path. Without CRON_SECRET, production scheduler calls fail closed.
# Generate: openssl rand -base64 32
CRON_SECRET=
# ── Pump.fun trade ingestion ─────────────────────────────────────────────────
# Trades are ingested from the chain itself: api/_lib/pump-onchain-trades.js
# holds one logsSubscribe on the pump program over the Solana RPC failover
# chain (free keyless lanes first; keyed/paid lanes as reserve) and decodes
# TradeEvents locally. This is the authoritative source and needs no key.
#
# Optional: pin the firehose to specific RPC endpoints (comma-separated
# http(s) URLs, tried first) instead of the derived free-first ordering.
PUMP_ONCHAIN_WS_URLS=
#
# Optional: PumpPortal per-mint trade stream as an augmenting second source.
# PumpPortal gates subscribeTokenTrade behind an API key whose linked wallet
# holds at least 0.02 SOL; without one the refusal is logged (throttled) and
# the on-chain firehose carries alone. subscribeNewToken (coin creations) is
# free and used regardless.
PUMPPORTAL_API_KEY=
# ── Database retention (/api/cron/db-retention) ──────────────────────────────
# Keeps the Neon branch under its project-size cap. The pump.fun intel firehose
# (pump_coin_intel + its mint-keyed satellites) ingests tens of thousands of rows
# a day; the retention cron prunes anything older than the window below and
# self-tunes under storage pressure. Docs: docs/ops/db-retention.md
#
# Normal retention window for the coin-intel firehose, in days. Clamped [2,365].
# Default 14 matches the smart-money engine's judge horizon. A 512 MB Neon free
# tier cannot physically hold 14 days of the firehose — the pressure valve below
# will hold a shorter effective window until the branch is upgraded. Raise this
# after moving to a larger Neon plan.
PUMP_INTEL_RETENTION_DAYS=14
# Hard floor the pressure valve tightens to when the branch is over the high-water
# mark. Clamped [1, PUMP_INTEL_RETENTION_DAYS]. Coins are judged within a day or
# two of launch, so 3 keeps everything load-bearing while shedding the oldest data.
PUMP_INTEL_MIN_RETENTION_DAYS=3
# Storage high-water mark in MB. At/above this the retention cron switches to the
# min window so the hard cap (512 MB on the free tier) is never actually reached.
# Clamped [128, 100000]. Lower it for more headroom; raise it after a plan upgrade.
DB_RETENTION_HIGH_WATER_MB=470
# ── Economy consolidation sweep (api/_lib/economy-sweepback.js) ───────────────
# The treasury-sweepback cron returns engine-signer surplus (SOL above each
# signer's operating float, plus stray token balances) to the economy master.
# Destination is locked in code to ECONOMY_MASTER_ADDRESS. Optional dust floor:
# a SOL sweep smaller than this is skipped so fees never exceed the return.
ECONOMY_SWEEPBACK_MIN_SOL=
# ── Per-signer floor overrides (api/_lib/solana-signers.js) ───────────────────
# Override any registry signer's SOL floor (and topup refill target) without a
# code deploy: SIGNER_MIN_SOL_<NAME> / SIGNER_REFILL_TO_SOL_<NAME>, signer name
# upper-cased with dashes as underscores. Applied at module load, so topup
# targets, balance alerts, and the floors dashboard all agree. Example: park the
# autonomous launcher's 1 SOL floor while launches are paused so its deficit
# stops outranking active engines in the deficit-sorted topup queue.
# SIGNER_MIN_SOL_COIN_LAUNCHER_MASTER=0.05
# ── Agent activity engine (api/_lib/circulation.js, /api/cron/pulse-tick) ─────
# Operates a pool of platform-owned agents that transact with one another on-chain
# (tips, payments, trades, launches, on-chain registration) so the live money feed
# reflects real wallet activity. Fully inert unless ENABLED is truthy AND a funded
# treasury secret is set. All amounts are small and topped up just-in-time.
CIRCULATION_ENABLED=
# 64-byte Solana secret key (base58, base64, or JSON array) for the funded treasury
# wallet the engine tops agent wallets up from.
CIRCULATION_TREASURY_SECRET=
# 'mainnet' (default) or 'devnet'.
CIRCULATION_NETWORK=
# Target number of operated agents (default 14) and light actions per tick (default 2).
CIRCULATION_POOL_TARGET=
CIRCULATION_ACTIONS_PER_TICK=
# Adaptive rate governor. The tick reads the treasury once and funds only as many
# SOL-spending actions as it can afford, filling the rest of the budget with
# actions that cost nothing on-chain (trials, reviews, listings). Without this the
# engine planned a fixed rate, drained the treasury, and then produced nothing but
# "treasury balance too low" skips until a human refilled it.
# SOL held back so the treasury can always pay its own transfer fees (default 0.005).
CIRCULATION_TREASURY_RESERVE_SOL=
# Estimated just-in-time top-up one paid action draws; sets the throttle curve
# (default 0.012, the observed per-action funding need).
CIRCULATION_EST_ACTION_SOL=
# Optional: enables on-chain (ERC-8004) agent registration. EVM private key (0x…)
# of a gas-funded treasury wallet, plus the chain id (default 8453 / Base). Without
# this, the deploy action is skipped.
CIRCULATION_EVM_TREASURY_SECRET=
CIRCULATION_EVM_CHAIN_ID=
# ── IRL proof-of-presence (epic IRL-Hardening H3) ────────────────────────────
# HMAC key that signs the short-lived proof-of-presence tokens minted by
# POST /api/irl/fix-token and verified on the GET /api/irl/pins nearby read
# (api/_lib/irl-presence.js). A token binds a nearby read to the coarse (~150 m)
# cell the caller actually had a GPS fix in, so a viewer can't browse pins at a
# location they aren't standing near.
#
# Enforcement is gated on this secret being set to a STRONG value (>= 16 chars):
# - SET in production: the nearby read REQUIRES a valid `x-irl-fix` token and
# fails CLOSED (401/403) when it's missing, expired, forged, or out of area.
# - UNSET (dev/preview): proof-of-presence is BYPASSED so local/sandbox testing
# isn't gated — the read works exactly as before. The active mode is logged
# once at cold start by both fix-token.js and pins.js.
# Production MUST set this. Generate: openssl rand -base64 32
IRL_FIX_SECRET=
# ── Upstash QStash (async work queue) ────────────────────────────────────────
# Powers async knowledge ingest at /api/widgets/:id/knowledge-process. Without
# QSTASH_TOKEN the publisher disables itself silently and large PDFs/URLs fall
# back to inline processing (slower, risk of timeout on Vercel's 60s limit).
# QSTASH_CURRENT_SIGNING_KEY is required to verify the worker's incoming
# webhook signature — calls without a valid signature are rejected.
# Get keys at https://console.upstash.com → QStash.
QSTASH_TOKEN=
QSTASH_CURRENT_SIGNING_KEY=
QSTASH_NEXT_SIGNING_KEY=
# ── $THREE token split, quote & treasury wiring ──────────────────────────────
# The $THREE mint and the wallets every priced split routes to. Read by
# api/token/[action].js (quote/settle) and api/cron/rewards-distribute.js.
#
# THREE_TREASURY_WALLET, THREE_REWARDS_WALLET and THREE_QUOTE_SECRET are REQUIRED
# in production: token/config.js + token/quote.js fail closed when they are unset
# (the source of the live `POST /api/token/quote → 503 THREE_TREASURY_WALLET is
# required in production` log entries) rather than silently routing treasury funds
# to a placeholder or signing quotes with the dev key. Set all three in prod.
# Platform $THREE mint. Defaults to the canonical mint; override only for a
# devnet/test mint. There is no other coin — never point this at a different one.
THREE_TOKEN_MINT=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump
# pump.fun mints are 6-decimal. Override only for a non-pump mint.
THREE_TOKEN_DECIMALS=6
# Treasury wallet — receives the treasury share of every split. REQUIRED in prod.
THREE_TREASURY_WALLET=
# Holder-rewards (reflections) wallet — receives the `rewards` share of every
# split; the rewards cron drains it back to holders pro-rata. REQUIRED in prod.
THREE_REWARDS_WALLET=
# Burn address. Defaults to the Solana incinerator (unspendable — tokens sent
# there leave circulation permanently). Override only with another null address.
THREE_BURN_ADDRESS=1nc1nerator11111111111111111111111111111111
# HMAC secret that signs payment quotes so a client cannot tamper with the quoted
# amount or split after the server prices it. REQUIRED in prod. NEVER log this.
THREE_QUOTE_SECRET=
# Validity window (seconds) for an issued quote. Short enough that a quoted price
# can't be exploited after the market moves; long enough to sign + send one tx.
THREE_QUOTE_TTL_S=90
# ── Payments / fees / treasury wiring ────────────────────────────────────────
# Recipient wallets for /api/payments/* checkout sessions. Set per-chain EVM
# overrides as PAYMENT_RECIPIENT_EVM_<chainId> (e.g. PAYMENT_RECIPIENT_EVM_8453)
# to route Base payments to a different treasury than other EVM chains.
PAYMENT_RECIPIENT_EVM=
PAYMENT_RECIPIENT_SOLANA=
# Platform fee charged on creator earnings, in basis points (100 bps = 1%).
# Default 250 (2.5%). Validated to 0–10000 inclusive.
PLATFORM_FEE_BPS=250
# Platform treasury keypair for agent monetization withdrawals. Base58-encoded
# 64-byte Solana keypair or JSON-array format. Used by the monetization-payouts
# (process-withdrawals) cron to send USDC to agent owners. When unset, the
# cron skips Solana withdrawals with a clear error. Alias for TREASURY_KEYPAIR.
PLATFORM_TREASURY_KEYPAIR=
# Referral commission paid out on confirmed purchases when the buyer arrived
# via a referral link, in basis points. Default 500 (5%).
REFERRAL_COMMISSION_BPS=500
# Optional override for purchase-receipt HMAC key. When unset, derived from
# SESSION_SECRET via sha256(SESSION_SECRET + ':receipts'). Rotate by setting
# this to a fresh secret — old receipts will fail to verify.
PURCHASE_RECEIPT_KEY=
# Override the Solana USDC mint (default = mainnet USDC). Used by the
# /api/payments price builder and the Solana fee-payer logic.
SOLANA_USDC_MINT=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# ── Solana / EVM RPC overrides (additional) ──────────────────────────────────
# Primary Solana RPCs (mainnet + devnet). Public endpoints rate-limit hard —
# set Helius / Triton / Quicknode URLs for production. SOLANA_MAINNET_RPC is
# an older alias still read by a few signing routes; mirror SOLANA_RPC_URL.
SOLANA_MAINNET_RPC=
# Comma-separated list of fallback RPC URLs tried in order on primary failure.
# Used by api/_lib/solana/rpc-fallback.js.
SOLANA_RPC_FALLBACK_URLS=
# Comma-separated PAID metered endpoints held in reserve. Tried dead LAST,
# after every free/keyless public node, so their monthly quota is only spent
# when the entire free chain is down or throttled. Mainnet only. NOTE: for a
# dedicated paid endpoint you actually want in rotation, prefer QUICKNODE_RPC_URL
# below (high-priority lane) over this reserve slot.
SOLANA_RPC_LAST_RESORT_URLS=
# A single dedicated QuickNode endpoint URL (the access token is embedded in the
# path, so this is a full URL, not an api-key). Placed HIGH in the chain by
# api/_lib/solana/connection.js (right after SOLANA_RPC_URL and ahead of the
# shared-key providers Helius/Alchemy), so a paid, reliable node absorbs load
# first instead of sitting behind the flaky public tail. Its WSS is derived by
# https:->wss:, which matches QuickNode's own wss:// host/path. Get one at
# https://quicknode.com (Solana Mainnet). Use QUICKNODE_RPC_URL_DEVNET for devnet.
QUICKNODE_RPC_URL=
QUICKNODE_RPC_URL_DEVNET=
# dRPC + Ankr authenticated keys (both sunset keyless access). When set, they are
# added to the Solana RPC chain in their authenticated form as extra keyed lanes
# after Helius/Alchemy. Keyless entries are deliberately omitted (guaranteed 403).
# dRPC: https://drpc.org · Ankr: https://www.ankr.com/rpc.
DRPC_API_KEY=
ANKR_API_KEY=
# Per-chain RPC aliases consulted by /api/permissions/[action] when the
# canonical RPC_URL_<chainId> isn't set. Useful when sharing env across the
# permissions relayer and a separate test runner.
BASE_SEPOLIA_RPC_URL=
SEPOLIA_RPC_URL=
# Alchemy multichain key — used by /api/scene/gate-check for token-balance
# gates that need a paid RPC tier. Without it gate-check returns 503.
# Get a key at https://dashboard.alchemy.com.
ALCHEMY_API_KEY=
# DeBank Cloud API access key — wallet/portfolio data (balances, protocol
# positions, NFT holdings) across 190+ chains. Sent as the `AccessKey` header.
# Get a key at https://cloud.debank.com.
DEBANK_ACCESS_KEY=
# Solana RPC override for the AgenC partnership endpoints (api/agenc/*).
# Falls back to SOLANA_RPC_URL when unset.
AGENC_RPC_URL=
# ── Treasury + relayer signing keys ──────────────────────────────────────────
# DANGER: these wallets hold real funds. Never share, never commit. Rotate
# through Google Secret Manager and Cloud Run secret references only. Each is
# loaded on first use; missing keys cause the relevant route to 500 with a clear
# "<KEY> not configured" message.
# Solana platform treasury for cron buyback / distribution flows. Base58 or
# JSON-array encoded Keypair secret (api/_lib/evm-transfer.js + cron/[name].js).
TREASURY_KEYPAIR=
# Base64-encoded 64-byte Solana keypair for the on-chain coin-launch demo's
# treasury (api/_lib/coin/treasury.js). Leave unset unless you're running the
# coin-launch flow yourself.
COIN_TREASURY_SECRET_KEY_B64=
# Base64-encoded 64-byte Solana keypair used by the Pump.fun buyback cron to
# pay tx fees on behalf of the protocol. Distinct from TREASURY_KEYPAIR.
# Generate (writes .env + prints the public key to fund with SOL):
# node scripts/gen-solana-signer-key.mjs --var PUMP_CRON_RELAYER_SECRET_KEY_B64 --write
# Add --vanity www to grind a vanity public key. Same generator for any
# *_SECRET_KEY_B64 var below.
PUMP_CRON_RELAYER_SECRET_KEY_B64=
# ── Programmatic $THREE buyback (revenue → Jupiter buy → treasury) ───────────
# The run-three-buyback cron (daily) converts platform USDC revenue into onchain
# $THREE buy pressure and routes the bought tokens to the treasury. Public proof
# is rendered on /three-token. No platform burn — supply is never destroyed.
#
# Execution is OFF until both an opt-in flag AND a funded signer are set, so a
# scheduled run is a recorded no-op until an operator deliberately enables it.
THREE_BUYBACK_ENABLED=
# Base64-encoded 64-byte Solana keypair that holds the buyback USDC and signs the
# Jupiter buy. Fund this wallet with USDC (route platform revenue into it) to arm
# buybacks. Pays its own SOL tx fees, so it's covered by the relayer-balance cron.
THREE_BUYBACK_SECRET_KEY_B64=
# PUBLISHED commitment: share of platform revenue (basis points) the protocol
# commits to convert into $THREE buybacks. Rendered on the token page as the
# holder-facing promise — policy, shown whether or not a run is enabled. Default
# 5000 (50%), the conservative floor of the 50–80% band comparable fee-generating
# protocols sustain (Hyperliquid ~79%, pump.fun ~50%). Raise to publish a bigger
# commitment without a code change. 0–10000.
THREE_BUYBACK_COMMIT_BPS=5000
# Max USD a single run may deploy (bounds an over-funded sweep). Default 250.
THREE_BUYBACK_MAX_USD=
# Below this USD, a run is skipped so dust doesn't cost more in fees than it buys.
# Default 10.
THREE_BUYBACK_MIN_USD=
# Jupiter slippage tolerance in basis points (0 < bps ≤ 5000). Default 300 (3%).
THREE_BUYBACK_SLIPPAGE_BPS=
# ── $THREE micro-buy loop (api/x402/three-buy + api/cron/three-buy-loop) ──────
# High-frequency sibling of the daily buyback: many tiny, real USDC→$THREE market
# buys per minute, each triggered by (and paid through) a settled x402 call, so the
# platform shows continuous, verifiable buy pressure. BUY-ONLY — it never sells.
# Execution is OFF until this flag is truthy AND a funded signer exists; until then
# every call is a recorded no-op and the x402 toll is refused (no charge).
THREE_MICROBUY_ENABLED=
# Set to false to pause ONLY the driver loop while leaving the endpoint payable.
THREE_MICROBUY_LOOP_ENABLED=
# Base64-encoded 64-byte Solana keypair that holds the micro-buy USDC float and
# signs the Jupiter buys. Optional — when unset, the micro-buy lane reuses the
# buyback wallet (THREE_BUYBACK_SECRET_KEY_B64). Set a DEDICATED key to keep the
# two lanes' USDC from competing. Fund it with USDC and a little SOL for fees.
THREE_MICROBUY_SECRET_KEY_B64=
# USD spent per single micro-buy. Default 0.01 (hard-capped at 5).
THREE_MICROBUY_USD=
# UTC-daily ceiling on total micro-buy USD — the hard bound on real market spend
# AND SOL fee burn, enforced atomically (Redis reserve-before-buy). Default 50.
THREE_MICROBUY_DAILY_CAP_USD=
# Buys fired per per-minute tick. Default 10; hard-capped at 60. Set 60 for the
# "~60 buys/min" target. Real spend still bounded by THREE_MICROBUY_DAILY_CAP_USD.
THREE_MICROBUY_PER_TICK=
# Concurrent buy workers per tick (1–30). Unset = auto-size to the per-tick target
# (capped at 15), so a 60-buy tick runs ~15-wide and finishes inside the 60s budget.
THREE_MICROBUY_CONCURRENCY=
# Wait for each buy to confirm on-chain before returning? Default false (broadcast-
# and-go) — required to sustain ~60 buys/min. The daily cap is reserved BEFORE
# broadcast and the treasury sweep reconciles real balances, so throughput mode
# stays bounded and self-correcting. Set true to trade throughput for confirmation.
THREE_MICROBUY_AWAIT_CONFIRM=
# Jupiter slippage tolerance in bps (0 < bps ≤ 5000). Default 300 (3%).
THREE_MICROBUY_SLIPPAGE_BPS=
# Sweep accrued $THREE to the treasury every N ticks. Default 30 (~30 min).
THREE_MICROBUY_SWEEP_EVERY_N_TICKS=
# Per-tick ceiling on internal x402 tolls (USDC atomics, 6dp). Default 1000000 ($1).
X402_THREE_BUY_TOLL_CAP_ATOMIC=
# Override the per-call x402 toll price (USDC atomics). Default 1000 ($0.001).
X402_PRICE_THREE_BUY=
# Base58-encoded 64-byte Solana keypair for the agent that signs outbound
# x402 payments from /api/x402-pay. Leave unset if you only RECEIVE x402.
X402_AGENT_SOLANA_SECRET_BASE58=
# Base58-encoded 32-byte Solana secret for the Solana Attestation Service
# authority signer (api/_lib/sas.js). Required by any /api/sas/* route.
SAS_AUTHORITY_SECRET=
# Base58-encoded 64-byte Solana keypair used by the attestation event signer
# (api/_lib/attest-event.js). Required when emitting on-chain reputation
# attestations from cron.
ATTEST_AGENT_SECRET_KEY=
# ── three.ws Agent Collection (Metaplex Core) ──────────────────────────────────
# Our "flavor" of Metaplex: every Solana agent is minted into a three.ws Core
# Collection whose update authority is the keypair below, making each agent's
# on-chain metadata editable by three.ws on the owner's behalf (authority-managed
# edits via /api/agents/solana-edit). See api/_lib/solana-collection.js.
#
# Base58-encoded 64-byte secret for the collection update authority. It signs
# collection creation, mint-into-collection, and all on-chain edits — so it must
# hold a little SOL on each active network. Without it, mints fall back to the
# legacy standalone (owner-managed) asset and edits are unavailable.
SOLANA_AGENT_COLLECTION_AUTHORITY_KEY=
# Deployed collection addresses (base58), filled in by
# scripts/deploy-solana-agent-collection.mjs. Leave blank until deployed —
# mints stay legacy/owner-managed while unset.
SOLANA_AGENT_COLLECTION_MAINNET=
SOLANA_AGENT_COLLECTION_DEVNET=
# Hex EVM private key for the treasury wallet that signs cron-driven USDC
# transfers on Base / EVM chains (api/_lib/evm-transfer.js). Required only
# for the cron flows that distribute or sweep on-chain — request-path code
# never touches this key. Fund the derived address with gas tokens.
EVM_TREASURY_PRIVATE_KEY=
# ── Pump.fun integration (additional) ────────────────────────────────────────
# Default agent token mint used by api/_lib/pump-pricing.js when a caller
# doesn't supply one. Unset = no default billing token.
PUMP_DEFAULT_AGENT_MINT=
# Network the MCP dispatch layer assumes for pump tools (mainnet | devnet).
PUMP_DEFAULT_NETWORK=mainnet
# Fallback Solana pubkey to charge when distribute-payments can't determine
# the payer from context. Should match PUMP_CRON_RELAYER_SECRET_KEY_B64's
# derived pubkey in normal operation.
PUMP_DISTRIBUTE_FALLBACK_PAYER=
# Shared secret for the PumpKit-flavoured webhook handler at
# /api/agents/solana/*. Webhooks without a matching `authorization: Bearer
# $PUMPKIT_WEBHOOK_SECRET` return 500.
# Generate: openssl rand -base64 32
PUMPKIT_WEBHOOK_SECRET=
# ── Autonomous coin launcher (api/_lib/launcher-engine.js + /api/cron/launcher-tick) ─
# The "Memetic Launcher": platform agents mint pump.fun coins on a cadence riding
# live cultural narratives, each agent signing its OWN create. Ships INERT — fully
# off until armed via POST /api/admin/launcher { enabled:true, dry_run:false }
# (use scripts/launcher-ops.mjs). Funding is just-in-time and capped.
#
# Master launch wallet — the ONLY wallet SOL is ever taken from. It never mints;
# it tops up the next agent in the rotation with exactly per_launch_sol, then the
# agent signs its own create. Base64 of a 64-byte Solana secret key. Falls back to
# PUMP_X402_LAUNCHER_SECRET_KEY_B64 so existing infra keeps working.
# Generate: node scripts/gen-solana-signer-key.mjs --var LAUNCHER_MASTER_SECRET_KEY_B64
# Fund the derived pubkey with SOL before arming.
LAUNCHER_MASTER_SECRET_KEY_B64=
#
# House-ownership guarantee (optional but recommended). Comma-separated user uuids
# we control. When set, the GLOBAL rotation is HARD-restricted to agents owned by
# exactly these accounts — only house-owned agents ever launch. Unset = the
# platform circulation pool (also bot accounts, never real users).
# LAUNCHER_OWNER_USER_IDS=11111111-2222-4333-8444-555555555555,...
LAUNCHER_OWNER_USER_IDS=
# ── Mint-mark kill-switch (api/pump/[action].js: launch-prep + launch-agent) ─
# Controls whether branded launches must carry the "3ws" mint mark.
# Default: ON (any value other than '0' or 'false' enforces fail-closed).
# Set to '0' ONLY during an incident where grindVanityNode is broken and
# launches must continue unblocked. Re-enable immediately after resolution.
THREE_WS_MARK_ENFORCE=1
# Redis list key holding the pump.fun graduations stream (defaults to
# "pf:graduations"). Override only when running multiple environments
# against one Upstash instance.
GRADUATIONS_LIST_KEY=pf:graduations
# ── Replicate webhook signing ────────────────────────────────────────────────
# Signing secret from replicate.com/account/webhook to verify model-completion
# callbacks at /api/webhooks/replicate. Without it the endpoint rejects every
# request. The "whsec_" prefix is stripped automatically.
REPLICATE_WEBHOOK_SIGNING_KEY=
# ── Google Cloud Platform — 3D pipeline + Vertex AI ──────────────────────────
# Used for: Vertex AI text-to-image (reference image for text→3D), and
# self-hosted Cloud Run workers (avatar reconstruction, background removal,
# remesh, texture generation).
#
# text-to-image provider ladder: NVIDIA NIM FLUX > Vertex > Replicate.
# Worker priority: GCP Cloud Run > Replicate > HuggingFace for image-to-3D.
#
# Get your project id from: https://console.cloud.google.com
GOOGLE_CLOUD_PROJECT=
# Region for Vertex AI endpoints (default: us-central1). Set to "global" for
# models only served on the global endpoint.
GOOGLE_CLOUD_LOCATION=us-central1
# Explicit on/off gate for the Vertex text-to-image lane, independent of
# GOOGLE_CLOUD_PROJECT (which Vertex Claude and the workers also need). Unset ⇒
# lane is active whenever the project is set (today's behavior). Set to 0/false
# to turn the lane off without unsetting the shared project. See docs/gcp-credits.md.
VERTEX_IMAGEN_ENABLED=
# Vertex image-generation model. NOTE: Google is retiring the Imagen :predict
# family (imagen-3.0-* shut down 2026-06-30; imagen-4.0-* by 2026-08-17), so the
# default is now the live Gemini image model, which bills to the same GCP credits:
# gemini-2.5-flash-image — GA "Nano Banana" (generateContent API)
# imagen-4.0-generate-001 — legacy :predict path, until 2026-08-17 only
VERTEX_IMAGEN_MODEL=gemini-2.5-flash-image
# Vertex image-editing model (used by editImage()). Same Gemini default; an
# imagen-* value routes to the legacy :predict edit shape while still callable.
VERTEX_IMAGEN_EDIT_MODEL=gemini-2.5-flash-image
# Location for the image models only (falls back to GOOGLE_CLOUD_LOCATION, then
# us-central1). "global" is required for the preview image models. NOTE: the
# gemini-3-pro-image-preview model was RETIRED by Google and now returns 404
# on generateContent (verified 2026-07-21) — it caused a text->3D reference-image
# outage. Production runs global + the GA gemini-2.5-flash-image (set above).
# Do not point VERTEX_IMAGEN_MODEL at a *-preview image model without first
# confirming it resolves (curl the :generateContent endpoint) — a 404 there
# silently degrades every text->3D generation.
VERTEX_IMAGEN_LOCATION=
# Requested reference-image resolution: 1K / 2K / 4K (default 2K).
# gemini-2.5-flash-image ignores it (always 1024px); gemini-3-pro-image honors
# it. Models that reject the knob get one automatic retry without it.
VERTEX_IMAGE_SIZE=
# Service account JSON key (paste the full JSON as a single-line string).
# Alternative: set GOOGLE_APPLICATION_CREDENTIALS to a file path on the server.
GCP_SERVICE_ACCOUNT_JSON=
# Shared bearer secret for all Cloud Run workers (set as GCP Secret Manager
# secret named "avatar-reconstruction-key", or override here for local dev).
GCP_RECONSTRUCTION_KEY=
# Cloud Run service URLs — set after deploying each worker:
# workers/avatar-pipeline-controller → avatar reconstruction (image → GLB)
GCP_RECONSTRUCTION_URL=
# workers/model-trellis → self-hosted TRELLIS image→3D
# (forge backend `trellis_selfhost`). Fuses up to 6 turnaround views of one
# subject into a single textured GLB; unset ⇒ the lane drops out of routing.
MODEL_TRELLIS_URL=
# TRELLIS.2 worker (workers/model-trellis2), the default image-to-3D lane (forge backend
# `trellis2`). Unset skips the lane; the chain behind it serves the request.
MODEL_TRELLIS2_URL=
# Modly worker (workers/modly), Modly's backend run headless on an L4. Serves the forge
# backends `modly` (TripoSG) and `modly_hunyuan` (Hunyuan3D 2 Mini Turbo), both
# untextured image-to-3D. Unset skips both lanes.
MODEL_MODLY_URL=
# workers/model-hunyuan3d → self-hosted Hunyuan3D-2 image→3D
# (forge backend `hunyuan3d`, gcp provider mode `hunyuan`). NOT the same as
# GCP_RECONSTRUCTION_URL, whose avatar face pipeline rejects non-face images.
GCP_HUNYUAN3D_URL=
# workers/model-triposg → sketch→3D (forge `sketch` path)
GCP_TRIPOSG_URL=
# workers/unirig → auto-rigging (GLB → rigged GLB).
# Required for /api/forge?action=rig: without it rerig falls back to
# GCP_RECONSTRUCTION_URL, whose deployed service has no /rig endpoint.
GCP_UNIRIG_URL=
# workers/rembg → background removal (image → PNG)
GCP_REMBG_URL=
# workers/remesh → mesh processing (GLB → clean GLB)
GCP_REMESH_URL=
# workers/texture → text-guided texturing (GLB + prompt → textured GLB).
# Also serves the Magic Brush /retexture_region endpoint (local region
# inpainting) — no separate URL needed.
GCP_TEXTURE_URL=
# workers/segment → part segmentation (GLB → segmented GLB + parts manifest)
GCP_SEGMENT_URL=
# workers/cad-forge → build123d program → STEP/STL/GLB/SVG (CAD Forge, /cad).
# Authenticated with its own secret (cad-forge-key), not GCP_RECONSTRUCTION_KEY,
# because it runs model-written code; the API falls back to the shared key
# only when CAD_FORGE_KEY is unset.
GCP_CAD_FORGE_URL=
CAD_FORGE_KEY=
# Optional: the NVIDIA NIM model that leads the CAD program writer ladder
# (default moonshotai/kimi-k3), and the global hourly design ceiling (default 400).
CAD_WRITER_MODEL=
CAD_FORGE_GLOBAL_HOURLY=
# Magic Brush region inpainting model (workers/texture /retexture_region). SDXL
# inpaint checkpoint loaded lazily on first region edit. Override only to pin a
# different inpaint model.
SDXL_INPAINT_MODEL=diffusers/stable-diffusion-xl-1.0-inpainting-0.1
# ── IPFS pinning (additional) ───────────────────────────────────────────────
# nft.storage token used by /api/erc8004/* when PINATA_JWT and
# WEB3_STORAGE_TOKEN are both empty. Get one at https://nft.storage.
NFT_STORAGE_TOKEN=
# ── LiveKit (real-time voice rooms) ──────────────────────────────────────────
# Powers the agent voice-chat experience at /api/agents/:id/livekit-token.
# Without all three set, the endpoint returns 503 livekit_not_configured.
# Self-host LiveKit Server or use https://livekit.io cloud.
LIVEKIT_API_KEY=
LIVEKIT_API_SECRET=
LIVEKIT_SERVER_URL=
# ── Additional LLM / social keys ─────────────────────────────────────────────
# Google Gemini — surfaced to the browser via /api/gemini-key (the front-end
# voice modal embeds the key for direct Gemini calls). Optional.
# Get a key at https://aistudio.google.com.
GEMINI_API_KEY=
# Neynar (Farcaster) - the indexed lane for Farcaster social-memory seeding.
# Optional: without it /api/seed/farcaster reads a public Farcaster hub
# (FARCASTER_HUB_URL) keyless, minus the follower and reaction counts only an
# indexer has. Get a key at https://neynar.com.
NEYNAR_API_KEY=
# X (Twitter) - read-only public-data bearer token used by /api/seed/x.
# Get one from https://developer.twitter.com (Read access). Optional when the
# OAuth 1.0a app pair below is set: /api/seed/x exchanges X_API_KEY and
# X_API_SECRET for the same app-only bearer at runtime.
TWITTER_BEARER_TOKEN=
# X (Twitter) posting — OAuth 1.0a user context for @trythreews, used by
# scripts/changelog-x.mjs (npm run changelog:push:x) to tweet changelog
# entries. Create an app at https://developer.x.com with Read and Write
# permissions, then generate the access token/secret while logged in as
# @trythreews (Keys and tokens → Access Token and Secret).
X_API_KEY=
X_API_SECRET=
X_ACCESS_TOKEN=
X_ACCESS_SECRET=
# @trythreews content queue (data/x-content/queue.json, /api/cron/x-content).
# Unset or false: every cron tick previews the next item without posting. Set
# true on the Cloud Run service only after the owner approves auto-publishing.
# Posting uses the X_API_KEY / X_API_SECRET / X_ACCESS_TOKEN / X_ACCESS_SECRET
# app credentials; the publish ledger lives in the app_settings table.
X_CONTENT_AUTO_PUBLISH=false
# Telegram bot — used by /api/pump/deliver-telegram to push pump.fun signals
# to subscriber chats. Without it the endpoint 500s.
# Create a bot via https://t.me/BotFather → /newbot.
TELEGRAM_BOT_TOKEN=
# Telegram changelog channel — scripts/changelog-telegram.mjs posts new
# changelog entries here (npm run changelog:push). Use the channel @handle or
# the -100… numeric id; the bot above must be an admin of the channel.
TELEGRAM_CHANGELOG_CHAT_ID=-1003927666373
# Telegram commit feed — /api/cron/commit-feed-push posts every new commit on
# `main` here as it lands (raw, one message per commit, no curation). Optional:
# falls back to TELEGRAM_CHANGELOG_CHAT_ID above when unset, so it works out of
# the box on the same channel. Set this to a separate chat id to keep the
# commit firehose out of the holder-facing changelog channel.
TELEGRAM_COMMITS_CHAT_ID=
# Telegram pump.fun first-claims channel (@pumpfunclaims).
# /api/cron/pump-claims-push posts each first-time creator fee claim here, one
# message per claim. Use the channel @handle or the -100… numeric id; the bot
# above must be an admin of the channel. Deliberately has NO fallback to the
# changelog channel: this is a high-volume third-party coin feed and holders
# are a different audience. Leave blank to disable the lane entirely.
# The scan behind it also needs PUMPFUN_BOT_URL set to return anything.
TELEGRAM_PUMP_CLAIMS_CHAT_ID=
# Telegram Oracle signals channel: the live feed of three.ws/oracle. The
# oracle-score cron (every 2 min) posts each coin that first crosses the tier
# floor (ORACLE_ALERT_MIN_TIER) OR the raw score floor (ORACLE_FEED_MIN_SCORE,
# default 56 = the Lean boundary); agent entries and profitable exits post from
# the agent/settle loops; oracle-digest posts a daily channel summary at 08:00
# UTC. Separate from ops alerts and the changelog channel. Leave blank to
# disable. A public @handle here also lights up the "Join the live Telegram
# feed" button on /oracle (via /api/oracle/stats).
TELEGRAM_ORACLE_CHAT_ID=
ORACLE_ALERT_MIN_TIER=strong
# Score floor for channel posts, independent of tier. 56 tracks the top of the
# real score distribution (~a dozen posts/day). Set 101 to disable the score
# path and post only on tier crossings.
ORACLE_FEED_MIN_SCORE=56
# ── x402 spending ledger ─────────────────────────────────────────────────────
# Set to "1" to allow the per-user x402 spending ledger to fall back to an
# in-process Map when Upstash Redis is unreachable. ONLY enable in dev — in
# production this would silently disable spending caps across multiple
# serverless instances.
X402_ALLOW_MEMORY_FALLBACK=
# ── WalletConnect (client-side) ──────────────────────────────────────────────
# Project ID surfaced to the browser via /api/config. Without it, WalletConnect
# QR connections silently fail. Free at https://cloud.walletconnect.com.
VITE_WALLETCONNECT_PROJECT_ID=
# ── Sentry tagging ───────────────────────────────────────────────────────────
# Override the environment label sent with each Sentry event. Defaults to
# VERCEL_ENV ("production" | "preview" | "development"). Set this to a
# custom label (e.g. "staging") when running outside Vercel.
SENTRY_ENVIRONMENT=
# Override the release tag. Defaults to VERCEL_GIT_COMMIT_SHA. Set to your
# build's git SHA or a semver string when running outside Vercel so source
# maps + release health reports line up correctly.
SENTRY_RELEASE=
# ── Tunables ─────────────────────────────────────────────────────────────────
# Subscription charge timeout for the renewal cron (api/cron/[name].js).
# Bounds the time we wait for a skill's onPeriod handler before marking the
# charge attempt failed. Default 30000 ms.
SUBSCRIPTION_CHARGE_TIMEOUT_MS=30000
# Coin-launch demo is gated by an explicit opt-in flag so cron + manual calls
# stay no-ops in any project that doesn't intend to expose it. Set to "true"
# to enable; any other value (including unset) disables.
COIN_DEMO_ENABLED=
# Dust threshold (in atomic USDC units, 6 decimals) below which the club
# sweep cron leaves balances un-distributed. Default 5000 = $0.005. Raise
# during high-gas periods to keep payouts net-positive.
CLUB_SWEEP_DUST_ATOMICS=5000
# Model override for the marketplace preview generator. Falls back to the
# per-provider default when unset (defined in api/marketplace/[action].js).
PREVIEW_MODEL=
# ── AWS Marketplace (SaaS listing) ───────────────────────────────────────────
# Credentials for a dedicated IAM user scoped to the four aws-marketplace:*
# actions used by api/_lib/aws-marketplace.js (ResolveCustomer, MeterUsage,
# BatchMeterUsage, GetEntitlements). Required when a Marketplace listing is
# live; safe to leave unset until then — env reads are lazy.
AWS_MP_ACCESS_KEY_ID=
AWS_MP_SECRET_ACCESS_KEY=
# Region of the seller account. AWS Marketplace metering only resolves in
# us-east-1 today regardless of where you host the app.
AWS_MP_REGION=us-east-1
# Product code assigned by AWS when the SaaS product is created in AMMP.
# Appears in the public product page URL and in every SNS notification payload.
AWS_MP_PRODUCT_CODE=
# Optional. ARN of the SNS topic that receives subscribe/unsubscribe
# notifications. When set, api/aws-marketplace/subscription.js rejects any
# SNS message whose TopicArn does not match (defense-in-depth on top of
# AWS's signature verification).
AWS_MP_SNS_TOPIC_ARN=
# Per-minute rate limit applied to every auto-issued x402 subscription a
# linked AWS Marketplace customer receives. Default 600/min — bump per tier
# if you split into multiple listings.
AWS_MP_DEFAULT_RATE_LIMIT_PER_MINUTE=600
# When set, every successful paid /api/x402/* call by an AWS Marketplace
# subscription reports one unit on this MeterUsage dimension (Usage product).
# Leave blank for Contract products (flat-fee subscription; entitlement-only).
AWS_MP_METERING_DIMENSION=
# ── Debug toggles (leave unset in prod) ──────────────────────────────────────
# Set DEBUG=true to log knowledge-retrieval failures from widget chat.
DEBUG=
# Set TTS_DEBUG=1 to log every ElevenLabs voice-clone completion (user id,
# voice id, audio byte count). Useful while iterating on the cloning flow.
TTS_DEBUG=
# ─── CoinCommunities (Coin Worlds / Town social layer) ───────────────────────
# Each coin is its own 3D world on /walk; its CoinCommunities community is the
# live social layer (feed + realtime chat bubbles). The API key is held ONLY
# server-side by the api/community/* proxy — it is never shipped to the browser.
# Get a key: register a business at https://coin-communities.xyz, verify email,
# create an API key in the dashboard. Reads + realtime tickets need only this.
CC_API_KEY=
# API origin. Override only for staging. Don't append /api/v1 — the SDK adds it.
CC_BASE_URL=https://api.coin-communities.xyz
# OPTIONAL server key-pair (x-server-key / x-server-secret). Required ONLY to
# attribute posts to users server-side (postMessageServer). Leave unset and the
# Town composer renders its designed locked state (live reads still work).
CC_SERVER_KEY=
CC_SERVER_SECRET=
# OPTIONAL default coin a bare /walk binds to when no ?coin= is present and the
# lobby is skipped. A Solana mint address. Unset → /walk shows the world lobby.
CC_DEFAULT_TOKEN=
# Meshy AI — 3D generation MCP server (Pro plan required: meshy.ai/settings/api)
MESHY_API_KEY=msy_your_key_here
# ─── DCA strategies (api/dca-strategies.js) ──────────────────────────────────
# Token symbols a DCA strategy may buy (comma-separated, resolved against the
# strategy's chain at execution time). Empty/unset → strategy creation returns
# 400 not_configured. Per project policy no token tickers are hardcoded in code.
DCA_ALLOWED_TOKEN_OUT=
# Default EVM chain id for new strategies when the client omits chain_id
# (e.g. 8453 for Base mainnet). Unset → chain_id is required per-request.
DCA_CHAIN_ID=
# ─── Labor-escrow bounty wallet (api/_lib/labor-escrow.js) ───────────────────
# Base58-encoded 64-byte Solana secret key for the platform's escrow wallet.
# This wallet holds $THREE in escrow while bounties are active and releases/
# reclaims funds on completion. Leave unset to disable bounty posting (the
# endpoint returns 503 escrow_unavailable). Fund the derived public key with
# enough SOL for transaction fees before enabling in production.
# Generate a fresh keypair: node -e "const n=require('tweetnacl'); ..."
# or use: solana-keygen new --outfile escrow-keypair.json (then convert to base58)
LABOR_ESCROW_SECRET_BASE58=
# ─── Sketchfab showcase (api/cron/sketchfab-showcase.js) ─────────────────────
# API token for the Sketchfab account the showcase cron publishes finished
# three.ws models to. Get one at https://sketchfab.com/settings/password
# (the "API Token" field). The cron is scheduled Mon/Wed/Fri and is fully wired
# without it: every run returns not_configured and uploads nothing until the
# token is set, and `?dry_run=1` previews the exact models the next real run
# would push. See docs/sketchfab.md.
SKETCHFAB_API_TOKEN=
# Models pushed per run (default 2). Raise once the account's upload quota and
# processing latency are known good.
SKETCHFAB_UPLOADS_PER_RUN=
# ─── Materialize: 3D print fulfillment (api/_lib/print/*, docs/materialize.md) ─
# Everything below is OPTIONAL. Quoting, analysis, checkout and the fabrication
# gate all run without any of it; these unlock operations, a contracted partner,
# and on-chain certificates.
#
# Private Telegram chat the operator console pages for a new job, a stalled job,
# and every fabrication refusal or held order. Unset falls back to
# TELEGRAM_ALERTS_CHAT_ID, then to the in-app admin bell.
TELEGRAM_PRINT_OPS_CHAT_ID=
# Comma-separated user ids or emails allowed into /materialize/ops without full
# platform admin. These responses carry shipping addresses, so the gate fails
# closed in development too: unset means admin-only.
PRINT_OPERATORS=
# Contracted print partner's API. Both must be set or the partner adapter stays
# unregistered and every order routes to the manual operator lane, which is the
# launch configuration. The key also verifies their webhook signatures
# (x-print-signature: sha256=<hmac of the raw body>).
PRINT_PARTNER_CN_URL=
PRINT_PARTNER_CN_KEY=
# Certificates of authenticity. The attester signs the Solana memo carrying the
# printed file's hash and the edition number. Base58 64-byte secret key; unset
# means certificates are issued and hashed but left unattested, and the
# certificate page says so rather than pretending.
PRINT_CERT_ATTESTER_SECRET=
# devnet (default) or mainnet. Mainnet is gated TWICE on purpose: this must say
# mainnet AND PRINT_CERT_MAINNET_APPROVAL must carry the owner's recorded
# approval, because a devnet signature printed on a mainnet certificate would be
# a lie. A missing approval never silently downgrades.
PRINT_CERT_CLUSTER=
PRINT_CERT_MAINNET_APPROVAL=