@axonfi/sdk 0.3.7 → 0.4.1

package/dist/index.d.cts

@@ -458,6 +458,12 @@ interface PayInput {
      * If set, `memo` is ignored for ref generation but still stored off-chain.
      */
     ref?: Hex;
+    /**
+     * Marks this payment as x402 bot-EOA funding. When true, the relayer
+     * records the flag for audit/context (e.g. "bot self-payment for x402").
+     * Does NOT bypass any policy checks — full pipeline still applies.
+     */
+    x402Funding?: boolean;
 }
 /**
  * Signed execute intent for DeFi protocol interactions.
@@ -612,7 +618,97 @@ interface AxonClientConfig {
      * Provide either this or `account`.
      */
     botPrivateKey?: Hex;
+    /** Override the relayer URL (defaults to https://relay.axonfi.xyz). */
+    relayerUrl?: string;
+}
+
+/** Resource descriptor from the x402 PAYMENT-REQUIRED header. */
+interface X402Resource {
+    /** URL of the resource being unlocked. */
+    url: string;
+    /** Human-readable description of the resource. */
+    description?: string;
+    /** MIME type of the resource. */
+    mimeType?: string;
+}
+/** A single payment option from the `accepts` array. */
+interface X402PaymentOption {
+    /** Recipient address (merchant). */
+    payTo: string;
+    /** Amount in token base units (string). */
+    amount: string;
+    /** Token contract address. */
+    asset: string;
+    /** CAIP-2 network identifier, e.g. "eip155:8453". */
+    network: string;
+    /** Settlement scheme: "exact" (EIP-3009) or "permit2". */
+    scheme?: string;
+    /** Additional option-specific fields. */
+    extra?: Record<string, unknown>;
+}
+/** Parsed x402 PAYMENT-REQUIRED response. */
+interface X402PaymentRequired {
+    /** x402 protocol version. */
+    x402Version: number;
+    /** Resource being unlocked. */
+    resource: X402Resource;
+    /** Accepted payment options. */
+    accepts: X402PaymentOption[];
+}
+/** Result of handlePaymentRequired — contains everything needed to retry the request. */
+interface X402HandleResult {
+    /** Base64-encoded JSON for the PAYMENT-SIGNATURE header. */
+    paymentSignature: string;
+    /** The payment option that was selected and funded. */
+    selectedOption: X402PaymentOption;
+    /** Axon payment result (txHash, requestId, etc.). */
+    fundingResult: {
+        requestId: string;
+        status: string;
+        txHash?: string;
+    };
 }
+/**
+ * Parse the PAYMENT-REQUIRED header value (base64 JSON).
+ *
+ * The x402 spec encodes the payment requirements as a base64-encoded JSON
+ * string in the response header.
+ */
+declare function parsePaymentRequired(headerValue: string): X402PaymentRequired;
+/**
+ * Parse a CAIP-2 network identifier to a numeric chain ID.
+ *
+ * @example parseChainId("eip155:8453") // → 8453
+ * @example parseChainId("eip155:84532") // → 84532
+ */
+declare function parseChainId(network: string): number;
+/**
+ * Find a payment option matching the bot's chain ID.
+ *
+ * Prefers USDC options (EIP-3009 path — no gas needed from bot).
+ * Falls back to any matching chain option.
+ *
+ * @returns The best matching payment option, or null if none match.
+ */
+declare function findMatchingOption(accepts: X402PaymentOption[], chainId: number): X402PaymentOption | null;
+/**
+ * Extract metadata fields from a parsed x402 header for payment enrichment.
+ *
+ * These fields flow into the Axon payment record, giving vault owners
+ * full visibility into what their bots are accessing.
+ */
+declare function extractX402Metadata(parsed: X402PaymentRequired, selectedOption: X402PaymentOption): {
+    resourceUrl: string;
+    memo: string | null;
+    recipientLabel: string | null;
+    metadata: Record<string, string>;
+};
+/**
+ * Format a payment signature payload for the PAYMENT-SIGNATURE header.
+ *
+ * The x402 spec requires the header value to be base64-encoded JSON.
+ */
+declare function formatPaymentSignature(payload: Record<string, unknown>): string;
 
 /**
  * Main entry point for bots interacting with Axon.
@@ -649,6 +745,7 @@ declare class AxonClient {
     private readonly chainId;
     private readonly relayerUrl;
     private readonly walletClient;
+    private readonly botPrivateKey;
     constructor(config: AxonClientConfig);
     /** Returns the bot's address derived from the configured private key. */
     get botAddress(): Address;
@@ -743,6 +840,57 @@ declare class AxonClient {
      * to another system (e.g. a custom relayer integration).
      */
     signPayment(intent: PaymentIntent): Promise<Hex>;
+    /**
+     * x402 utilities for handling HTTP 402 Payment Required responses.
+     *
+     * The x402 flow:
+     * 1. Bot hits an API that returns HTTP 402 + PAYMENT-REQUIRED header
+     * 2. SDK parses the header, finds a matching payment option
+     * 3. SDK funds the bot's EOA from the vault (full Axon pipeline applies)
+     * 4. Bot signs an EIP-3009 or Permit2 authorization
+     * 5. SDK returns a PAYMENT-SIGNATURE header for the bot to retry with
+     *
+     * @example
+     * ```ts
+     * const response = await fetch('https://api.example.com/data');
+     * if (response.status === 402) {
+     *   const result = await client.x402.handlePaymentRequired(response.headers);
+     *   const data = await fetch('https://api.example.com/data', {
+     *     headers: { 'PAYMENT-SIGNATURE': result.paymentSignature },
+     *   });
+     * }
+     * ```
+     */
+    readonly x402: {
+        /**
+         * Fund the bot's EOA from the vault for x402 settlement.
+         *
+         * This is a regular Axon payment (to = bot's own address) that goes through
+         * the full pipeline: policy engine, AI scan, human review if needed.
+         *
+         * @param amount - Amount in token base units
+         * @param token - Token address (defaults to USDC on this chain)
+         * @param metadata - Optional metadata for the payment record
+         */
+        fund: (amount: bigint, token?: Address, metadata?: {
+            resourceUrl?: string;
+            memo?: string;
+            recipientLabel?: string;
+            metadata?: Record<string, string>;
+        }) => Promise<PaymentResult>;
+        /**
+         * Handle a full x402 flow: parse header, fund bot, sign authorization, return header.
+         *
+         * Supports both EIP-3009 (USDC) and Permit2 (any ERC-20) settlement.
+         * The bot's EOA is funded from the vault first (full Axon pipeline applies).
+         *
+         * @param headers - Response headers from the 402 response (must contain PAYMENT-REQUIRED)
+         * @param maxTimeoutMs - Maximum time to wait for pending_review resolution (default: 120s)
+         * @param pollIntervalMs - Polling interval for pending_review (default: 5s)
+         * @returns Payment signature header value + funding details
+         */
+        handlePaymentRequired: (headers: Headers | Record<string, string>, maxTimeoutMs?: number, pollIntervalMs?: number) => Promise<X402HandleResult>;
+    };
     private _get;
     private _defaultDeadline;
     private _resolveRef;
@@ -939,6 +1087,94 @@ declare function resolveTokenDecimals(token: Address | Token | KnownTokenSymbol,
  */
 declare function parseAmount(amount: bigint | number | string, token: Address | Token | KnownTokenSymbol, chainId?: number): bigint;
 
+/**
+ * Per-chain EIP-712 domain parameters for USDC's EIP-3009 implementation.
+ * These differ between testnets and mainnets (Circle uses different `name` values).
+ *
+ * Verified on-chain via `cast call <usdc> "name()(string)"` and
+ * `cast call <usdc> "version()(string)"`.
+ */
+declare const USDC_EIP712_DOMAIN: Record<number, {
+    name: string;
+    version: string;
+}>;
+/** Parameters for EIP-3009 TransferWithAuthorization. */
+interface TransferAuthorization {
+    /** Token holder (sender). */
+    from: Address;
+    /** Recipient of the transfer. */
+    to: Address;
+    /** Amount in token base units (USDC: 6 decimals). */
+    value: bigint;
+    /** Unix timestamp — transfer is invalid before this time. Usually 0. */
+    validAfter: bigint;
+    /** Unix timestamp — transfer is invalid after this time. */
+    validBefore: bigint;
+    /** Random bytes32 nonce (must not have been used before for this sender). */
+    nonce: Hex;
+}
+/**
+ * Generate a random bytes32 nonce for EIP-3009.
+ * Uses crypto.getRandomValues for cryptographic randomness.
+ */
+declare function randomNonce(): Hex;
+/**
+ * Sign an EIP-3009 TransferWithAuthorization for USDC.
+ *
+ * The resulting signature can be submitted to a facilitator contract that calls
+ * `USDC.transferWithAuthorization(from, to, value, validAfter, validBefore, nonce, v, r, s)`.
+ *
+ * @param privateKey - Signer's private key (must match auth.from)
+ * @param chainId - Chain ID (determines USDC domain name/version)
+ * @param auth - Transfer authorization parameters
+ * @returns EIP-712 signature (65 bytes, 0x-prefixed)
+ */
+declare function signTransferWithAuthorization(privateKey: Hex, chainId: number, auth: TransferAuthorization): Promise<Hex>;
+
+/** Canonical Permit2 contract address (same on all EVM chains). */
+declare const PERMIT2_ADDRESS: Address;
+/** x402 facilitator proxy contract address (same on all supported chains). */
+declare const X402_PROXY_ADDRESS: Address;
+/**
+ * Witness type string for x402's PermitWitnessTransferFrom.
+ * Must match what the x402 facilitator contract expects.
+ */
+declare const WITNESS_TYPE_STRING: "TransferDetails witness)TokenPermissions(address token,uint256 amount)TransferDetails(address to,uint256 requestedAmount)";
+/** Parameters for Permit2 PermitWitnessTransferFrom. */
+interface Permit2Authorization {
+    /** Token to transfer. */
+    token: Address;
+    /** Maximum amount the spender can transfer. */
+    amount: bigint;
+    /** Spender address (the x402 proxy). */
+    spender: Address;
+    /** Unique nonce (random uint256). */
+    nonce: bigint;
+    /** Unix timestamp — signature is invalid after this time. */
+    deadline: bigint;
+    /** Witness: recipient address. */
+    witnessTo: Address;
+    /** Witness: requested amount. */
+    witnessRequestedAmount: bigint;
+}
+/**
+ * Generate a random uint256 nonce for Permit2.
+ * Uses crypto.getRandomValues for cryptographic randomness.
+ */
+declare function randomPermit2Nonce(): bigint;
+/**
+ * Sign a Permit2 PermitWitnessTransferFrom for x402.
+ *
+ * The resulting signature is submitted to the x402 facilitator proxy,
+ * which calls `Permit2.permitWitnessTransferFrom(...)` to settle the payment.
+ *
+ * @param privateKey - Signer's private key (token holder)
+ * @param chainId - Chain ID
+ * @param permit - Permit2 authorization parameters
+ * @returns EIP-712 signature (65 bytes, 0x-prefixed)
+ */
+declare function signPermit2WitnessTransfer(privateKey: Hex, chainId: number, permit: Permit2Authorization): Promise<Hex>;
+
 declare const AxonVaultAbi: readonly [{
     readonly type: "constructor";
     readonly inputs: readonly [{
@@ -3017,4 +3253,4 @@ declare const AxonRegistryAbi: readonly [{
     readonly inputs: readonly [];
 }];
 
-export { type AmountInput, AxonClient, type AxonClientConfig, AxonRegistryAbi, AxonVaultAbi, AxonVaultFactoryAbi, type BotConfig, type BotConfigParams, CHAIN_NAMES, Chain, DEFAULT_DEADLINE_SECONDS, type DestinationCheckResult, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, EXECUTE_INTENT_TYPEHASH, EXPLORER_ADDR, EXPLORER_TX, type ExecuteInput, type ExecuteIntent, KNOWN_TOKENS, type KeystoreV3, type KnownToken, type KnownTokenSymbol, NATIVE_ETH, type OperatorCeilings, PAYMENT_INTENT_TYPEHASH, type PayInput, PaymentErrorCode, type PaymentIntent, type PaymentResult, type PaymentStatus, RELAYER_API, type RebalanceTokensResult, SUPPORTED_CHAIN_IDS, SWAP_INTENT_TYPEHASH, type SpendingLimit, type SupportedChainId, type SwapInput, type SwapIntent, Token, type TokenInput, type TosStatus, USDC, type VaultInfo, WINDOW, createAxonPublicClient, createAxonWalletClient, decryptKeystore, deployVault, encodeRef, encryptKeystore, getBotConfig, getChain, getDomainSeparator, getKnownTokensForChain, getOperatorCeilings, getRebalanceTokenCount, getTokenSymbolByAddress, getVaultOperator, getVaultOwner, getVaultVersion, isBotActive, isDestinationAllowed, isRebalanceTokenWhitelisted, isVaultPaused, operatorMaxDrainPerDay, parseAmount, resolveToken, resolveTokenDecimals, signExecuteIntent, signPayment, signSwapIntent };
+export { type AmountInput, AxonClient, type AxonClientConfig, AxonRegistryAbi, AxonVaultAbi, AxonVaultFactoryAbi, type BotConfig, type BotConfigParams, CHAIN_NAMES, Chain, DEFAULT_DEADLINE_SECONDS, type DestinationCheckResult, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, EXECUTE_INTENT_TYPEHASH, EXPLORER_ADDR, EXPLORER_TX, type ExecuteInput, type ExecuteIntent, KNOWN_TOKENS, type KeystoreV3, type KnownToken, type KnownTokenSymbol, NATIVE_ETH, type OperatorCeilings, PAYMENT_INTENT_TYPEHASH, PERMIT2_ADDRESS, type PayInput, PaymentErrorCode, type PaymentIntent, type PaymentResult, type PaymentStatus, type Permit2Authorization, RELAYER_API, type RebalanceTokensResult, SUPPORTED_CHAIN_IDS, SWAP_INTENT_TYPEHASH, type SpendingLimit, type SupportedChainId, type SwapInput, type SwapIntent, Token, type TokenInput, type TosStatus, type TransferAuthorization, USDC, USDC_EIP712_DOMAIN, type VaultInfo, WINDOW, WITNESS_TYPE_STRING, type X402HandleResult, type X402PaymentOption, type X402PaymentRequired, type X402Resource, X402_PROXY_ADDRESS, createAxonPublicClient, createAxonWalletClient, decryptKeystore, deployVault, encodeRef, encryptKeystore, extractX402Metadata, findMatchingOption, formatPaymentSignature, getBotConfig, getChain, getDomainSeparator, getKnownTokensForChain, getOperatorCeilings, getRebalanceTokenCount, getTokenSymbolByAddress, getVaultOperator, getVaultOwner, getVaultVersion, isBotActive, isDestinationAllowed, isRebalanceTokenWhitelisted, isVaultPaused, operatorMaxDrainPerDay, parseAmount, parseChainId, parsePaymentRequired, randomNonce, randomPermit2Nonce, resolveToken, resolveTokenDecimals, signExecuteIntent, signPayment, signPermit2WitnessTransfer, signSwapIntent, signTransferWithAuthorization };

package/dist/index.d.ts

@@ -458,6 +458,12 @@ interface PayInput {
      * If set, `memo` is ignored for ref generation but still stored off-chain.
      */
     ref?: Hex;
+    /**
+     * Marks this payment as x402 bot-EOA funding. When true, the relayer
+     * records the flag for audit/context (e.g. "bot self-payment for x402").
+     * Does NOT bypass any policy checks — full pipeline still applies.
+     */
+    x402Funding?: boolean;
 }
 /**
  * Signed execute intent for DeFi protocol interactions.
@@ -612,7 +618,97 @@ interface AxonClientConfig {
      * Provide either this or `account`.
      */
     botPrivateKey?: Hex;
+    /** Override the relayer URL (defaults to https://relay.axonfi.xyz). */
+    relayerUrl?: string;
+}
+
+/** Resource descriptor from the x402 PAYMENT-REQUIRED header. */
+interface X402Resource {
+    /** URL of the resource being unlocked. */
+    url: string;
+    /** Human-readable description of the resource. */
+    description?: string;
+    /** MIME type of the resource. */
+    mimeType?: string;
+}
+/** A single payment option from the `accepts` array. */
+interface X402PaymentOption {
+    /** Recipient address (merchant). */
+    payTo: string;
+    /** Amount in token base units (string). */
+    amount: string;
+    /** Token contract address. */
+    asset: string;
+    /** CAIP-2 network identifier, e.g. "eip155:8453". */
+    network: string;
+    /** Settlement scheme: "exact" (EIP-3009) or "permit2". */
+    scheme?: string;
+    /** Additional option-specific fields. */
+    extra?: Record<string, unknown>;
+}
+/** Parsed x402 PAYMENT-REQUIRED response. */
+interface X402PaymentRequired {
+    /** x402 protocol version. */
+    x402Version: number;
+    /** Resource being unlocked. */
+    resource: X402Resource;
+    /** Accepted payment options. */
+    accepts: X402PaymentOption[];
+}
+/** Result of handlePaymentRequired — contains everything needed to retry the request. */
+interface X402HandleResult {
+    /** Base64-encoded JSON for the PAYMENT-SIGNATURE header. */
+    paymentSignature: string;
+    /** The payment option that was selected and funded. */
+    selectedOption: X402PaymentOption;
+    /** Axon payment result (txHash, requestId, etc.). */
+    fundingResult: {
+        requestId: string;
+        status: string;
+        txHash?: string;
+    };
 }
+/**
+ * Parse the PAYMENT-REQUIRED header value (base64 JSON).
+ *
+ * The x402 spec encodes the payment requirements as a base64-encoded JSON
+ * string in the response header.
+ */
+declare function parsePaymentRequired(headerValue: string): X402PaymentRequired;
+/**
+ * Parse a CAIP-2 network identifier to a numeric chain ID.
+ *
+ * @example parseChainId("eip155:8453") // → 8453
+ * @example parseChainId("eip155:84532") // → 84532
+ */
+declare function parseChainId(network: string): number;
+/**
+ * Find a payment option matching the bot's chain ID.
+ *
+ * Prefers USDC options (EIP-3009 path — no gas needed from bot).
+ * Falls back to any matching chain option.
+ *
+ * @returns The best matching payment option, or null if none match.
+ */
+declare function findMatchingOption(accepts: X402PaymentOption[], chainId: number): X402PaymentOption | null;
+/**
+ * Extract metadata fields from a parsed x402 header for payment enrichment.
+ *
+ * These fields flow into the Axon payment record, giving vault owners
+ * full visibility into what their bots are accessing.
+ */
+declare function extractX402Metadata(parsed: X402PaymentRequired, selectedOption: X402PaymentOption): {
+    resourceUrl: string;
+    memo: string | null;
+    recipientLabel: string | null;
+    metadata: Record<string, string>;
+};
+/**
+ * Format a payment signature payload for the PAYMENT-SIGNATURE header.
+ *
+ * The x402 spec requires the header value to be base64-encoded JSON.
+ */
+declare function formatPaymentSignature(payload: Record<string, unknown>): string;
 
 /**
  * Main entry point for bots interacting with Axon.
@@ -649,6 +745,7 @@ declare class AxonClient {
     private readonly chainId;
     private readonly relayerUrl;
     private readonly walletClient;
+    private readonly botPrivateKey;
     constructor(config: AxonClientConfig);
     /** Returns the bot's address derived from the configured private key. */
     get botAddress(): Address;
@@ -743,6 +840,57 @@ declare class AxonClient {
      * to another system (e.g. a custom relayer integration).
      */
     signPayment(intent: PaymentIntent): Promise<Hex>;
+    /**
+     * x402 utilities for handling HTTP 402 Payment Required responses.
+     *
+     * The x402 flow:
+     * 1. Bot hits an API that returns HTTP 402 + PAYMENT-REQUIRED header
+     * 2. SDK parses the header, finds a matching payment option
+     * 3. SDK funds the bot's EOA from the vault (full Axon pipeline applies)
+     * 4. Bot signs an EIP-3009 or Permit2 authorization
+     * 5. SDK returns a PAYMENT-SIGNATURE header for the bot to retry with
+     *
+     * @example
+     * ```ts
+     * const response = await fetch('https://api.example.com/data');
+     * if (response.status === 402) {
+     *   const result = await client.x402.handlePaymentRequired(response.headers);
+     *   const data = await fetch('https://api.example.com/data', {
+     *     headers: { 'PAYMENT-SIGNATURE': result.paymentSignature },
+     *   });
+     * }
+     * ```
+     */
+    readonly x402: {
+        /**
+         * Fund the bot's EOA from the vault for x402 settlement.
+         *
+         * This is a regular Axon payment (to = bot's own address) that goes through
+         * the full pipeline: policy engine, AI scan, human review if needed.
+         *
+         * @param amount - Amount in token base units
+         * @param token - Token address (defaults to USDC on this chain)
+         * @param metadata - Optional metadata for the payment record
+         */
+        fund: (amount: bigint, token?: Address, metadata?: {
+            resourceUrl?: string;
+            memo?: string;
+            recipientLabel?: string;
+            metadata?: Record<string, string>;
+        }) => Promise<PaymentResult>;
+        /**
+         * Handle a full x402 flow: parse header, fund bot, sign authorization, return header.
+         *
+         * Supports both EIP-3009 (USDC) and Permit2 (any ERC-20) settlement.
+         * The bot's EOA is funded from the vault first (full Axon pipeline applies).
+         *
+         * @param headers - Response headers from the 402 response (must contain PAYMENT-REQUIRED)
+         * @param maxTimeoutMs - Maximum time to wait for pending_review resolution (default: 120s)
+         * @param pollIntervalMs - Polling interval for pending_review (default: 5s)
+         * @returns Payment signature header value + funding details
+         */
+        handlePaymentRequired: (headers: Headers | Record<string, string>, maxTimeoutMs?: number, pollIntervalMs?: number) => Promise<X402HandleResult>;
+    };
     private _get;
     private _defaultDeadline;
     private _resolveRef;
@@ -939,6 +1087,94 @@ declare function resolveTokenDecimals(token: Address | Token | KnownTokenSymbol,
  */
 declare function parseAmount(amount: bigint | number | string, token: Address | Token | KnownTokenSymbol, chainId?: number): bigint;
 
+/**
+ * Per-chain EIP-712 domain parameters for USDC's EIP-3009 implementation.
+ * These differ between testnets and mainnets (Circle uses different `name` values).
+ *
+ * Verified on-chain via `cast call <usdc> "name()(string)"` and
+ * `cast call <usdc> "version()(string)"`.
+ */
+declare const USDC_EIP712_DOMAIN: Record<number, {
+    name: string;
+    version: string;
+}>;
+/** Parameters for EIP-3009 TransferWithAuthorization. */
+interface TransferAuthorization {
+    /** Token holder (sender). */
+    from: Address;
+    /** Recipient of the transfer. */
+    to: Address;
+    /** Amount in token base units (USDC: 6 decimals). */
+    value: bigint;
+    /** Unix timestamp — transfer is invalid before this time. Usually 0. */
+    validAfter: bigint;
+    /** Unix timestamp — transfer is invalid after this time. */
+    validBefore: bigint;
+    /** Random bytes32 nonce (must not have been used before for this sender). */
+    nonce: Hex;
+}
+/**
+ * Generate a random bytes32 nonce for EIP-3009.
+ * Uses crypto.getRandomValues for cryptographic randomness.
+ */
+declare function randomNonce(): Hex;
+/**
+ * Sign an EIP-3009 TransferWithAuthorization for USDC.
+ *
+ * The resulting signature can be submitted to a facilitator contract that calls
+ * `USDC.transferWithAuthorization(from, to, value, validAfter, validBefore, nonce, v, r, s)`.
+ *
+ * @param privateKey - Signer's private key (must match auth.from)
+ * @param chainId - Chain ID (determines USDC domain name/version)
+ * @param auth - Transfer authorization parameters
+ * @returns EIP-712 signature (65 bytes, 0x-prefixed)
+ */
+declare function signTransferWithAuthorization(privateKey: Hex, chainId: number, auth: TransferAuthorization): Promise<Hex>;
+
+/** Canonical Permit2 contract address (same on all EVM chains). */
+declare const PERMIT2_ADDRESS: Address;
+/** x402 facilitator proxy contract address (same on all supported chains). */
+declare const X402_PROXY_ADDRESS: Address;
+/**
+ * Witness type string for x402's PermitWitnessTransferFrom.
+ * Must match what the x402 facilitator contract expects.
+ */
+declare const WITNESS_TYPE_STRING: "TransferDetails witness)TokenPermissions(address token,uint256 amount)TransferDetails(address to,uint256 requestedAmount)";
+/** Parameters for Permit2 PermitWitnessTransferFrom. */
+interface Permit2Authorization {
+    /** Token to transfer. */
+    token: Address;
+    /** Maximum amount the spender can transfer. */
+    amount: bigint;
+    /** Spender address (the x402 proxy). */
+    spender: Address;
+    /** Unique nonce (random uint256). */
+    nonce: bigint;
+    /** Unix timestamp — signature is invalid after this time. */
+    deadline: bigint;
+    /** Witness: recipient address. */
+    witnessTo: Address;
+    /** Witness: requested amount. */
+    witnessRequestedAmount: bigint;
+}
+/**
+ * Generate a random uint256 nonce for Permit2.
+ * Uses crypto.getRandomValues for cryptographic randomness.
+ */
+declare function randomPermit2Nonce(): bigint;
+/**
+ * Sign a Permit2 PermitWitnessTransferFrom for x402.
+ *
+ * The resulting signature is submitted to the x402 facilitator proxy,
+ * which calls `Permit2.permitWitnessTransferFrom(...)` to settle the payment.
+ *
+ * @param privateKey - Signer's private key (token holder)
+ * @param chainId - Chain ID
+ * @param permit - Permit2 authorization parameters
+ * @returns EIP-712 signature (65 bytes, 0x-prefixed)
+ */
+declare function signPermit2WitnessTransfer(privateKey: Hex, chainId: number, permit: Permit2Authorization): Promise<Hex>;
+
 declare const AxonVaultAbi: readonly [{
     readonly type: "constructor";
     readonly inputs: readonly [{
@@ -3017,4 +3253,4 @@ declare const AxonRegistryAbi: readonly [{
     readonly inputs: readonly [];
 }];
 
-export { type AmountInput, AxonClient, type AxonClientConfig, AxonRegistryAbi, AxonVaultAbi, AxonVaultFactoryAbi, type BotConfig, type BotConfigParams, CHAIN_NAMES, Chain, DEFAULT_DEADLINE_SECONDS, type DestinationCheckResult, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, EXECUTE_INTENT_TYPEHASH, EXPLORER_ADDR, EXPLORER_TX, type ExecuteInput, type ExecuteIntent, KNOWN_TOKENS, type KeystoreV3, type KnownToken, type KnownTokenSymbol, NATIVE_ETH, type OperatorCeilings, PAYMENT_INTENT_TYPEHASH, type PayInput, PaymentErrorCode, type PaymentIntent, type PaymentResult, type PaymentStatus, RELAYER_API, type RebalanceTokensResult, SUPPORTED_CHAIN_IDS, SWAP_INTENT_TYPEHASH, type SpendingLimit, type SupportedChainId, type SwapInput, type SwapIntent, Token, type TokenInput, type TosStatus, USDC, type VaultInfo, WINDOW, createAxonPublicClient, createAxonWalletClient, decryptKeystore, deployVault, encodeRef, encryptKeystore, getBotConfig, getChain, getDomainSeparator, getKnownTokensForChain, getOperatorCeilings, getRebalanceTokenCount, getTokenSymbolByAddress, getVaultOperator, getVaultOwner, getVaultVersion, isBotActive, isDestinationAllowed, isRebalanceTokenWhitelisted, isVaultPaused, operatorMaxDrainPerDay, parseAmount, resolveToken, resolveTokenDecimals, signExecuteIntent, signPayment, signSwapIntent };
+export { type AmountInput, AxonClient, type AxonClientConfig, AxonRegistryAbi, AxonVaultAbi, AxonVaultFactoryAbi, type BotConfig, type BotConfigParams, CHAIN_NAMES, Chain, DEFAULT_DEADLINE_SECONDS, type DestinationCheckResult, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, EXECUTE_INTENT_TYPEHASH, EXPLORER_ADDR, EXPLORER_TX, type ExecuteInput, type ExecuteIntent, KNOWN_TOKENS, type KeystoreV3, type KnownToken, type KnownTokenSymbol, NATIVE_ETH, type OperatorCeilings, PAYMENT_INTENT_TYPEHASH, PERMIT2_ADDRESS, type PayInput, PaymentErrorCode, type PaymentIntent, type PaymentResult, type PaymentStatus, type Permit2Authorization, RELAYER_API, type RebalanceTokensResult, SUPPORTED_CHAIN_IDS, SWAP_INTENT_TYPEHASH, type SpendingLimit, type SupportedChainId, type SwapInput, type SwapIntent, Token, type TokenInput, type TosStatus, type TransferAuthorization, USDC, USDC_EIP712_DOMAIN, type VaultInfo, WINDOW, WITNESS_TYPE_STRING, type X402HandleResult, type X402PaymentOption, type X402PaymentRequired, type X402Resource, X402_PROXY_ADDRESS, createAxonPublicClient, createAxonWalletClient, decryptKeystore, deployVault, encodeRef, encryptKeystore, extractX402Metadata, findMatchingOption, formatPaymentSignature, getBotConfig, getChain, getDomainSeparator, getKnownTokensForChain, getOperatorCeilings, getRebalanceTokenCount, getTokenSymbolByAddress, getVaultOperator, getVaultOwner, getVaultVersion, isBotActive, isDestinationAllowed, isRebalanceTokenWhitelisted, isVaultPaused, operatorMaxDrainPerDay, parseAmount, parseChainId, parsePaymentRequired, randomNonce, randomPermit2Nonce, resolveToken, resolveTokenDecimals, signExecuteIntent, signPayment, signPermit2WitnessTransfer, signSwapIntent, signTransferWithAuthorization };