@agent-score/commerce 1.0.0

package/dist/payment/index.d.ts

@@ -0,0 +1,716 @@
+export { P as PaymentRequiredHeaderInput, a as aliasAmountFields, p as paymentRequiredHeader, w as wwwAuthenticateHeader } from '../wwwauthenticate-CU1eNvMQ.js';
+export { P as PaymentSigner, S as SignerNetwork, a as extractPaymentSigner, r as readX402PaymentHeader } from '../signer-Cvdwn6Cs.js';
+
+interface PaymentRequestInput {
+    /** Symbolic rail name (e.g., 'tempo-mainnet', 'x402-base-mainnet') — fills in defaults */
+    rail?: string;
+    /** Amount in USD as a number or string. Converted to raw integer using `decimals`. */
+    amountUsd: string | number;
+    /** Token contract address or currency code. Defaults from rail. */
+    currency?: string;
+    /** Decimal precision for the amount. Defaults from rail (6 for USDC, 2 for USD). */
+    decimals?: number;
+    /** Recipient address (on-chain). Optional for stripe-style rails. */
+    recipient?: string;
+    /** EVM chain ID (goes into methodDetails.chainId). Defaults from rail. */
+    chainId?: number;
+    /** Stripe profile_id or similar (goes into methodDetails.networkId — note camelCase per link-cli's mpp decode validator). */
+    networkId?: string;
+}
+/**
+ * Build the base64-encoded `request` blob for an MPP Payment directive (per the
+ * paymentauth.org spec). Output shape matches what link-cli `mpp decode` expects:
+ *
+ *   { amount: "<raw_integer>", currency: "<token>", recipient?: "<addr>",
+ *     methodDetails?: { chainId?: number, networkId?: string } }
+ */
+declare function buildPaymentRequestBlob(input: PaymentRequestInput): string;
+interface PaymentDirectiveInput {
+    /** Symbolic rail name — sets `method` automatically */
+    rail?: string;
+    /** Challenge id (unique per request, used to correlate retries) */
+    id: string;
+    /** Realm — the host of the merchant URL (e.g., "agents.merchant.example") */
+    realm: string;
+    /** MPP method name. Defaults from rail (e.g., 'tempo', 'stripe'). */
+    method?: string;
+    /** MPP intent. Defaults to 'charge'. */
+    intent?: string;
+    /** ISO-8601 expiry timestamp. Defaults to now + 5 minutes. */
+    expires?: string;
+    /** Base64-encoded request blob. Pass the result of buildPaymentRequestBlob. */
+    request: string;
+}
+/**
+ * Format an MPP Payment directive string for the WWW-Authenticate header.
+ * Output shape: `Payment id="...", realm="...", method="...", intent="charge",
+ *                expires="...", request="<base64>"`
+ */
+declare function paymentDirective(input: PaymentDirectiveInput): string;
+interface BuildPaymentDirectiveInput extends Omit<PaymentRequestInput, 'rail'>, Omit<PaymentDirectiveInput, 'request'> {
+    rail: string;
+}
+/**
+ * Convenience: build the request blob and the directive in one call. Most vendors
+ * want this rather than the two-step form.
+ */
+declare function buildPaymentDirective(input: BuildPaymentDirectiveInput): string;
+
+/**
+ * Named network registry. Vendors reference symbolic names (`networks.base.mainnet.caip2`)
+ * instead of magic strings. Lifted from agentscore-pay's constants.
+ */
+declare const networks: {
+    readonly base: {
+        readonly mainnet: {
+            readonly caip2: "eip155:8453";
+            readonly chainId: 8453;
+        };
+        readonly sepolia: {
+            readonly caip2: "eip155:84532";
+            readonly chainId: 84532;
+        };
+    };
+    readonly solana: {
+        readonly mainnet: {
+            readonly caip2: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+        };
+        readonly devnet: {
+            readonly caip2: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+        };
+    };
+    readonly tempo: {
+        readonly mainnet: {
+            readonly caip2: "eip155:4217";
+            readonly chainId: 4217;
+        };
+        readonly testnet: {
+            readonly caip2: "eip155:42431";
+            readonly chainId: 42431;
+        };
+    };
+};
+type NetworkFamily = keyof typeof networks;
+/**
+ * Returns the family name (base/solana/tempo) for a given CAIP-2 network string,
+ * or null if the network isn't in the registry. Useful for routing settlement
+ * by network.
+ */
+declare function networkFamily(caip2: string): NetworkFamily | null;
+
+/**
+ * USDC token registry per network. Used by paymentDirective and rail definitions.
+ * Lifted from agentscore-pay's constants.
+ */
+declare const USDC: {
+    readonly base: {
+        readonly mainnet: {
+            readonly address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+            readonly decimals: 6;
+        };
+        readonly sepolia: {
+            readonly address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+            readonly decimals: 6;
+        };
+    };
+    readonly solana: {
+        readonly mainnet: {
+            readonly mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+            readonly decimals: 6;
+        };
+        readonly devnet: {
+            readonly mint: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
+            readonly decimals: 6;
+        };
+    };
+    readonly tempo: {
+        readonly mainnet: {
+            readonly address: "0x20C000000000000000000000b9537d11c60E8b50";
+            readonly decimals: 6;
+        };
+        readonly testnet: {
+            readonly address: "0x20c0000000000000000000000000000000000000";
+            readonly decimals: 6;
+        };
+    };
+};
+
+/**
+ * Symbolic rail names mapped to their protocol details. Vendors pass `rail: 'tempo-mainnet'`
+ * to the directive builder and the SDK fills in method/network/decimals/currency from this
+ * registry. Custom rails not in this registry can be passed by setting the lower-level
+ * fields directly on the directive builder.
+ */
+declare const rails: {
+    readonly 'tempo-mainnet': {
+        readonly method: "tempo";
+        readonly network: "eip155:4217";
+        readonly chainId: 4217;
+        readonly currency: "0x20C000000000000000000000b9537d11c60E8b50";
+        readonly decimals: 6;
+        readonly asset: "0x20C000000000000000000000b9537d11c60E8b50";
+    };
+    readonly 'tempo-testnet': {
+        readonly method: "tempo";
+        readonly network: "eip155:42431";
+        readonly chainId: 42431;
+        readonly currency: "0x20c0000000000000000000000000000000000000";
+        readonly decimals: 6;
+        readonly asset: "0x20c0000000000000000000000000000000000000";
+    };
+    readonly 'x402-base-mainnet': {
+        readonly method: "x402";
+        readonly network: "eip155:8453";
+        readonly chainId: 8453;
+        readonly currency: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+        readonly decimals: 6;
+        readonly asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+    };
+    readonly 'x402-base-sepolia': {
+        readonly method: "x402";
+        readonly network: "eip155:84532";
+        readonly chainId: 84532;
+        readonly currency: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+        readonly decimals: 6;
+        readonly asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+    };
+    readonly 'x402-base-mainnet-upto': {
+        readonly method: "x402-upto";
+        readonly network: "eip155:8453";
+        readonly chainId: 8453;
+        readonly currency: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+        readonly decimals: 6;
+        readonly asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+    };
+    readonly 'x402-base-sepolia-upto': {
+        readonly method: "x402-upto";
+        readonly network: "eip155:84532";
+        readonly chainId: 84532;
+        readonly currency: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+        readonly decimals: 6;
+        readonly asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+    };
+    readonly 'x402-solana-mainnet': {
+        readonly method: "x402";
+        readonly network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+        readonly currency: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+        readonly decimals: 6;
+        readonly asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+    };
+    readonly 'x402-solana-devnet': {
+        readonly method: "x402";
+        readonly network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+        readonly currency: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
+        readonly decimals: 6;
+        readonly asset: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
+    };
+    readonly 'stripe-spt': {
+        readonly method: "stripe";
+        readonly currency: "usd";
+        readonly decimals: 2;
+    };
+};
+type RailName = keyof typeof rails;
+interface RailDefinition {
+    method: string;
+    network?: string;
+    chainId?: number;
+    currency: string;
+    decimals: number;
+    asset?: string;
+}
+/**
+ * Lookup a rail definition by symbolic name. Returns undefined if the rail isn't in
+ * the registry — vendors with custom rails should pass the low-level fields directly.
+ */
+declare function lookupRail(name: string): RailDefinition | undefined;
+
+/**
+ * Generic x402 server interface. Different versions of @x402/core may expose different
+ * shapes; we only require register() and (optionally) registerV1().
+ */
+interface X402ServerLike {
+    register(network: string, scheme: unknown): void;
+    registerV1?(network: string, scheme: unknown): void;
+}
+/**
+ * Registers an x402 scheme on both v1 and v2 of the protocol.
+ *
+ * Why: the @x402/core HTTP parser hardcodes `x402Version === 1`, while the client's
+ * `.register()` defaults to v2. Without registering on both versions, a merchant
+ * emitting a v1 response gets "No client registered for x402 version: 1" even
+ * though the scheme handler is identical between versions. Every merchant trips
+ * on this; the helper hides the workaround.
+ */
+declare function registerX402SchemesV1V2(server: X402ServerLike, network: string, scheme: unknown): void;
+
+type X402SymbolicRail = 'x402-base-mainnet' | 'x402-base-sepolia' | 'x402-solana-mainnet' | 'x402-solana-devnet' | 'x402-base-mainnet-upto' | 'x402-base-sepolia-upto';
+type X402FacilitatorChoice = 'coinbase' | 'http' | unknown;
+interface CreateX402ServerOptions {
+    /**
+     * Facilitator selection:
+     * - 'coinbase' → Coinbase CDP facilitator (requires `@coinbase/x402` installed)
+     * - 'http' → HTTP-only public testnet facilitator
+     * - any object → custom facilitator instance, used directly
+     * - omitted → defaults to 'http'
+     */
+    facilitator?: X402FacilitatorChoice;
+    /**
+     * Symbolic rail names to register schemes for. Each gets v1+v2 dual-register applied.
+     * Requires the corresponding peer dep installed (`@x402/evm` for base, `@x402/svm` for solana).
+     */
+    rails?: X402SymbolicRail[];
+    /** Advanced: register custom {network, scheme} pairs (in addition to or instead of `rails`). */
+    schemes?: {
+        network: string;
+        scheme: unknown;
+    }[];
+    /** Register the Bazaar discovery extension. Requires `@x402/extensions` installed. */
+    bazaar?: boolean;
+    /** Initialize the server immediately (calls facilitator). Default true. */
+    initialize?: boolean;
+}
+/**
+ * Loose type for the x402 resource server. We name the methods commerce calls during
+ * setup; everything else (settlePayment, buildPaymentRequirements, processPaymentRequest,
+ * enrichExtensions, etc.) is callable via the index signature so vendor code can use the
+ * full @x402/core surface without us having to mirror every method signature.
+ */
+interface X402Server {
+    register(network: string, scheme: unknown): void;
+    registerV1?(network: string, scheme: unknown): void;
+    registerExtension(ext: unknown): void;
+    initialize(): Promise<void>;
+    [key: string]: any;
+}
+/**
+ * One-call x402 server setup. Resolves facilitator, constructs the server, registers
+ * schemes per network with v1+v2 dual-register, optionally adds the Bazaar extension,
+ * and initializes — replaces ~15 lines of boilerplate with a single config call.
+ *
+ * x402 packages are peer dependencies — vendors install only the schemes they use.
+ * Throws a guiding error if a required peer is missing.
+ *
+ *   const server = await createX402Server({
+ *     facilitator: 'coinbase',
+ *     rails: ['x402-base-mainnet', 'x402-solana-mainnet'],
+ *     bazaar: true,
+ *   });
+ */
+declare function createX402Server(opts?: CreateX402ServerOptions): Promise<X402Server>;
+
+/**
+ * `processX402Settle` — single-call x402 verify+settle for merchants.
+ *
+ * Wraps the four x402-server steps every x402-accepting merchant repeats:
+ *   1. `buildPaymentRequirements(resourceConfig)` — builds the requirement entries the
+ *      facilitator validates against
+ *   2. `enrichExtensions(extension, transportContext)` — folds in Bazaar (or other)
+ *      extensions for the verify step
+ *   3. `processPaymentRequest(payload, resourceConfig, resourceMeta, extensions)` —
+ *      runs verify against the facilitator
+ *   4. `settlePayment(payload, matchedRequirement)` — settles on-chain
+ *
+ * Returns a tagged result so the caller can map errors to merchant-shaped responses
+ * without owning the orchestration boilerplate.
+ */
+
+interface ProcessX402SettleInput {
+    /** The x402 server instance from `createX402Server`. */
+    x402Server: X402Server;
+    /** The verified x402 payload extracted from the X-Payment header. */
+    payload: unknown;
+    /** Resource configuration the facilitator validates against (network, price, payTo,
+     *  asset, maxTimeoutSeconds, etc.). Shape is x402-server-specific. */
+    resourceConfig: unknown;
+    /** Resource metadata exposed to the facilitator (URL, description, mime type). */
+    resourceMeta: {
+        url: string;
+        description: string;
+        mimeType: string;
+    };
+    /** Optional extension to enrich during verify (e.g. Bazaar). */
+    extension?: unknown;
+    /** Transport context for the extension enrich step. Defaults to `{ method: 'POST',
+     *  adapter: { getPath: () => new URL(resourceMeta.url).pathname }, routePattern: <pathname> }`. */
+    transportContext?: unknown;
+}
+type ProcessX402SettleResult = {
+    success: true;
+    /** The matched requirement passed to `settlePayment`. */
+    matchedRequirement: unknown;
+    /** The settlement response from the facilitator. */
+    settleResult: unknown;
+    /** Base64-encoded JSON of `settleResult`, ready to set as the `payment-response`
+     *  HTTP header on the merchant's success response. x402 clients (`@x402/fetch`,
+     *  `agentscore-pay`) read this to confirm settlement landed. `undefined` when
+     *  there's no settle result (shouldn't happen on success path but typed defensively). */
+    paymentResponseHeader: string | undefined;
+    /** The x402 server's `processPaymentRequest` verify result. */
+    verifyResult: {
+        success: true;
+        [key: string]: unknown;
+    };
+} | {
+    success: false;
+    phase: 'no_requirements';
+    reason: string;
+} | {
+    success: false;
+    phase: 'verify_failed';
+    verifyResult: unknown;
+} | {
+    success: false;
+    phase: 'settle_failed';
+    error: unknown;
+    matchedRequirement: unknown;
+};
+declare function processX402Settle(input: ProcessX402SettleInput): Promise<ProcessX402SettleResult>;
+
+/**
+ * x402 boot-time + per-request validation helpers.
+ *
+ * Two layers of validation every x402-accepting merchant repeats:
+ *
+ *   - **Boot-time**: validate the configured `X402_BASE_NETWORK` + `X402_SVM_NETWORK`
+ *     env vars are in the supported set, and aren't pointing at the same network
+ *     family. Failing loud at boot is much better than per-request "unsupported
+ *     network" errors after a misconfigured deploy.
+ *
+ *   - **Per-request**: when an x402 X-Payment header arrives, parse the base64
+ *     payload, extract the signed network + payTo, validate against the merchant's
+ *     accepted networks, validate the payTo address shape per network family, and
+ *     check that the payTo was minted by THIS merchant (cache hit). Each step has
+ *     its own denial code and `next_steps` shape — getting the message right by
+ *     hand across 4 conditions is fiddly.
+ */
+/** CAIP-2 networks the commerce SDK supports for x402 Base (EVM USDC). */
+declare const X402_SUPPORTED_BASE_NETWORKS: Set<string>;
+/** CAIP-2 networks the commerce SDK supports for x402 Solana (SPL Token USDC). */
+declare const X402_SUPPORTED_SVM_NETWORKS: Set<string>;
+interface ValidateX402NetworkConfigInput {
+    /** CAIP-2 base network string (e.g. `'eip155:8453'`). */
+    baseNetwork: string;
+    /** CAIP-2 SVM network string (e.g. `'solana:5eykt…'`). */
+    svmNetwork: string;
+}
+/**
+ * Boot-time guard: throws if either network isn't supported, or if both point at the
+ * same family (which would silently route Solana payments to the Base path or vice
+ * versa). Call once at module init / server boot.
+ *
+ * Throws `Error` with a message that names the unsupported value AND lists the valid
+ * options — agents tracking down a misconfigured deploy don't need to grep for the
+ * supported list.
+ */
+declare function validateX402NetworkConfig(input: ValidateX402NetworkConfigInput): void;
+interface VerifyX402RequestInput {
+    /** The incoming Request — `verifyX402Request` reads the X-Payment / payment-signature header. */
+    request: Request;
+    /** Async lookup that returns true when the address was minted by this merchant
+     *  (typically `piCache.hasAddress`). The cache check defends against agents replaying
+     *  credentials against attacker-controlled deposit addresses. */
+    isCachedAddress: (address: string) => Promise<boolean>;
+    /** The merchant's accepted networks per family. Both required — pass the same env
+     *  values you fed to `validateX402NetworkConfig`. */
+    acceptedNetworks: {
+        /** CAIP-2 base network — e.g. `'eip155:8453'`. */
+        base: string;
+        /** CAIP-2 SVM network — e.g. `'solana:5eykt…'`. */
+        svm: string;
+    };
+}
+type VerifyX402RequestResult = {
+    ok: true;
+    /** The base64-decoded JSON payload from the X-Payment header. */
+    payload: {
+        accepted?: {
+            network?: string;
+            payTo?: string;
+        };
+        [key: string]: unknown;
+    };
+    /** The CAIP-2 network the agent signed for. */
+    signedNetwork: string;
+    /** The on-chain pay-to address the agent signed for (already validated). */
+    signedPayTo: string;
+    /** True when the signed network is Solana — useful for routing settlement. */
+    isSolana: boolean;
+} | {
+    ok: false;
+    /** Suitable as a JSON body for the merchant's denial response. Includes
+     *  `next_steps` with `regenerate_payment_credential` action + a per-condition
+     *  `user_message` and a footgun `warning` so agents can recover deterministically
+     *  from the response alone. */
+    body: {
+        error: {
+            code: string;
+            message: string;
+        };
+        next_steps: {
+            action: 'regenerate_payment_credential';
+            user_message: string;
+            warning: string;
+        };
+    };
+    /** HTTP status to use for the denial response. */
+    status: 400;
+};
+/**
+ * Per-request: parse the x402 X-Payment header, validate the network + payTo, and
+ * confirm the address was minted by this merchant. One call replaces ~45 lines of
+ * inline header decode + regex validation + cache lookup.
+ *
+ * Returns `{ok: true, payload, signedNetwork, signedPayTo, isSolana}` when valid; the
+ * caller passes `payload` straight into `processX402Settle`.
+ *
+ * Returns `{ok: false, body, status}` when invalid — the merchant just does
+ * `return c.json(body, status)` (or framework equivalent).
+ *
+ * Reads the header from `payment-signature` first, falling back to `x-payment` (both
+ * are in the wild as the binary-friendly transport name evolved).
+ */
+declare function verifyX402Request(input: VerifyX402RequestInput): Promise<VerifyX402RequestResult>;
+
+interface CreateMppxServerOptions {
+    /** Symbolic rail config — commerce wires the boilerplate (tempo.charge, mppStripe.charge, etc.). */
+    rails?: {
+        /** One-shot Tempo USDC charge (intent: 'charge'). */
+        tempo?: {
+            recipient: string;
+            /** Custom currency token. Default: USDC on Tempo. */
+            currency?: string;
+            /** Use Tempo testnet (Moderato). Default false. */
+            testnet?: boolean;
+        };
+        /**
+         * Tempo session (intent: 'session') — pay-as-you-go channel for repeated calls or
+         * SSE-streamed responses. Vendor brings their own ChannelStore (DB-backed implementation
+         * tracking open channels + voucher state) and an `escrowContract` address.
+         */
+        tempo_session?: {
+            recipient: string;
+            currency?: string;
+            testnet?: boolean;
+            /**
+             * On-chain escrow contract address that holds channel deposits and pays out
+             * cumulative vouchers on settlement. Vendor-deployed.
+             */
+            escrowContract: string;
+            /**
+             * Channel store implementation tracking open channels + cumulative voucher state.
+             * Pass an instance of mppx's `ChannelStore` interface (you can use the in-memory
+             * default for dev or implement a Postgres/Redis-backed store for production).
+             */
+            store: unknown;
+            /** Optional supported chains; defaults to mppx defaults. */
+            chains?: unknown;
+        };
+        /** Stripe SPT (Shared Payment Token) — see also @agent-score/commerce/stripe-multichain. */
+        stripe?: {
+            profileId: string;
+            secretKey: string;
+            paymentMethodTypes?: string[];
+        };
+    };
+    /** Advanced: pass mppx method instances directly (in addition to or instead of `rails`). */
+    methods?: unknown[];
+    /** MPP secret key (merchant's). */
+    secretKey: string;
+}
+/**
+ * One-call mppx server setup. Wires `tempo.charge(...)`, `tempo.session(...)`, and Stripe SPT
+ * (via createMppxStripe) from symbolic rail config, replacing the boilerplate of constructing
+ * each method by hand.
+ *
+ *   const mppx = await createMppxServer({
+ *     rails: {
+ *       tempo: { recipient: TEMPO_ADDR, testnet: false },             // intent: 'charge'
+ *       tempo_session: {                                                // intent: 'session'
+ *         recipient: TEMPO_ADDR,
+ *         escrowContract: ESCROW_ADDR,
+ *         store: myChannelStore,
+ *       },
+ *       stripe: { profileId: STRIPE_PROFILE_ID, secretKey: STRIPE_SECRET_KEY },
+ *     },
+ *     secretKey: MPP_SECRET_KEY,
+ *   });
+ *
+ * `mppx` is an OPTIONAL peer dependency — install it only if you accept MPP rails.
+ */
+declare function createMppxServer(opts: CreateMppxServerOptions): Promise<unknown>;
+
+interface SettlementHandlers<TPayload, TResult> {
+    evm?: (payload: TPayload) => TResult | Promise<TResult>;
+    svm?: (payload: TPayload) => TResult | Promise<TResult>;
+}
+interface SettlementPayloadLike {
+    accepted: {
+        network: string;
+    };
+}
+/**
+ * Dispatches a settlement payload to the right network-family handler based on
+ * the CAIP-2 network string in `payload.accepted.network`:
+ *
+ *   - eip155:* → handlers.evm
+ *   - solana:* → handlers.svm
+ *
+ * Throws if the network is unrecognized or the matching handler is missing.
+ * Most vendors will register handlers for both rail families they accept.
+ */
+declare function dispatchSettlementByNetwork<TPayload extends SettlementPayloadLike, TResult>(payload: TPayload, handlers: SettlementHandlers<TPayload, TResult>): Promise<TResult>;
+
+/**
+ * Multi-rail payment header bundle — one call composes both `WWW-Authenticate` (the
+ * `paymentauth.org` Payment directives) and the standard x402 `PAYMENT-REQUIRED` header
+ * from a single rails declaration. Reduces ~10 lines of merchant boilerplate per 402
+ * response.
+ *
+ * Layered on top of `paymentDirective` / `wwwAuthenticateHeader` / `paymentRequiredHeader`
+ * — those primitives stay exposed for vendors who want full control.
+ */
+interface PaymentHeadersRail {
+    /** Symbolic rail name — `tempo-mainnet`, `x402-base-mainnet`, `stripe`, etc. */
+    rail: string;
+    /** Amount in USD as a number or string. */
+    amountUsd: string | number;
+    /** Recipient address (on-chain) — required for crypto rails. */
+    recipient?: string;
+    /** Stripe profile_id / network_id — required for `stripe` rail. */
+    networkId?: string;
+    /** EVM chain id override — usually inferred from rail. */
+    chainId?: number;
+    /** Token contract / currency override — usually inferred from rail. */
+    currency?: string;
+    /** Decimal precision override — usually inferred from rail (USDC=6, etc.). */
+    decimals?: number;
+    /** MPP method override — usually inferred from rail. */
+    method?: string;
+    /** MPP intent. Default `charge`. */
+    intent?: string;
+    /** ISO-8601 expiry. Default now + 5 min. */
+    expires?: string;
+}
+interface BuildPaymentHeadersInput {
+    /** Rails the merchant accepts on this 402. Each becomes one `Payment` directive. */
+    rails: PaymentHeadersRail[];
+    /** Order id used as the directive challenge id (per-rail it becomes `${orderId}-${rail}`). */
+    orderId: string;
+    /** Realm — the host of the merchant URL (e.g. `agents.merchant.example`). */
+    realm: string;
+    /**
+     * Optional x402 `accepts` array — included as the standard PAYMENT-REQUIRED header so
+     * x402 clients (`@x402/fetch`, `@x402/core` HTTPClient, `agentscore-pay`) can parse the
+     * base64-encoded JSON form instead of the WWW-Authenticate text directives. Pass
+     * `undefined` (or omit) to skip the PAYMENT-REQUIRED header.
+     */
+    x402?: {
+        accepts: unknown[];
+        version?: 1 | 2;
+        resource?: {
+            url: string;
+            mimeType?: string;
+        };
+    };
+}
+interface PaymentHeadersResult {
+    'www-authenticate': string;
+    'PAYMENT-REQUIRED'?: string;
+}
+/**
+ * Compose `WWW-Authenticate` (multi-directive) and `PAYMENT-REQUIRED` (x402 base64) headers
+ * from a single rails declaration. Returns an object suitable for spreading into a
+ * `Headers` constructor or the `headers` field of a `Response`.
+ *
+ * Example:
+ * ```ts
+ * const headers = buildPaymentHeaders({
+ *   orderId: 'ord_123',
+ *   realm: 'agents.merchant.example',
+ *   rails: [
+ *     { rail: 'tempo-mainnet', amountUsd: 25, recipient: TEMPO_ADDR },
+ *     { rail: 'x402-base-mainnet', amountUsd: 25, recipient: BASE_ADDR },
+ *     { rail: 'stripe', amountUsd: 25, networkId: STRIPE_PROFILE_ID },
+ *   ],
+ *   x402: { accepts: x402Accepts, version: 1 },
+ * });
+ * return new Response(JSON.stringify(body), { status: 402, headers });
+ * ```
+ */
+declare function buildPaymentHeaders(input: BuildPaymentHeadersInput): PaymentHeadersResult;
+
+/**
+ * Idempotency-key composition.
+ *
+ * Stable per-payment keys that retries of the same logical payment can reuse, so AgentScore's
+ * `/v1/credentials/wallets` capture endpoint dedupes correctly and the operator's
+ * `transaction_count` doesn't inflate.
+ *
+ * Convention (matches what martin-estate uses today):
+ *   1. Prefer the upstream payment-rail's stable identifier (Stripe PaymentIntent id, x402
+ *      tx hash) when one exists — those are already idempotent on their side.
+ *   2. Fall back to a synthesized `pi-{orderId}-{amountCents}` key when no upstream id is
+ *      available (e.g. pre-creation, or rails without a PI concept).
+ *   3. Server caps idempotency keys at 200 chars; this helper warns when that boundary is
+ *      crossed so a future caller doesn't silently get truncation collisions.
+ */
+interface BuildIdempotencyKeyInput {
+    /** Upstream rail's stable payment id — Stripe PaymentIntent id, x402 tx hash, etc. Wins when present. */
+    paymentIntentId?: string | null;
+    /** Order id — used to compose a fallback key when no paymentIntentId exists. */
+    orderId?: string | null;
+    /** Amount in cents (or smallest currency unit) — added to the fallback for extra collision resistance. */
+    amountCents?: number;
+    /** Optional extra prefix to namespace the key (e.g. `"refund"`, `"void"`). */
+    prefix?: string;
+}
+/**
+ * Compose a stable idempotency key for AgentScore wallet capture and other retry-safe POSTs.
+ *
+ * Returns `undefined` when no inputs are present (caller should treat as "no idempotency
+ * key — first attempt only", same shape as omitting the field entirely).
+ *
+ * Examples:
+ * ```ts
+ * buildIdempotencyKey({ paymentIntentId: 'pi_abc' });            // → 'pi_abc'
+ * buildIdempotencyKey({ orderId: 'ord_x', amountCents: 25000 }); // → 'pi-ord_x-25000'
+ * buildIdempotencyKey({ orderId: 'ord_x' });                     // → 'pi-ord_x'
+ * buildIdempotencyKey({ paymentIntentId: 'pi_abc', prefix: 'refund' }); // → 'refund-pi_abc'
+ * buildIdempotencyKey({});                                       // → undefined
+ * ```
+ */
+declare function buildIdempotencyKey(input: BuildIdempotencyKeyInput): string | undefined;
+
+/**
+ * x402 Settlement-Overrides header helpers — used with the `upto` scheme to specify the
+ * actual amount to charge after the work is done. The header is JSON-encoded and lives
+ * on the merchant's response; the facilitator settles for that amount instead of the
+ * advertised maximum.
+ *
+ * Per the x402 docs (https://docs.x402.org/getting-started/quickstart-for-sellers), the
+ * amount field accepts three formats:
+ *   - raw atomic units, e.g., '1000' for $0.001 USDC at 6 decimals
+ *   - percentage, e.g., '50%' of the authorized maximum
+ *   - dollar price, e.g., '$0.05' (converted to atomic via the network's default token)
+ */
+declare const SETTLEMENT_OVERRIDES_HEADER = "Settlement-Overrides";
+interface SettlementOverrides {
+    /** Raw atomic units, '<n>%' percentage, or '$X.YZ' dollar price. */
+    amount: string;
+}
+/**
+ * Build a `{ name, value }` pair for the x402 Settlement-Overrides header. Vendors
+ * set this on their response to direct the facilitator to settle for the actual amount
+ * (used in the upto scheme flow):
+ *
+ *   const { name, value } = settlementOverrideHeader({ amount: '1500' });
+ *   res.setHeader(name, value);  // Express
+ *   c.header(name, value);       // Hono
+ */
+declare function settlementOverrideHeader(overrides: SettlementOverrides): {
+    name: string;
+    value: string;
+};
+
+export { type BuildIdempotencyKeyInput, type BuildPaymentDirectiveInput, type BuildPaymentHeadersInput, type CreateMppxServerOptions, type CreateX402ServerOptions, type NetworkFamily, type PaymentDirectiveInput, type PaymentHeadersRail, type PaymentHeadersResult, type PaymentRequestInput, type ProcessX402SettleInput, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, USDC, type ValidateX402NetworkConfigInput, type VerifyX402RequestInput, type VerifyX402RequestResult, type X402FacilitatorChoice, type X402Server, type X402ServerLike, type X402SymbolicRail, X402_SUPPORTED_BASE_NETWORKS, X402_SUPPORTED_SVM_NETWORKS, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, createMppxServer, createX402Server, dispatchSettlementByNetwork, lookupRail, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request };