.env.example

# ────────────────────────────────────────────────────────────────────────────
# three.ws — backend environment
# Copy to .env.local for local dev. In production, set these in Vercel.
# ────────────────────────────────────────────────────────────────────────────

# Public site origin (no trailing slash)
PUBLIC_APP_ORIGIN=https://three.ws

# Postgres (Neon serverless driver — HTTPS connection string)
DATABASE_URL=postgres://user:pass@ep-xxx.neon.tech/neondb?sslmode=require

# S3-compatible storage (AWS S3, Cloudflare R2, Backblaze B2, etc.)
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
# prod Vercel region for low write latency. Unset = caches share the store above (no
# behavior change). Vercel-KV second store prefixed `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 4.6 (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-4-6
CHAT_MAX_TOKENS=1024

# Admin key for three.ws chat brand config. Set in Vercel, enter in chat settings to unlock 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=

# 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 paste the output here / into Vercel env.
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 via Vercel env vars.
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=

# ── 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
# 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=

# ── 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 onboarding@resend.dev while verifying.
EMAIL_FROM=three.ws <notifications@three.ws>
# Reply-To for transactional mail (defaults to support@three.ws so replies reach a human).
EMAIL_REPLY_TO=support@three.ws
# 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/*. Vercel cron requests bypass this check via the `x-vercel-cron`
# header, so the secret only matters for manual / external invocation. Without
# it, only the Vercel platform can fire cron jobs.
# 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
# via Vercel env vars 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=
#   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=

# 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) — powers /api/seed/farcaster social-memory seeding.
# 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).
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=

# 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 Oracle signals channel — prime/strong conviction coins posted here
# by the oracle-score cron. Separate from ops alerts and the changelog channel.
# Leave blank to disable. Set ORACLE_ALERT_MIN_TIER=prime to only post the top tier.
TELEGRAM_ORACLE_CHAT_ID=
ORACLE_ALERT_MIN_TIER=strong

# ── 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=