@agentcash/router 1.6.0 → 1.7.0

package/dist/index.d.cts

@@ -4,7 +4,6 @@ import { ZodType } from 'zod';
 import { PaymentRequirements, PaymentRequired, VerifyResponse, SettleResponse, Network } from '@x402/core/types';
 import * as viem from 'viem';
 import { Transport } from 'mppx/server';
-import { Store } from 'mppx';
 
 interface KvStore {
     get(key: string): Promise<unknown>;
@@ -26,42 +25,15 @@ type KvChange<R> = {
     op: 'delete';
     result: R;
 };
-declare function withPrefix(kv: KvStore, prefix: string): KvStore;
 
-declare const SIWX_CHALLENGE_EXPIRY_MS: number;
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
 }
-declare class MemoryNonceStore implements NonceStore {
-    private seen;
-    check(nonce: string): Promise<boolean>;
-    private evict;
-}
-interface KvNonceStoreOptions {
-    prefix?: string;
-    ttlMs?: number;
-}
-declare function createKvNonceStore(kv: KvStore, options?: KvNonceStoreOptions): NonceStore;
 
 interface EntitlementStore {
     has(route: string, wallet: string): Promise<boolean>;
     grant(route: string, wallet: string): Promise<void>;
 }
-declare class MemoryEntitlementStore implements EntitlementStore {
-    private readonly routeToWallets;
-    has(route: string, wallet: string): Promise<boolean>;
-    grant(route: string, wallet: string): Promise<void>;
-}
-interface KvEntitlementStoreOptions {
-    prefix?: string;
-}
-declare function createKvEntitlementStore(kv: KvStore, options?: KvEntitlementStoreOptions): EntitlementStore;
-
-type MppStore = Store.Store;
-interface KvMppStoreOptions {
-    prefix?: string;
-}
-declare function createKvMppStore(kv: KvStore, options?: KvMppStoreOptions): Promise<MppStore>;
 
 interface RequestMeta {
     requestId: string;
@@ -137,7 +109,6 @@ interface RouterPlugin {
     onAlert?(ctx: PluginContext, alert: AlertEvent): void;
     onProviderQuota?(ctx: PluginContext, event: ProviderQuotaEvent): void;
 }
-declare function consolePlugin(): RouterPlugin;
 
 declare class HttpError extends Error {
     readonly status: number;
@@ -222,10 +193,6 @@ interface X402AcceptConfig extends X402AcceptBase {
     /** Per-accept payee override. Function form receives the request and parsed body for dynamic recipient routing. Falls back to `RouterConfig.payeeAddress`. */
     payTo?: PayToConfig;
 }
-interface X402ResolvedAccept extends X402AcceptBase {
-    scheme: string;
-    payTo: string;
-}
 interface X402RouterFacilitatorConfig extends FacilitatorConfig {
     /** Async header builder invoked per facilitator call. Use for short-lived auth tokens (e.g. CDP signed headers). */
     createAcceptsHeaders?: () => Promise<Record<string, string>>;
@@ -233,9 +200,7 @@ interface X402RouterFacilitatorConfig extends FacilitatorConfig {
 /** A facilitator URL or a full `FacilitatorConfig` (URL + auth header builders). */
 type X402FacilitatorTarget = string | X402RouterFacilitatorConfig;
 interface X402FacilitatorsConfig {
-    /** Facilitator for EVM chains (Base, etc.). Defaults to the Coinbase facilitator using `CDP_API_KEY_ID`/`CDP_API_KEY_SECRET`. */
-    evm?: X402FacilitatorTarget;
-    /** Facilitator for Solana. Required to accept Solana payments — there's no default. */
+    /** Facilitator for Solana. Defaults to {@link DEFAULT_SOLANA_FACILITATOR_URL}. The EVM facilitator is hardcoded to Coinbase (CDP) — set `CDP_API_KEY_ID` / `CDP_API_KEY_SECRET`. */
     solana?: X402FacilitatorTarget;
 }
 interface MppProtocolInfo {
@@ -409,7 +374,7 @@ interface RouterConfig {
         /** Per-chain facilitator overrides (`evm`/`solana`). Defaults to the Coinbase facilitator on EVM; set `solana` to accept Solana payments. */
         facilitators?: X402FacilitatorsConfig;
     };
-    /** Observability hook receiving request/auth/payment/settlement events. Use `consolePlugin` for dev, or implement `RouterPlugin` for structured logs/analytics. */
+    /** Observability hook receiving request/auth/payment/settlement events. Implement `RouterPlugin` for structured logs/analytics. */
     plugin?: RouterPlugin;
     /** Single KV cache for SIWX nonce, SIWX entitlement, and MPP tx-hash replay (prefixed `siwx:nonce:`, `siwx:ent:`, `mpp:`). Pass `{ url, token }` for an Upstash-compatible REST endpoint (Upstash, Vercel KV), or a custom `KvStore` implementation. Omitted: auto-bootstraps from `KV_REST_API_URL` + `KV_REST_API_TOKEN`; falls back to in-memory when missing (unsafe in serverless). */
     kvStore?: KvStore | {
@@ -422,7 +387,7 @@ interface RouterConfig {
     mpp?: {
         /** HMAC key for signing/verifying MPP challenge nonces. Persist across deploys — rotating invalidates outstanding 402 challenges. Falls back to `MPP_SECRET_KEY`. */
         secretKey: string;
-        /** Tempo currency contract address (0x-prefixed). Use `TEMPO_USDC_CURRENCY` for USDC on Tempo. */
+        /** Tempo currency contract address (0x-prefixed). Use `TEMPO_USDC_ADDRESS` for USDC on Tempo. */
         currency: string;
         /** MPP payee address (EVM). Overrides `payeeAddress` for MPP only. Required when `payeeAddress` is unset. MUST equal `operatorKey`'s derived address when `session` is enabled. */
         recipient?: string;
@@ -827,50 +792,83 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     private register;
 }
 
-declare const BASE_NETWORK = "eip155:8453";
-declare const SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
-declare const TEMPO_USDC_CURRENCY = "0x20c000000000000000000000b9537d11c60e8b50";
-declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
-
-type RouterEnv = Record<string, string | undefined>;
-type RouterConfigIssueCode = 'missing_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'missing_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'invalid_mpp_operator_key' | 'mpp_operator_equals_fee_payer';
+type RouterConfigIssueCode = 'missing_base_url' | 'invalid_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'invalid_x402_payee' | 'invalid_solana_payee' | 'invalid_solana_facilitator_url' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'missing_mpp_rpc_url' | 'invalid_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'invalid_mpp_operator_key' | 'mpp_operator_equals_fee_payer' | 'missing_discovery_title' | 'missing_discovery_description' | 'missing_discovery_guidance' | 'invalid_server_url' | 'kv_url_without_token' | 'kv_token_without_url' | 'invalid_kv_url' | 'missing_kv_in_production';
+type RouterConfigIssueSeverity = 'error' | 'warning';
 interface RouterConfigIssue {
     code: RouterConfigIssueCode;
     message: string;
     protocol?: ProtocolType;
-}
-interface RouterConfigValidationOptions {
-    env?: RouterEnv;
-    requireCdpKeys?: boolean;
+    /** @default 'error' — warnings are surfaced via `console.warn` and do not throw. */
+    severity?: RouterConfigIssueSeverity;
+}
+/** Options for {@link createRouterFromEnv} / {@link routerConfigFromEnv}. */
+interface CreateRouterFromEnvOptions<TPrices extends Record<string, string> = Record<never, string>> {
+    /** Defaults to `process.env`. Pass an explicit object in tests. */
+    env?: Record<string, string | undefined>;
+    /** Discovery title. Shown in `.well-known/agentcash`, OpenAPI, and `/llms.txt`. */
+    title: string;
+    /** Discovery description. */
+    description: string;
+    /** Long-form usage guidance for agent consumers. Served at `/llms.txt`. Pass an empty string to opt out. */
+    guidance: string;
+    /** Discovery version. @default '1.0.0' */
+    version?: string;
+    /** Optional contact metadata published in discovery. */
+    contact?: DiscoveryConfig['contact'];
+    /** Optional ownership proofs published in `.well-known/agentcash`. */
+    ownershipProofs?: string[];
+    /** Per-route HTTP method hint visibility. */
+    methodHints?: DiscoveryConfig['methodHints'];
+    /** Override the OpenAPI `servers[].url`. Defaults to `BASE_URL`. */
+    serverUrl?: string;
+    /** Centralized price map keyed by route id. `route(key)` auto-applies `.paid(prices[key])` for matching keys. */
+    prices?: TPrices;
+    /** Observability plugin. */
+    plugin?: RouterPlugin;
+    /** Custom KV store. When omitted, the router auto-bootstraps from `KV_REST_API_URL` + `KV_REST_API_TOKEN`. */
+    kvStore?: KvStore;
+    /** Override x402 facilitators. The Solana facilitator defaults to `SOLANA_FACILITATOR_URL` env or `DEFAULT_SOLANA_FACILITATOR_URL`. */
+    x402Facilitators?: X402FacilitatorsConfig;
+    /** Explicit protocol list. Default: `['x402']`, with `'mpp'` added when `MPP_SECRET_KEY` is set. */
+    protocols?: readonly ProtocolType[];
+    /** Require `route({ path })` form for every route. @default false */
+    strictRoutes?: boolean;
 }
 
 declare class RouterConfigError extends Error {
     readonly issues: RouterConfigIssue[];
     constructor(issues: RouterConfigIssue[]);
 }
-declare function formatRouterConfigIssues(issues: readonly RouterConfigIssue[]): string;
-
-declare function validateRouterConfig(config: RouterConfig, options?: RouterConfigValidationOptions): void;
-declare function getRouterConfigIssues(config: RouterConfig, options?: RouterConfigValidationOptions): RouterConfigIssue[];
 
-declare function mppFromEnv(env: RouterEnv, options?: {
-    recipient?: string;
-    require?: boolean;
-    feePayerKey?: string;
-}): RouterConfig['mpp'] | undefined;
-declare function x402AcceptsFromEnv(env: RouterEnv, options?: {
-    payeeAddress?: string;
-    payeeEnv?: string;
-    network?: string;
-    solanaPayeeAddress?: string;
-    solanaPayeeEnv?: string;
-}): X402AcceptConfig[];
-declare function paidOptionsForProtocols(protocols: readonly ProtocolType[]): PaidOptions;
+/**
+ * Build a {@link RouterConfig} from environment variables.
+ *
+ * `envShape` in this file is the single source of truth for env vars; README
+ * and `.env.example` are drift-tested against `ENV_KEYS`. Validates every
+ * required value up front and throws a single {@link RouterConfigError}
+ * containing all issues at once. Soft warnings (e.g. half-configured KV) are
+ * emitted via `console.warn`.
+ */
+declare function routerConfigFromEnv<const TPrices extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<TPrices>): RouterConfig & {
+    prices?: TPrices;
+};
 
-/** SIWX verification error codes. */
-type SiwxErrorCode = 'siwx_missing_header' | 'siwx_malformed' | 'siwx_expired' | 'siwx_nonce_used' | 'siwx_invalid_signature';
-/** Human-readable error messages for each SIWX error code. */
-declare const SIWX_ERROR_MESSAGES: Record<SiwxErrorCode, string>;
+/** Base mainnet CAIP-2 network ID (`eip155:8453`). */
+declare const BASE_MAINNET_NETWORK = "eip155:8453";
+/** Solana mainnet CAIP-2 network ID. */
+declare const SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+/** USDC contract address on Tempo (the `mpp.currency` value for Tempo USDC). */
+declare const TEMPO_USDC_ADDRESS = "0x20c000000000000000000000b9537d11c60e8b50";
+/** USDC has 6 decimals on Tempo. */
+declare const TEMPO_USDC_DECIMALS = 6;
+/** USDC contract on Base mainnet. */
+declare const BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** USDC has 6 decimals on Base. */
+declare const BASE_USDC_DECIMALS = 6;
+/** All-zeros EVM address. Used as a placeholder/sentinel; not a valid payee. */
+declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** Public Solana x402 facilitator. Override per-deployment via `SOLANA_FACILITATOR_URL`. */
+declare const DEFAULT_SOLANA_FACILITATOR_URL = "https://facilitator.corbits.dev";
 
 interface MonitorEntry {
     provider: string;
@@ -891,5 +889,26 @@ interface ServiceRouter<TPriceKeys extends string = never> {
 declare function createRouter<const P extends Record<string, string> = Record<never, string>>(config: RouterConfig & {
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
+/**
+ * Build a {@link ServiceRouter} from environment variables.
+ *
+ * Validates every required env var up front and throws a single
+ * {@link RouterConfigError} containing all problems at once. Most consumers
+ * should use this entry point. Use {@link createRouter} when you need to
+ * construct a {@link RouterConfig} programmatically.
+ *
+ * The env vars this function reads are the canonical schema in
+ * `src/config/schema.ts` (`ENV_SPEC`).
+ *
+ * @example
+ * ```ts
+ * export const router = createRouterFromEnv({
+ *   title: 'My API',
+ *   description: 'Pay-per-call search.',
+ *   guidance: 'POST /search with { q: string }. Returns top 10 results.',
+ * });
+ * ```
+ */
+declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, BASE_NETWORK, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, type HandlerPaymentContext, HttpError, type KvChange, type KvEntitlementStoreOptions, type KvMppStoreOptions, type KvNonceStoreOptions, type KvStore, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type MppProtocolInfo, type NonceStore, type OveragePolicy, type PaidOptions, type PayToConfig, type PaymentEvent, type PaymentStatus, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigValidationOptions, type RouterEnv, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, SIWX_ERROR_MESSAGES, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettledHandlerErrorContext, type SettlementErrorContext, type SettlementEvent, type SettlementLifecycle, type SettlementLifecycleContext, type SettlementSettledContext, type SiwxErrorCode, type StreamingHandlerContext, TEMPO_USDC_CURRENCY, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, ZERO_EVM_ADDRESS, consolePlugin, createKvEntitlementStore, createKvMppStore, createKvNonceStore, createRouter, formatRouterConfigIssues, getRouterConfigIssues, mppFromEnv, paidOptionsForProtocols, validateRouterConfig, withPrefix, x402AcceptsFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

package/dist/index.d.ts

@@ -4,7 +4,6 @@ import { ZodType } from 'zod';
 import { PaymentRequirements, PaymentRequired, VerifyResponse, SettleResponse, Network } from '@x402/core/types';
 import * as viem from 'viem';
 import { Transport } from 'mppx/server';
-import { Store } from 'mppx';
 
 interface KvStore {
     get(key: string): Promise<unknown>;
@@ -26,42 +25,15 @@ type KvChange<R> = {
     op: 'delete';
     result: R;
 };
-declare function withPrefix(kv: KvStore, prefix: string): KvStore;
 
-declare const SIWX_CHALLENGE_EXPIRY_MS: number;
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
 }
-declare class MemoryNonceStore implements NonceStore {
-    private seen;
-    check(nonce: string): Promise<boolean>;
-    private evict;
-}
-interface KvNonceStoreOptions {
-    prefix?: string;
-    ttlMs?: number;
-}
-declare function createKvNonceStore(kv: KvStore, options?: KvNonceStoreOptions): NonceStore;
 
 interface EntitlementStore {
     has(route: string, wallet: string): Promise<boolean>;
     grant(route: string, wallet: string): Promise<void>;
 }
-declare class MemoryEntitlementStore implements EntitlementStore {
-    private readonly routeToWallets;
-    has(route: string, wallet: string): Promise<boolean>;
-    grant(route: string, wallet: string): Promise<void>;
-}
-interface KvEntitlementStoreOptions {
-    prefix?: string;
-}
-declare function createKvEntitlementStore(kv: KvStore, options?: KvEntitlementStoreOptions): EntitlementStore;
-
-type MppStore = Store.Store;
-interface KvMppStoreOptions {
-    prefix?: string;
-}
-declare function createKvMppStore(kv: KvStore, options?: KvMppStoreOptions): Promise<MppStore>;
 
 interface RequestMeta {
     requestId: string;
@@ -137,7 +109,6 @@ interface RouterPlugin {
     onAlert?(ctx: PluginContext, alert: AlertEvent): void;
     onProviderQuota?(ctx: PluginContext, event: ProviderQuotaEvent): void;
 }
-declare function consolePlugin(): RouterPlugin;
 
 declare class HttpError extends Error {
     readonly status: number;
@@ -222,10 +193,6 @@ interface X402AcceptConfig extends X402AcceptBase {
     /** Per-accept payee override. Function form receives the request and parsed body for dynamic recipient routing. Falls back to `RouterConfig.payeeAddress`. */
     payTo?: PayToConfig;
 }
-interface X402ResolvedAccept extends X402AcceptBase {
-    scheme: string;
-    payTo: string;
-}
 interface X402RouterFacilitatorConfig extends FacilitatorConfig {
     /** Async header builder invoked per facilitator call. Use for short-lived auth tokens (e.g. CDP signed headers). */
     createAcceptsHeaders?: () => Promise<Record<string, string>>;
@@ -233,9 +200,7 @@ interface X402RouterFacilitatorConfig extends FacilitatorConfig {
 /** A facilitator URL or a full `FacilitatorConfig` (URL + auth header builders). */
 type X402FacilitatorTarget = string | X402RouterFacilitatorConfig;
 interface X402FacilitatorsConfig {
-    /** Facilitator for EVM chains (Base, etc.). Defaults to the Coinbase facilitator using `CDP_API_KEY_ID`/`CDP_API_KEY_SECRET`. */
-    evm?: X402FacilitatorTarget;
-    /** Facilitator for Solana. Required to accept Solana payments — there's no default. */
+    /** Facilitator for Solana. Defaults to {@link DEFAULT_SOLANA_FACILITATOR_URL}. The EVM facilitator is hardcoded to Coinbase (CDP) — set `CDP_API_KEY_ID` / `CDP_API_KEY_SECRET`. */
     solana?: X402FacilitatorTarget;
 }
 interface MppProtocolInfo {
@@ -409,7 +374,7 @@ interface RouterConfig {
         /** Per-chain facilitator overrides (`evm`/`solana`). Defaults to the Coinbase facilitator on EVM; set `solana` to accept Solana payments. */
         facilitators?: X402FacilitatorsConfig;
     };
-    /** Observability hook receiving request/auth/payment/settlement events. Use `consolePlugin` for dev, or implement `RouterPlugin` for structured logs/analytics. */
+    /** Observability hook receiving request/auth/payment/settlement events. Implement `RouterPlugin` for structured logs/analytics. */
     plugin?: RouterPlugin;
     /** Single KV cache for SIWX nonce, SIWX entitlement, and MPP tx-hash replay (prefixed `siwx:nonce:`, `siwx:ent:`, `mpp:`). Pass `{ url, token }` for an Upstash-compatible REST endpoint (Upstash, Vercel KV), or a custom `KvStore` implementation. Omitted: auto-bootstraps from `KV_REST_API_URL` + `KV_REST_API_TOKEN`; falls back to in-memory when missing (unsafe in serverless). */
     kvStore?: KvStore | {
@@ -422,7 +387,7 @@ interface RouterConfig {
     mpp?: {
         /** HMAC key for signing/verifying MPP challenge nonces. Persist across deploys — rotating invalidates outstanding 402 challenges. Falls back to `MPP_SECRET_KEY`. */
         secretKey: string;
-        /** Tempo currency contract address (0x-prefixed). Use `TEMPO_USDC_CURRENCY` for USDC on Tempo. */
+        /** Tempo currency contract address (0x-prefixed). Use `TEMPO_USDC_ADDRESS` for USDC on Tempo. */
         currency: string;
         /** MPP payee address (EVM). Overrides `payeeAddress` for MPP only. Required when `payeeAddress` is unset. MUST equal `operatorKey`'s derived address when `session` is enabled. */
         recipient?: string;
@@ -827,50 +792,83 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     private register;
 }
 
-declare const BASE_NETWORK = "eip155:8453";
-declare const SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
-declare const TEMPO_USDC_CURRENCY = "0x20c000000000000000000000b9537d11c60e8b50";
-declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
-
-type RouterEnv = Record<string, string | undefined>;
-type RouterConfigIssueCode = 'missing_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'missing_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'invalid_mpp_operator_key' | 'mpp_operator_equals_fee_payer';
+type RouterConfigIssueCode = 'missing_base_url' | 'invalid_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'invalid_x402_payee' | 'invalid_solana_payee' | 'invalid_solana_facilitator_url' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'missing_mpp_rpc_url' | 'invalid_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'invalid_mpp_operator_key' | 'mpp_operator_equals_fee_payer' | 'missing_discovery_title' | 'missing_discovery_description' | 'missing_discovery_guidance' | 'invalid_server_url' | 'kv_url_without_token' | 'kv_token_without_url' | 'invalid_kv_url' | 'missing_kv_in_production';
+type RouterConfigIssueSeverity = 'error' | 'warning';
 interface RouterConfigIssue {
     code: RouterConfigIssueCode;
     message: string;
     protocol?: ProtocolType;
-}
-interface RouterConfigValidationOptions {
-    env?: RouterEnv;
-    requireCdpKeys?: boolean;
+    /** @default 'error' — warnings are surfaced via `console.warn` and do not throw. */
+    severity?: RouterConfigIssueSeverity;
+}
+/** Options for {@link createRouterFromEnv} / {@link routerConfigFromEnv}. */
+interface CreateRouterFromEnvOptions<TPrices extends Record<string, string> = Record<never, string>> {
+    /** Defaults to `process.env`. Pass an explicit object in tests. */
+    env?: Record<string, string | undefined>;
+    /** Discovery title. Shown in `.well-known/agentcash`, OpenAPI, and `/llms.txt`. */
+    title: string;
+    /** Discovery description. */
+    description: string;
+    /** Long-form usage guidance for agent consumers. Served at `/llms.txt`. Pass an empty string to opt out. */
+    guidance: string;
+    /** Discovery version. @default '1.0.0' */
+    version?: string;
+    /** Optional contact metadata published in discovery. */
+    contact?: DiscoveryConfig['contact'];
+    /** Optional ownership proofs published in `.well-known/agentcash`. */
+    ownershipProofs?: string[];
+    /** Per-route HTTP method hint visibility. */
+    methodHints?: DiscoveryConfig['methodHints'];
+    /** Override the OpenAPI `servers[].url`. Defaults to `BASE_URL`. */
+    serverUrl?: string;
+    /** Centralized price map keyed by route id. `route(key)` auto-applies `.paid(prices[key])` for matching keys. */
+    prices?: TPrices;
+    /** Observability plugin. */
+    plugin?: RouterPlugin;
+    /** Custom KV store. When omitted, the router auto-bootstraps from `KV_REST_API_URL` + `KV_REST_API_TOKEN`. */
+    kvStore?: KvStore;
+    /** Override x402 facilitators. The Solana facilitator defaults to `SOLANA_FACILITATOR_URL` env or `DEFAULT_SOLANA_FACILITATOR_URL`. */
+    x402Facilitators?: X402FacilitatorsConfig;
+    /** Explicit protocol list. Default: `['x402']`, with `'mpp'` added when `MPP_SECRET_KEY` is set. */
+    protocols?: readonly ProtocolType[];
+    /** Require `route({ path })` form for every route. @default false */
+    strictRoutes?: boolean;
 }
 
 declare class RouterConfigError extends Error {
     readonly issues: RouterConfigIssue[];
     constructor(issues: RouterConfigIssue[]);
 }
-declare function formatRouterConfigIssues(issues: readonly RouterConfigIssue[]): string;
-
-declare function validateRouterConfig(config: RouterConfig, options?: RouterConfigValidationOptions): void;
-declare function getRouterConfigIssues(config: RouterConfig, options?: RouterConfigValidationOptions): RouterConfigIssue[];
 
-declare function mppFromEnv(env: RouterEnv, options?: {
-    recipient?: string;
-    require?: boolean;
-    feePayerKey?: string;
-}): RouterConfig['mpp'] | undefined;
-declare function x402AcceptsFromEnv(env: RouterEnv, options?: {
-    payeeAddress?: string;
-    payeeEnv?: string;
-    network?: string;
-    solanaPayeeAddress?: string;
-    solanaPayeeEnv?: string;
-}): X402AcceptConfig[];
-declare function paidOptionsForProtocols(protocols: readonly ProtocolType[]): PaidOptions;
+/**
+ * Build a {@link RouterConfig} from environment variables.
+ *
+ * `envShape` in this file is the single source of truth for env vars; README
+ * and `.env.example` are drift-tested against `ENV_KEYS`. Validates every
+ * required value up front and throws a single {@link RouterConfigError}
+ * containing all issues at once. Soft warnings (e.g. half-configured KV) are
+ * emitted via `console.warn`.
+ */
+declare function routerConfigFromEnv<const TPrices extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<TPrices>): RouterConfig & {
+    prices?: TPrices;
+};
 
-/** SIWX verification error codes. */
-type SiwxErrorCode = 'siwx_missing_header' | 'siwx_malformed' | 'siwx_expired' | 'siwx_nonce_used' | 'siwx_invalid_signature';
-/** Human-readable error messages for each SIWX error code. */
-declare const SIWX_ERROR_MESSAGES: Record<SiwxErrorCode, string>;
+/** Base mainnet CAIP-2 network ID (`eip155:8453`). */
+declare const BASE_MAINNET_NETWORK = "eip155:8453";
+/** Solana mainnet CAIP-2 network ID. */
+declare const SOLANA_MAINNET_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+/** USDC contract address on Tempo (the `mpp.currency` value for Tempo USDC). */
+declare const TEMPO_USDC_ADDRESS = "0x20c000000000000000000000b9537d11c60e8b50";
+/** USDC has 6 decimals on Tempo. */
+declare const TEMPO_USDC_DECIMALS = 6;
+/** USDC contract on Base mainnet. */
+declare const BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** USDC has 6 decimals on Base. */
+declare const BASE_USDC_DECIMALS = 6;
+/** All-zeros EVM address. Used as a placeholder/sentinel; not a valid payee. */
+declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** Public Solana x402 facilitator. Override per-deployment via `SOLANA_FACILITATOR_URL`. */
+declare const DEFAULT_SOLANA_FACILITATOR_URL = "https://facilitator.corbits.dev";
 
 interface MonitorEntry {
     provider: string;
@@ -891,5 +889,26 @@ interface ServiceRouter<TPriceKeys extends string = never> {
 declare function createRouter<const P extends Record<string, string> = Record<never, string>>(config: RouterConfig & {
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
+/**
+ * Build a {@link ServiceRouter} from environment variables.
+ *
+ * Validates every required env var up front and throws a single
+ * {@link RouterConfigError} containing all problems at once. Most consumers
+ * should use this entry point. Use {@link createRouter} when you need to
+ * construct a {@link RouterConfig} programmatically.
+ *
+ * The env vars this function reads are the canonical schema in
+ * `src/config/schema.ts` (`ENV_SPEC`).
+ *
+ * @example
+ * ```ts
+ * export const router = createRouterFromEnv({
+ *   title: 'My API',
+ *   description: 'Pay-per-call search.',
+ *   guidance: 'POST /search with { q: string }. Returns top 10 results.',
+ * });
+ * ```
+ */
+declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, BASE_NETWORK, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, type HandlerPaymentContext, HttpError, type KvChange, type KvEntitlementStoreOptions, type KvMppStoreOptions, type KvNonceStoreOptions, type KvStore, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type MppProtocolInfo, type NonceStore, type OveragePolicy, type PaidOptions, type PayToConfig, type PaymentEvent, type PaymentStatus, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigValidationOptions, type RouterEnv, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, SIWX_ERROR_MESSAGES, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettledHandlerErrorContext, type SettlementErrorContext, type SettlementEvent, type SettlementLifecycle, type SettlementLifecycleContext, type SettlementSettledContext, type SiwxErrorCode, type StreamingHandlerContext, TEMPO_USDC_CURRENCY, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, ZERO_EVM_ADDRESS, consolePlugin, createKvEntitlementStore, createKvMppStore, createKvNonceStore, createRouter, formatRouterConfigIssues, getRouterConfigIssues, mppFromEnv, paidOptionsForProtocols, validateRouterConfig, withPrefix, x402AcceptsFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };