@agentcash/router 1.5.2 → 1.7.0

package/dist/index.d.ts

@@ -1,78 +1,39 @@
 import { FacilitatorConfig } from '@x402/core/http';
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
-import { Store } from 'mppx';
-import { PaymentRequirements, PaymentRequired, SettleResponse, Network } from '@x402/core/types';
+import { PaymentRequirements, PaymentRequired, VerifyResponse, SettleResponse, Network } from '@x402/core/types';
 import * as viem from 'viem';
+import { Transport } from 'mppx/server';
 
-interface EntitlementStore {
-    has(route: string, wallet: string): Promise<boolean>;
-    grant(route: string, wallet: string): Promise<void>;
-}
-/**
- * In-memory SIWX entitlement store.
- *
- * Suitable for development and tests. Not durable across server restarts.
- */
-declare class MemoryEntitlementStore implements EntitlementStore {
-    private readonly routeToWallets;
-    has(route: string, wallet: string): Promise<boolean>;
-    grant(route: string, wallet: string): Promise<void>;
-}
-interface RedisEntitlementStoreOptions {
-    /** Key prefix. Default: 'siwx:entitlement:' */
-    prefix?: string;
-}
-/**
- * Redis-backed entitlement store for paid+SIWX acceleration.
- */
-declare function createRedisEntitlementStore(client: unknown, options?: RedisEntitlementStoreOptions): EntitlementStore;
+interface KvStore {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    del(key: string): Promise<void>;
+    setNxEx(key: string, value: unknown, ttlSeconds: number): Promise<boolean>;
+    sadd(key: string, member: string): Promise<void>;
+    sismember(key: string, member: string): Promise<boolean>;
+    update<R>(key: string, fn: (current: unknown) => KvChange<R>): Promise<R>;
+}
+type KvChange<R> = {
+    op: 'noop';
+    result: R;
+} | {
+    op: 'set';
+    value: unknown;
+    result: R;
+} | {
+    op: 'delete';
+    result: R;
+};
 
-/**
- * SIWX challenge expiry in milliseconds.
- * Currently not configurable per-route — this is a known limitation.
- * Future versions may add `siwx: { expiryMs }` to RouterConfig.
- */
-declare const SIWX_CHALLENGE_EXPIRY_MS: number;
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
 }
-/**
- * In-memory nonce store for development and testing.
- * NOT suitable for production serverless environments (Vercel, etc.)
- * where each function invocation gets fresh memory.
- *
- * For production, use `createRedisNonceStore()` with Upstash or ioredis.
- */
-declare class MemoryNonceStore implements NonceStore {
-    private seen;
-    check(nonce: string): Promise<boolean>;
-    private evict;
-}
-interface RedisNonceStoreOptions {
-    /** Key prefix for nonce storage. Default: 'siwx:nonce:' */
-    prefix?: string;
-    /** TTL in milliseconds. Default: SIWX_CHALLENGE_EXPIRY_MS (5 minutes) */
-    ttlMs?: number;
+
+interface EntitlementStore {
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
 }
-/**
- * Create a Redis-backed nonce store for production SIWX replay protection.
- * Auto-detects client type (Upstash or ioredis) and uses appropriate API.
- *
- * @example
- * ```ts
- * // Upstash (Vercel)
- * import { Redis } from '@upstash/redis';
- * const redis = new Redis({ url: process.env.UPSTASH_URL, token: process.env.UPSTASH_TOKEN });
- * const nonceStore = createRedisNonceStore(redis);
- *
- * // ioredis
- * import Redis from 'ioredis';
- * const redis = new Redis(process.env.REDIS_URL);
- * const nonceStore = createRedisNonceStore(redis);
- * ```
- */
-declare function createRedisNonceStore(client: unknown, opts?: RedisNonceStoreOptions): NonceStore;
 
 interface RequestMeta {
     requestId: string;
@@ -148,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;
@@ -167,14 +127,19 @@ type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 type JsonObject = {
     [key: string]: JsonValue;
 };
-
 interface X402Server {
     initialize(): Promise<void>;
     buildPaymentRequirementsFromOptions(options: Array<{
         scheme: string;
         network: string;
-        price: string;
+        price: string | {
+            asset: string;
+            amount: string;
+            extra?: Record<string, unknown>;
+        };
         payTo: string;
+        maxTimeoutSeconds?: number;
+        extra?: Record<string, unknown>;
     }>, context: {
         request: Request;
     }): Promise<PaymentRequirements[]>;
@@ -184,32 +149,20 @@ interface X402Server {
         description?: string;
     }, error?: string, extensions?: Record<string, unknown>): Promise<PaymentRequired>;
     findMatchingRequirements(requirements: PaymentRequirements[], payload: unknown): PaymentRequirements;
-    verifyPayment(payload: unknown, requirements: PaymentRequirements): Promise<{
-        isValid: boolean;
-        payer?: string;
-    }>;
-    settlePayment(payload: unknown, requirements: PaymentRequirements): Promise<SettleResponse>;
+    verifyPayment(payload: unknown, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    settlePayment(payload: unknown, requirements: PaymentRequirements, declaredExtensions?: Record<string, unknown>, transportContext?: unknown, settlementOverrides?: {
+        amount?: string;
+    }): Promise<SettleResponse>;
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
 type RouteMethod = 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
 interface RouteDefinition<K extends string = string> {
-    /**
-     * Public API path segment (without `/api/` prefix).
-     * Example: `flightaware/airports/id/flights/arrivals`
-     */
+    /** Public API path segment without the `/api/` prefix (e.g. `flightaware/airports/id/flights/arrivals`). */
     path: K;
-    /**
-     * Internal route ID for pricing maps / analytics. Defaults to `path`.
-     *
-     * In `strictRoutes` mode, custom keys are disallowed to prevent discovery
-     * drift between internal IDs and advertised paths.
-     */
+    /** Internal route ID for pricing maps / analytics. Defaults to `path`. Disallowed under `strictRoutes` to prevent discovery drift. */
     key?: string;
-    /**
-     * Optional explicit method. If omitted, defaults to builder behavior
-     * (`POST`, or `GET` when `.query()` is used).
-     */
+    /** Explicit HTTP method. Defaults to `POST`, or `GET` when `.query()` is used. */
     method?: RouteMethod;
 }
 interface TierConfig {
@@ -223,26 +176,31 @@ type PricingConfig<TBody = unknown> = string | ((body: TBody) => string | Promis
 };
 type PayToConfig = string | ((request: Request, body?: unknown) => string | Promise<string>);
 interface X402AcceptBase {
+    /** Chain identifier (e.g. `base`, `base-sepolia`, `solana-mainnet`). */
     network: string;
+    /** Token contract address (EVM) or mint (Solana). Defaults to USDC for the network. */
     asset?: string;
+    /** Token decimals. Defaults to USDC's 6. */
     decimals?: number;
+    /** Max payment-proof age the facilitator will accept, in seconds. */
     maxTimeoutSeconds?: number;
+    /** Extra fields passed through to the x402 PaymentRequirements `extra` block. */
     extra?: Record<string, unknown>;
 }
 interface X402AcceptConfig extends X402AcceptBase {
+    /** `'exact'` for fixed-price one-shot payments; `'upto'` for settle-≤-cap (required for `.paid({ dynamic: true })` on x402). @default 'exact' */
     scheme?: string;
+    /** 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>>;
 }
+/** A facilitator URL or a full `FacilitatorConfig` (URL + auth header builders). */
 type X402FacilitatorTarget = string | X402RouterFacilitatorConfig;
 interface X402FacilitatorsConfig {
-    evm?: X402FacilitatorTarget;
+    /** 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 {
@@ -258,6 +216,12 @@ interface PaidOptions {
     payTo?: PayToConfig;
     /** Override MPP protocol metadata in x-payment-info discovery. */
     mpp?: MppProtocolInfo;
+    /** Handler-driven dynamic pricing: handler calls `charge()` per tick, total billed is `tickCost × calls` capped at `maxPrice`. Requires `maxPrice`. Incompatible with tiered pricing. On x402 needs an `upto` accept; on MPP needs `RouterConfig.mpp.session`. */
+    dynamic?: boolean;
+    /** Per-tick cost (positive decimal-dollar string). Required for `.paid({ dynamic: true })`. Also the voucher-headroom granularity for MPP sessions. */
+    tickCost?: string;
+    /** Cosmetic unit label for 402 challenges / UIs (e.g. `'token'`, `'byte'`). Does not affect billing. */
+    unitType?: string;
 }
 type PaymentStatus = 'verified' | 'settled';
 interface HandlerPaymentContext {
@@ -293,26 +257,16 @@ interface SettledHandlerErrorContext<TBody = unknown> extends SettlementSettledC
     error: unknown;
 }
 interface SettlementLifecycle<TBody = unknown> {
-    /**
-     * Runs after the handler returns a successful response, before router-controlled
-     * settlement/broadcast. Throw with `.status` to return a specific error and
-     * skip settlement when the protocol flow has not already settled.
-     */
+    /** Runs after a successful handler response, before router-controlled settlement/broadcast. Throw with `.status` to fail the request and skip settlement (when not already settled). */
     beforeSettle?: (ctx: SettlementLifecycleContext<TBody>) => void | Promise<void>;
-    /**
-     * Runs after successful settlement. Use for durable ledgers and audit rows.
-     * Errors are alerted and do not change the already-settled response.
-     */
+    /** Runs after successful settlement; for durable ledgers and audit rows. Errors are alerted but don't change the already-settled response. */
     afterSettle?: (ctx: SettlementSettledContext<TBody>) => void | Promise<void>;
-    /**
-     * Runs when the router has already observed a settled payment, then the
-     * handler returns an error response. Use for app-owned refund or
-     * compensation queues.
-     */
+    /** Runs when payment was settled but the handler then returned an error response. Use for app-owned refund / compensation queues. */
     onSettledHandlerError?: (ctx: SettledHandlerErrorContext<TBody>) => void | Promise<void>;
     /** Runs when router-controlled settlement fails after the handler succeeded. */
     onSettlementError?: (ctx: SettlementErrorContext<TBody>) => void | Promise<void>;
 }
+type ChargeFn = () => Promise<void>;
 interface HandlerContext<TBody = undefined, TQuery = undefined> {
     body: TBody;
     query: TQuery;
@@ -325,6 +279,10 @@ interface HandlerContext<TBody = undefined, TQuery = undefined> {
     alert: AlertFn;
     setVerifiedWallet: (addr: string) => void;
 }
+/** Handler context for streaming `.paid({ dynamic: true })` handlers (async generators). Call `charge()` once per billable unit. */
+interface StreamingHandlerContext<TBody = undefined, TQuery = undefined> extends HandlerContext<TBody, TQuery> {
+    charge: ChargeFn;
+}
 type OveragePolicy = 'same-rate' | 'increased-rate' | 'hard-stop';
 type QuotaLevel = 'healthy' | 'warn' | 'critical';
 interface QuotaInfo {
@@ -358,28 +316,17 @@ interface RouteEntry {
      */
     siwxEnabled?: boolean;
     pricing?: PricingConfig;
+    /** When true the route is dynamic-priced; bills `tickCost` per request (request-mode) or per `charge()` call (streaming). */
+    dynamicPrice?: boolean;
+    /** True iff handler is an async generator. Streaming handlers settle per-tick over SSE; non-streaming dynamic handlers bill exactly `tickCost` per request. Set by the builder at `.handler(fn)` time. */
+    streaming?: boolean;
     protocols: ProtocolType[];
     bodySchema?: ZodType;
     querySchema?: ZodType;
     outputSchema?: ZodType;
-    /**
-     * Optional conforming example for the request input (body for body routes, query params for query routes).
-     * When present, it must satisfy the corresponding schema and is validated at route registration.
-     *
-     * Emitted in the bazaar discovery extension so indexers can advertise a working sample call.
-     */
+    /** Optional conforming example for the request input (body or query). Validated against the schema at registration. Emitted in the bazaar discovery extension. */
     inputExample?: JsonObject;
-    /**
-     * Optional conforming example for the response output. When present, it must
-     * satisfy `outputSchema` and is validated at route registration.
-     *
-     * Accepts any JSON value (object, array, or primitive) to support top-level array or
-     * primitive response schemas.
-     *
-     * Emitted in the bazaar discovery extension. Without it the `output` block is
-     * dropped from the declaration entirely (the output schema alone cannot be
-     * exposed in bazaar without an example).
-     */
+    /** Optional conforming example for the response output (any JSON value). Validated against `outputSchema` at registration. Without it, the bazaar `output` block is omitted (schema alone can't be exposed). */
     outputExample?: JsonValue;
     description?: string;
     path?: string;
@@ -393,6 +340,10 @@ interface RouteEntry {
     validateFn?: (body: unknown) => void | Promise<void>;
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
+    /** Per-tick cost (decimal-dollar). Required when `dynamicPrice` is true. */
+    tickCost?: string;
+    /** Cosmetic unit label for 402 challenges and client UIs. */
+    unitType?: string;
 }
 interface DiscoveryConfig {
     title: string;
@@ -410,93 +361,53 @@ interface DiscoveryConfig {
     serverUrl?: string;
 }
 interface RouterConfig {
+    /** Default payee for paid routes — populates `payTo` on the auto-generated x402 `exact` accept and acts as the MPP `recipient` fallback. Override per-protocol via `x402.accepts[i].payTo` / `mpp.recipient`, or per-route via `.paid({ payTo })`. */
     payeeAddress?: string;
-    /**
-     * Origin URL (e.g. `https://myapp.com`).
-     * Used for 402 challenge realm, discovery URLs, OpenAPI servers, and MPP memo indexing.
-     *
-     * **Required.** No auto-detection — the realm is load-bearing for payment matching,
-     * so it must be explicitly set by the consuming app.
-     */
+    /** Origin URL (required). Used as 402 realm, discovery base, OpenAPI server, and MPP memo prefix — must match the public domain or payment matching breaks. */
     baseUrl: string;
+    /** Default chain for the auto-generated x402 `exact` accept (e.g. `base`, `base-sepolia`). Ignored when `x402.accepts` is set. @default 'base' */
     network?: string;
+    /** x402 protocol settings. Omit to default to a single `exact`/USDC accept on `network` paid to `payeeAddress`, verified via the Coinbase default facilitator (requires `CDP_API_KEY_ID`/`CDP_API_KEY_SECRET`). */
     x402?: {
+        /** Explicit accepts list (scheme + network + asset). Overrides the auto-generated default. Add an `upto` accept here to enable `.paid({ dynamic: true })` on x402. */
         accepts?: X402AcceptConfig[];
+        /** 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. Implement `RouterPlugin` for structured logs/analytics. */
     plugin?: RouterPlugin;
-    siwx?: {
-        nonceStore?: NonceStore;
-        entitlementStore?: EntitlementStore;
+    /** 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 | {
+        url: string;
+        token: string;
     };
+    /** Centralized price map keyed by route ID. `.route(key)` auto-applies `.paid(prices[key])` when `key` is listed; per-route `.paid()` still works for keys not in the map. */
     prices?: Record<string, string>;
+    /** MPP (Tempo) payment-channel config. Required when `protocols` includes `'mpp'`. */
     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_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;
-        /** Tempo RPC URL for on-chain verification. Falls back to TEMPO_RPC_URL env var. */
+        /** Tempo RPC URL for on-chain verification. Falls back to `TEMPO_RPC_URL`. */
         rpcUrl?: string;
-        /**
-         * Private key of the account that sponsors transaction fees.
-         * When set, clients don't need gas tokens — the server pays fees on their behalf.
-         * Must be a hex-encoded private key (e.g. `0xabc123...`).
-         */
+        /** Hex private key. Signs channel close/settle; required for `session`. Address MUST equal `recipient`/payee — mppx asserts sender===payee on settle. Validated at init. */
+        operatorKey?: string;
+        /** Hex private key. Sponsors gas for client channel open/topUp. MUST resolve to a different address than `operatorKey` — Tempo rejects sender===feePayer. Validated at init. Omit to make clients pay their own gas. */
         feePayerKey?: string;
-        /**
-         * Persistent store for transaction hash replay protection.
-         *
-         * Without this, mppx defaults to `Store.memory()` which is wiped on every cold start —
-         * unsafe on Vercel or any multi-instance deployment. Pass `Store.upstash(redis)` or
-         * `Store.cloudflare(kv)` for a shared persistent store.
-         *
-         * @example
-         * import { Store } from 'mppx'
-         * store: Store.upstash({ get, set, del })
-         * store: Store.cloudflare(env.MY_KV_NAMESPACE)
-         */
-        store?: Store.Store;
-        /**
-         * When `true`, auto-configures an Upstash-backed persistent store from Vercel KV
-         * environment variables (`KV_REST_API_URL` + `KV_REST_API_TOKEN`).
-         *
-         * Uses raw `fetch` against the Upstash REST API — no extra npm dependencies.
-         * Ignored when `store` is explicitly provided.
-         *
-         * @example
-         * createRouter({
-         *   mpp: {
-         *     secretKey: process.env.MPP_SECRET_KEY!,
-         *     currency: TEMPO_USDC_CURRENCY,
-         *     useDefaultStore: true,
-         *   }
-         * })
-         */
-        useDefaultStore?: boolean;
+        /** Enables MPP payment-channel sessions for `.paid({ dynamic: true })` routes (registers both request and SSE session middleware). Also requires `mpp.operatorKey`. */
+        session?: {
+            /** Suggested deposit on the 402 challenge = `tickCost × depositMultiplier` USDC. Route `maxPrice` overrides. @default 10 */
+            depositMultiplier?: number;
+        };
     };
-    /**
-     * Payment protocols to accept on paid routes unless a route overrides them.
-     *
-     * @default ['x402']
-     *
-     * @example
-     * // Accept both x402 and MPP payments
-     * createRouter({
-     *   protocols: ['x402', 'mpp'],
-     *   mpp: { secretKey, currency: TEMPO_USDC_CURRENCY, recipient },
-     *   prices: { 'exa/search': '0.01' }
-     * })
-     */
+    /** Payment protocols to accept on paid routes unless overridden per route. @default ['x402'] */
     protocols?: ProtocolType[];
-    /**
-     * Enforce explicit, path-first route definitions.
-     *
-     * When enabled:
-     * - `.route('key')` is rejected; use `.route({ path })`.
-     * - custom `key` differing from `path` is rejected.
-     *
-     * This prevents discovery/openapi drift caused by shorthand internal keys.
-     */
+    /** When true, `.route('key')` is rejected (use `.route({ path })`) and custom `key !== path` is rejected. Prevents discovery/openapi drift. */
     strictRoutes?: boolean;
+    /** Static metadata for auto-generated discovery surfaces — `/.well-known/x402`, OpenAPI (`/api/openapi`), and `/llms.txt`. */
     discovery: DiscoveryConfig;
 }
 
@@ -519,6 +430,14 @@ interface ResolvedX402Facilitator {
     config: X402RouterFacilitatorConfig;
 }
 
+type MppxMiddlewareResponse<T extends Transport.AnyTransport> = {
+    status: 402;
+    challenge: Transport.ChallengeOutputOf<T>;
+} | {
+    status: 200;
+    withReceipt: Transport.WithReceipt<T>;
+};
+type MppxMiddleware<TOptions, T extends Transport.AnyTransport> = (options: TOptions) => (input: Request) => Promise<MppxMiddlewareResponse<T>>;
 interface RouterDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
@@ -533,15 +452,22 @@ interface RouterDeps {
     x402FacilitatorsByNetwork?: Record<string, ResolvedX402Facilitator>;
     x402Accepts: X402AcceptConfig[];
     mppx?: {
-        charge: (options: {
+        charge: MppxMiddleware<{
             amount: string;
-        }) => (input: Request) => Promise<{
-            status: 402;
-            challenge: Response;
-        } | {
-            status: 200;
-            withReceipt: (response: Response) => Response;
-        }>;
+        }, Transport.Http>;
+        sessionRequest?: MppxMiddleware<{
+            amount: string;
+            unitType?: string;
+            suggestedDeposit?: string;
+        }, Transport.Http>;
+        sessionStream?: MppxMiddleware<{
+            amount: string;
+            unitType?: string;
+            suggestedDeposit?: string;
+        }, Transport.Sse>;
+    } | null;
+    mppSessionConfig?: {
+        depositMultiplier: number;
     } | null;
     tempoClient?: viem.Client | null;
 }
@@ -551,29 +477,22 @@ type OrchestrateDeps = RouterDeps;
 
 type True = true;
 type False = false;
-/**
- * Active request-input type at a builder position. Resolves to `TBody` when
- * `.body()` has been called, `TQuery` when `.query()` has been called, and
- * `never` when neither — making `.inputExample()` unusable before a schema
- * is set (the literal won't assign to `never`).
- */
 type InputTypeFor<TBody, TQuery> = [TBody] extends [undefined] ? [TQuery] extends [undefined] ? never : TQuery : TBody;
-/**
- * The handler argument type. Narrows to the real handler signature when the
- * builder state is valid, and to a descriptive error object when it isn't —
- * the mismatch surfaces as a TS type error at the `.handler(...)` call site
- * with the `__missing` string as the contextual hint.
- *
- * Encoded as a conditional argument rather than overload `this:` constraints
- * because TypeScript doesn't reliably gate overload selection on `this` for
- * generic classes (structurally identical instance types collapse).
- */
+type RequestHandlerFn<TBody, TQuery> = (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>;
+type StreamingHandlerFn<TBody, TQuery> = (ctx: StreamingHandlerContext<TBody, TQuery>) => AsyncIterable<unknown>;
 type HandlerArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean> = HasAuth extends true ? [NeedsBody, HasBody] extends [true, false] ? {
     __missing: 'Call .body(schema) — dynamic/tiered pricing requires a body schema to resolve the price against';
-} : (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown> : {
+} : RequestHandlerFn<TBody, TQuery> : {
     __missing: 'Select an auth mode: .paid(pricing), .siwx(), .apiKey(resolver), or .unprotected()';
 };
-declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false> {
+type StreamArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean, IsDynamic extends boolean> = HasAuth extends true ? IsDynamic extends true ? [NeedsBody, HasBody] extends [true, false] ? {
+    __missing: 'Call .body(schema) — dynamic pricing requires a body schema to resolve the price against';
+} : StreamingHandlerFn<TBody, TQuery> : {
+    __missing: 'Streaming handlers require .paid({ dynamic: true, tickCost, unitType, maxPrice }) — static/free routes cannot meter per-chunk billing';
+} : {
+    __missing: 'Select an auth mode: .paid({ dynamic: true, ... }) — streaming requires handler-driven dynamic pricing';
+};
+declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false, IsDynamic extends boolean = false> {
     /** @internal */ readonly _key: string;
     /** @internal */ readonly _registry: RouteRegistry;
     /** @internal */ readonly _deps: OrchestrateDeps;
@@ -583,6 +502,9 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     /** @internal */ _protocols: ProtocolType[];
     /** @internal */ _maxPrice: string | undefined;
     /** @internal */ _minPrice: string | undefined;
+    /** @internal */ _dynamicPrice: boolean;
+    /** @internal */ _tickCost: string | undefined;
+    /** @internal */ _unitType: string | undefined;
     /** @internal */ _payTo: PayToConfig | undefined;
     /** @internal */ _bodySchema: ZodType | undefined;
     /** @internal */ _querySchema: ZodType | undefined;
@@ -602,10 +524,63 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     /** @internal */ _mppInfo: MppProtocolInfo | undefined;
     constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
     private fork;
-    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody>;
+    /**
+     * Charge a fixed price per request, denominated in USDC as a decimal string.
+     *
+     * @example
+     * ```ts
+     * router.route('search').paid('0.01').handler(handler);
+     * ```
+     */
+    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, IsDynamic>;
+    /**
+     * Configure handler-driven dynamic pricing — each tick costs `tickCost` USDC,
+     * capped at `maxPrice`. Pair with `.handler()` for one-tick-per-request
+     * billing, or with `.stream()` for per-yield metering.
+     *
+     * @example
+     * ```ts
+     * router
+     *   .route('llm/stream')
+     *   .paid({ dynamic: true, tickCost: '0.0001', unitType: 'token', maxPrice: '0.05' })
+     *   .stream(async function* ({ charge }) { await charge(); yield 'hi'; });
+     * ```
+     */
+    paid(options: PaidOptions & {
+        dynamic: true;
+        maxPrice: string;
+    }): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, True>;
+    /**
+     * Compute the price from the parsed body before issuing the 402 challenge.
+     * Throw an `HttpError` from the pricing function to reject the request before
+     * payment is requested.
+     *
+     * @example
+     * ```ts
+     * router
+     *   .route('llm')
+     *   .paid((body) => `${body.tokens * 0.0001}`, { maxPrice: '5.00' })
+     *   .body(schema)
+     *   .handler(handler);
+     * ```
+     */
     paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
         maxPrice?: string;
-    }): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody>;
+    }): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, IsDynamic>;
+    /**
+     * Select a price tier from `body[field]`, optionally falling back to the
+     * `default` tier when the value is missing. The 402 challenge advertises the
+     * highest tier price.
+     *
+     * @example
+     * ```ts
+     * router
+     *   .route('upload')
+     *   .paid({ field: 'size', tiers: { sm: { price: '0.01' }, lg: { price: '0.10' } } })
+     *   .body(schema)
+     *   .handler(handler);
+     * ```
+     */
     paid(pricing: {
         field: string;
         tiers: Record<string, {
@@ -613,149 +588,287 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
             label?: string;
         }>;
         default?: string;
-    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody>;
-    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody>;
-    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, True, NeedsBody, HasBody>;
-    unprotected(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody>;
-    provider(name: string, config?: ProviderConfig): this;
-    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True>;
-    body<T>(schema: ZodType<T>, example: T & JsonObject): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True>;
-    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody>;
-    query<T>(schema: ZodType<T>, example: T & JsonObject): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody>;
-    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody>;
-    output<T>(schema: ZodType<T>, example: T & JsonValue): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody>;
+    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, IsDynamic>;
     /**
-     * Provide a conforming example of the request input (body or query params).
+     * Require Sign-In-with-X wallet identity on this route — clients prove
+     * control of a wallet via a signed challenge. Combine with `.paid()` to gate
+     * a paid route on a verified wallet identity.
      *
-     * Optional. When provided, the example is validated against the request schema
-     * at route registration and embedded in the bazaar discovery extension so
-     * indexers can advertise a working sample call.
+     * @example
+     * ```ts
+     * router.route('profile').siwx().handler(async ({ wallet }) => getProfile(wallet));
+     * ```
+     */
+    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, IsDynamic>;
+    /**
+     * Require an `X-API-Key` header (or `Authorization: Bearer <key>`); the
+     * resolver returns the account record, or `null` for 401. Composes with
+     * `.paid()` — key is checked first, payment second.
      *
-     * For the common case, pass the example directly to `.body(schema, example)` or
-     * `.query(schema, example)` instead.
+     * @example
+     * ```ts
+     * router
+     *   .route('admin/users')
+     *   .apiKey(async (key) => db.admin.findByKey(key))
+     *   .handler(async ({ account }) => db.user.list(account.orgId));
+     * ```
+     */
+    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, True, NeedsBody, HasBody, IsDynamic>;
+    /**
+     * Mark the route as public — no auth, no payment, no SIWX. The handler
+     * receives `null` for `wallet`, `payment`, and `account`.
      *
      * @example
      * ```ts
-     * router.route('search')
+     * router.route('health').unprotected().handler(async () => ({ status: 'ok' }));
+     * ```
+     */
+    unprotected(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, IsDynamic>;
+    /**
+     * Tag the route with an upstream provider for discovery and provider-side
+     * monitoring. The provider name and config surface in `well-known` and
+     * OpenAPI output.
+     *
+     * @example
+     * ```ts
+     * router
+     *   .route('search')
      *   .paid('0.01')
-     *   .body(z.object({ q: z.string() }))
-     *   .inputExample({ q: 'hello world' })
-     *   .handler(async ({ body }) => { ... });
+     *   .provider('exa', { quotaPerMonth: 1000 })
+     *   .handler(handler);
      * ```
      */
-    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody>;
+    provider(name: string, config?: ProviderConfig): this;
     /**
-     * Provide a conforming example of the response output.
+     * Declare the request body's Zod schema. Parsed body is typed as `ctx.body`
+     * in the handler. Use `.inputExample()` to attach a discovery example.
      *
-     * Optional. When provided, the example is validated against the output schema
-     * at route registration and embedded in the bazaar discovery extension so
-     * indexers can advertise the response shape.
+     * @example
+     * ```ts
+     * .body(z.object({ query: z.string() }))
+     *   .handler(async ({ body }) => search(body.query));
+     * ```
+     */
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True, IsDynamic>;
+    /**
+     * Declare a query-string Zod schema and switch the route to `GET`. Parsed
+     * query is typed as `ctx.query` in the handler. Use `.inputExample()` to
+     * attach a discovery example.
      *
-     * For the common case, pass the example directly to `.output(schema, example)` instead.
+     * @example
+     * ```ts
+     * .query(z.object({ id: z.string() }))
+     *   .handler(async ({ query }) => getById(query.id));
+     * ```
+     */
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody, IsDynamic>;
+    /**
+     * Declare the response output's Zod schema for OpenAPI generation. The
+     * runtime does not validate handler return values — use Zod's `.parse()`
+     * inside the handler if strict output validation is required. Use
+     * `.outputExample()` to attach a discovery example.
      *
-     * Accepts any JSON value (objects, arrays, or primitives) — top-level array
-     * or primitive responses (e.g. `z.array(...)`) are supported alongside the
-     * common object case.
+     * @example
+     * ```ts
+     * .output(z.object({ result: z.string() }))
+     *   .handler(async () => ({ result: 'ok' }));
+     * ```
+     */
+    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody, IsDynamic>;
+    /**
+     * Attach an example of the request body or query for discovery output,
+     * validated against the registered schema at registration.
      *
      * @example
      * ```ts
-     * router.route('search')
-     *   .paid('0.01')
-     *   .output(z.object({ results: z.array(z.string()) }))
-     *   .outputExample({ results: ['a', 'b'] })
-     *   .handler(async () => { ... });
+     * .body(searchSchema).inputExample({ query: 'cats' });
+     * ```
+     */
+    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, IsDynamic>;
+    /**
+     * Attach an example response for discovery output, validated against the
+     * registered output schema at registration.
      *
-     * // Top-level array response
-     * router.route('chains')
-     *   .paid('0.01')
-     *   .output(z.array(z.object({ name: z.string() })))
-     *   .outputExample([{ name: 'Ethereum' }])
-     *   .handler(async () => { ... });
+     * @example
+     * ```ts
+     * .output(resultSchema).outputExample({ result: 'ok' });
+     * ```
+     */
+    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, IsDynamic>;
+    /**
+     * Set a human-readable summary of the route. Surfaces in OpenAPI,
+     * `well-known`, and `llms.txt` discovery output.
+     *
+     * @example
+     * ```ts
+     * .description('Search indexed web pages by full-text query');
      * ```
      */
-    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody>;
     description(text: string): this;
+    /**
+     * Override the URL path advertised in discovery output. Defaults to the
+     * registry key passed to `.route()`.
+     *
+     * @example
+     * ```ts
+     * router.route('search').path('/v2/search').handler(handler);
+     * ```
+     */
     path(p: string): this;
+    /**
+     * Override the HTTP method advertised in discovery. Defaults to `POST`, or
+     * `GET` when `.query()` has been called.
+     *
+     * @example
+     * ```ts
+     * router.route('items/delete').method('DELETE').handler(handler);
+     * ```
+     */
     method(m: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH'): this;
     /**
-     * Add pre-payment validation that runs after body parsing but before the 402
-     * challenge is shown. Use this for async business logic like "is this resource
-     * available?" or "has this user hit their rate limit?".
+     * Run validation against the parsed body before the 402 challenge. Throw
+     * `Object.assign(new Error('...'), { status })` to reject with a custom
+     * status code; defaults to 400. Requires `.body()` to be called first.
      *
-     * Requires `.body()` — call `.body()` before `.validate()` for type inference.
+     * @example
+     * ```ts
+     * .body(RegisterSchema).validate(async (body) => {
+     *   if (await isTaken(body.name)) {
+     *     throw Object.assign(new Error('taken'), { status: 409 });
+     *   }
+     * });
+     * ```
+     */
+    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, IsDynamic>;
+    /**
+     * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
+     * succeeds but before on-chain settlement and can cancel the charge;
+     * `afterSettle` runs after settlement completes (success or failure).
      *
      * @example
-     * ```typescript
-     * router
-     *   .route('domain/register')
-     *   .paid(calculatePrice)
-     *   .body(RegisterSchema)  // .body() first for type inference
-     *   .validate(async (body) => {
-     *     if (await isDomainTaken(body.domain)) {
-     *       throw Object.assign(new Error('Domain taken'), { status: 409 });
-     *     }
-     *   })
-     *   .handler(async ({ body }) => { ... });
+     * ```ts
+     * .settlement({
+     *   beforeSettle: ({ result }) => (result.refund ? 'skip' : 'continue'),
+     *   afterSettle: ({ tx }) => analytics.track('settled', { tx }),
+     * });
      * ```
      */
-    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody>;
+    settlement(lifecycle: SettlementLifecycle<TBody>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, IsDynamic>;
     /**
-     * Add route-specific settlement hooks.
+     * Register the request handler and return the Next.js route function. The
+     * handler receives a typed context and may return a value (serialized to
+     * JSON), a raw `Response`, or throw an `HttpError` for a non-2xx status.
      *
-     * `beforeSettle` runs after a successful handler response but before
-     * router-controlled settlement/broadcast, so it can still prevent the charge
-     * for x402 and MPP transaction-payload flows. `afterSettle` runs after
-     * settlement and is intended for durable ledgers or app-owned refund queues.
+     * @example
+     * ```ts
+     * export const POST = router
+     *   .route('search')
+     *   .paid('0.01')
+     *   .body(schema)
+     *   .handler(async ({ body, wallet }) => searchService(body, wallet));
+     * ```
      */
-    settlement(lifecycle: SettlementLifecycle<TBody>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody>;
     handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody>): (request: NextRequest) => Promise<Response>;
+    /**
+     * Register a streaming handler (`async function*`) and return the Next.js
+     * route function. Each `charge()` call bills one tick (`tickCost` USDC) up
+     * to `maxPrice`; requires `.paid({ dynamic: true, ... })` and MPP session mode.
+     *
+     * @example
+     * ```ts
+     * export const POST = router
+     *   .route('llm/stream')
+     *   .paid({ dynamic: true, tickCost: '0.0001', unitType: 'token', maxPrice: '0.05' })
+     *   .body(schema)
+     *   .stream(async function* ({ body, charge }) {
+     *     for await (const token of streamLLM(body.prompt)) {
+     *       await charge();
+     *       yield token;
+     *     }
+     *   });
+     * ```
+     */
+    stream(fn: StreamArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, IsDynamic>): (request: NextRequest) => Promise<Response>;
+    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' | 'missing_mpp_default_store_env';
+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;
+    /** @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;
 }
-interface RouterConfigValidationOptions {
-    env?: RouterEnv;
-    requireCdpKeys?: boolean;
-}
+
 declare class RouterConfigError extends Error {
     readonly issues: RouterConfigIssue[];
     constructor(issues: RouterConfigIssue[]);
 }
-declare function validateRouterConfig(config: RouterConfig, options?: RouterConfigValidationOptions): void;
-declare function getRouterConfigIssues(config: RouterConfig, options?: RouterConfigValidationOptions): RouterConfigIssue[];
-declare function formatRouterConfigIssues(issues: readonly RouterConfigIssue[]): string;
-declare function mppFromEnv(env: RouterEnv, options?: {
-    recipient?: string;
-    require?: boolean;
-    useDefaultStore?: 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;
 
 /**
- * SIWX verification error codes.
- * Enables clients to auto-retry transient failures (e.g., expired challenge).
+ * 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`.
  */
-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>;
+declare function routerConfigFromEnv<const TPrices extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<TPrices>): RouterConfig & {
+    prices?: TPrices;
+};
+
+/** 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;
@@ -776,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, 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 RedisEntitlementStoreOptions, type RedisNonceStoreOptions, 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, TEMPO_USDC_CURRENCY, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, ZERO_EVM_ADDRESS, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter, formatRouterConfigIssues, getRouterConfigIssues, mppFromEnv, paidOptionsForProtocols, validateRouterConfig, 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 };