Skip to main content
Configuration differs depending on whether you run Key0 as a standalone Docker container or embed the SDK directly in your application.
The standalone Docker image reads all configuration from environment variables. Pass them via docker run -e or a .env file.

​
Core

VariableRequiredDefaultDescription
KEY0_WALLET_ADDRESSYes—USDC-receiving wallet address (0x...).
ISSUE_TOKEN_APIYes—URL that Key0 POSTs to after payment is verified. Your backend returns a credential (API key, JWT, etc.) from this endpoint.
KEY0_NETWORKNotestnetmainnet (Base, chain 8453) or testnet (Base Sepolia, chain 84532).
PORTNo3000HTTP server listen port.

​
Agent Card

VariableRequiredDefaultDescription
AGENT_NAMENoKey0 ServerDisplay name in the A2A agent card.
AGENT_DESCRIPTIONNoPayment-gated A2A endpointDescription in the agent card.
AGENT_URLNohttp://localhost:PORTPublic URL of the server. Set this in production so the agent card advertises the correct address.
PROVIDER_NAMENoKey0Organization name in the agent card.
PROVIDER_URLNohttps://key0.aiOrganization URL in the agent card.

​
Plans

VariableRequiredDefaultDescription
PLANSNo[{"planId":"basic","unitAmount":"$0.10"}]JSON array of pricing plans. Each plan has planId, unitAmount, and an optional description.
PLANS_B64No—Base64-encoded version of PLANS. Used by the Setup UI as an alternative to PLANS. If both are set, PLANS_B64 takes precedence.

​
Challenge & Endpoint

VariableRequiredDefaultDescription
CHALLENGE_TTL_SECONDSNo900How long a payment challenge remains valid, in seconds.
BASE_PATHNo/a2aPath prefix for the A2A endpoints.
A2A_ENABLEDNotrueSet to false to disable A2A discovery at /.well-known/agent.json.
MCP_ENABLEDNofalseSet to true to mount MCP discovery and Streamable HTTP routes alongside A2A.
LLMS_ENABLEDNotrueSet to false to disable generated /llms.txt.
SKILLS_MD_ENABLEDNotrueSet to false to disable generated /skills.md.

​
Backend Auth

VariableRequiredDefaultDescription
BACKEND_AUTH_STRATEGYNononeAuthentication strategy for calls to ISSUE_TOKEN_API. Options: none, shared-secret, jwt.
ISSUE_TOKEN_API_SECRETNo—Bearer token (when strategy is shared-secret) or JWT signing key (when strategy is jwt) used to authenticate with ISSUE_TOKEN_API.

​
Per-Request Proxy (Standalone PPR)

VariableRequiredDefaultDescription
PROXY_TO_BASE_URLNo—Enable route-based gateway mode. When set, paid top-level routes can be called directly: Key0 returns a 402 challenge, proxies the request to this base URL after payment, and returns a ResourceResponse. ISSUE_TOKEN_API is not called for route purchases.

​
Token Issuance

VariableRequiredDefaultDescription
TOKEN_ISSUE_TIMEOUT_MSNo15000Timeout in milliseconds for the ISSUE_TOKEN_API call.
TOKEN_ISSUE_RETRIESNo2Number of retries for transient ISSUE_TOKEN_API failures.

​
Storage

VariableRequiredDefaultDescription
STORAGE_BACKENDNoredisStorage backend: redis or postgres.
REDIS_URLNo—Redis connection URL (e.g., redis://localhost:6379).
DATABASE_URLNo—PostgreSQL connection URL (e.g., postgresql://user:pass@host:5432/db).
KEY0_MANAGED_INFRANo—Auto-detected by Docker Compose profiles. Comma-separated override to specify which infrastructure is managed (e.g., redis,postgres).

​
Settlement & Refunds

VariableRequiredDefaultDescription
GAS_WALLET_PRIVATE_KEYNo—Private key of an ETH-funded wallet for self-contained on-chain settlement. Alternative to using the CDP (Coinbase Developer Platform) facilitator.
KEY0_WALLET_PRIVATE_KEYNo—Private key of the receiving wallet. Required only if you run the refund cron.
REFUND_INTERVAL_MSNo60000How often the refund cron scans for refundable challenges, in milliseconds.
REFUND_MIN_AGE_MSNo300000Grace period before a paid-but-undelivered challenge becomes eligible for refund, in milliseconds.
REFUND_BATCH_SIZENo50Maximum number of refunds processed per cron tick.

​
Notes

  • KEY0_WALLET_PRIVATE_KEY is only needed if you enable the refund cron. For normal operation, only the public wallet address is required.
  • GAS_WALLET_PRIVATE_KEY provides an alternative to the CDP facilitator for on-chain settlement. The wallet must hold enough ETH on Base to cover gas fees.
Redis is required even when you select Postgres as the storage backend. The BullMQ-based refund cron and distributed gas-wallet lock both depend on Redis.

Docker Deployment

Run Key0 as a standalone container with these environment variables.

SellerConfig

The code-level configuration object that maps to many of these variables.

Storage

Redis and Postgres setup for challenge stores, seen-tx, and audit logs.