@dcentralab/d402-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,859 @@
+import { Account } from 'viem/accounts';
+import { Hash } from 'viem';
+
+/**
+ * Type definitions for D402 payment protocol
+ */
+
+/**
+ * Supported blockchain networks
+ */
+type SupportedNetwork = 'mainnet' | 'sepolia' | 'base' | 'polygon';
+/**
+ * D402 Client configuration
+ */
+interface D402Config {
+    /** Viem account for signing payments */
+    account: Account;
+    /** Blockchain network */
+    network: SupportedNetwork;
+    /** Maximum payment amount in wei (smallest token unit) */
+    maxPaymentAmount: bigint;
+    /** Token contract address (defaults to USDC if not provided) */
+    tokenAddress?: `0x${string}`;
+    /** Payment validity window in seconds (default: 300) */
+    validityWindowSeconds?: number;
+}
+/**
+ * EIP-712 domain for signature verification
+ */
+interface EIP712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+}
+/**
+ * Payment requirement from 402 response
+ *
+ * Matches Python: PaymentRequirements (types.py lines 97-108)
+ */
+interface PaymentRequirement {
+    /** D402 protocol version */
+    d402Version?: number;
+    /** Payment scheme (exact or range) */
+    scheme: 'exact' | 'range';
+    /** Network identifier */
+    network: string;
+    /** Maximum amount required (in wei/smallest unit) */
+    maxAmountRequired: string;
+    /** Recipient address */
+    payTo: `0x${string}`;
+    /** Token contract address */
+    asset: `0x${string}`;
+    /** Resource identifier (API path) */
+    resource?: string;
+    /** Description of the service */
+    description?: string;
+    /** MIME type of response */
+    mimeType?: string;
+    /** Output schema definition */
+    outputSchema?: any;
+    /** Maximum timeout in seconds */
+    maxTimeoutSeconds?: number;
+    /** Additional EIP-712 domain info */
+    extra?: {
+        name: string;
+        version: string;
+        chainId: number;
+    };
+}
+/**
+ * Payment authorization details
+ */
+interface PaymentAuthorization {
+    /** Sender address */
+    from: `0x${string}`;
+    /** Recipient address */
+    to: `0x${string}`;
+    /** Payment amount (wei/smallest unit) */
+    value: string;
+    /** Valid after timestamp */
+    validAfter: string;
+    /** Valid before timestamp */
+    validBefore: string;
+    /** Unique nonce */
+    nonce: `0x${string}`;
+    /** Request path/resource */
+    requestPath: string;
+}
+/**
+ * Signed payment ready to send
+ */
+interface SignedPayment {
+    /** D402 protocol version */
+    d402Version: number;
+    /** Payment scheme */
+    scheme: string;
+    /** Network identifier */
+    network: string;
+    /** Payment payload */
+    payload: {
+        /** EIP-712 signature */
+        signature: `0x${string}`;
+        /** Authorization details */
+        authorization: PaymentAuthorization;
+    };
+}
+
+/**
+ * Payment requirements selection logic
+ */
+
+/**
+ * Options for selecting payment requirements
+ */
+interface PaymentSelectorOptions {
+    /** Filter by network (e.g., "base-mainnet") */
+    network?: string;
+    /** Filter by payment scheme (default: "exact") */
+    scheme?: string;
+    /** Maximum allowed payment amount in base units */
+    maxAmount?: bigint;
+    /** Preferred network (will try this first) */
+    preferredNetwork?: string;
+    /** Preferred token address */
+    preferredToken?: string;
+}
+/**
+ * Select payment requirement from a list based on filters and preferences
+ *
+ * This function implements the same logic as Python's default_payment_requirements_selector
+ *
+ * @param requirements - List of accepted payment requirements from 402 response
+ * @param options - Selection options and filters
+ * @returns Selected payment requirement
+ *
+ * @throws {UnsupportedSchemeError} If no matching scheme found
+ * @throws {PaymentAmountExceededError} If payment exceeds max amount
+ *
+ * @example
+ * const selected = selectPaymentRequirement(requirements, {
+ *   scheme: 'exact',
+ *   network: 'base-mainnet',
+ *   maxAmount: 1000000n
+ * })
+ */
+declare function selectPaymentRequirement(requirements: PaymentRequirement[], options?: PaymentSelectorOptions): PaymentRequirement;
+/**
+ * Custom payment selector function type
+ */
+type PaymentSelector = (requirements: PaymentRequirement[], options?: PaymentSelectorOptions) => PaymentRequirement;
+/**
+ * Create a custom payment selector with default options
+ *
+ * @param defaultOptions - Default options to apply
+ * @returns Custom selector function
+ *
+ * @example
+ * const selector = createPaymentSelector({
+ *   preferredNetwork: 'base-mainnet',
+ *   maxAmount: 1000000n
+ * })
+ *
+ * const selected = selector(requirements, { scheme: 'exact' })
+ */
+declare function createPaymentSelector(defaultOptions: PaymentSelectorOptions): PaymentSelector;
+/**
+ * Sort payment requirements by preference
+ * Useful for UI display or debugging
+ *
+ * @param requirements - List of requirements
+ * @param preferredNetwork - Preferred network name
+ * @returns Sorted list (preferred first)
+ */
+declare function sortPaymentRequirements(requirements: PaymentRequirement[], preferredNetwork?: string): PaymentRequirement[];
+
+/**
+ * D402 Client - Main client class for handling HTTP 402 payments
+ *
+ * Matches Python implementation: IATP/src/traia_iatp/d402/clients/base.py d402Client
+ */
+
+/**
+ * D402 Client configuration.
+ *
+ * Matches Python: d402Client.__init__ parameters (base.py lines 66-72)
+ */
+interface D402ClientConfig {
+    /** Operator account with private key for signing payments (EOA) */
+    operatorAccount: Account;
+    /**
+     * Consumer's IATPWallet contract address.
+     * If not provided, uses operator_account.address for testing.
+     */
+    walletAddress?: `0x${string}`;
+    /**
+     * Optional safety limit for maximum payment amount per request in base units.
+     *
+     * WARNING: This is a simple numeric comparison and does NOT account for:
+     * - Different tokens (USDC vs TRAIA vs others) - amounts are compared directly
+     * - Token decimals - ensure maxValue uses the same decimals as expected tokens
+     * - Exchange rates - this is not a USD limit, it's a token amount limit
+     *
+     * Each endpoint can have different payment requirements (amount and token),
+     * but this limit applies to all requests. Set it based on your most expensive
+     * expected payment in the token's base units.
+     *
+     * If undefined, no limit is enforced (not recommended for production).
+     */
+    maxValue?: bigint;
+    /**
+     * Optional custom selector for payment requirements.
+     * If not provided, uses default selector that picks first "exact" scheme.
+     */
+    paymentRequirementsSelector?: PaymentSelector;
+    /**
+     * Optional network filter for payment selection.
+     * Only select requirements matching this network.
+     */
+    networkFilter?: string;
+    /**
+     * Optional scheme filter for payment selection.
+     * Defaults to "exact".
+     */
+    schemeFilter?: string;
+}
+/**
+ * D402 Client for handling HTTP 402 Payment Required responses.
+ *
+ * Matches Python: d402Client class (base.py lines 63-219)
+ *
+ * This client automatically:
+ * 1. Detects HTTP 402 responses
+ * 2. Parses payment requirements
+ * 3. Selects appropriate payment option
+ * 4. Signs payment with EIP-712
+ * 5. Retries request with X-Payment header
+ *
+ * @example
+ * ```ts
+ * import { D402Client } from '@iatp/d402-client'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ *
+ * const operatorAccount = privateKeyToAccount('0x...')
+ *
+ * const client = new D402Client({
+ *   operatorAccount,
+ *   walletAddress: '0xUserIATPWallet...',
+ *   maxValue: 1000000n  // 1 USDC max
+ * })
+ *
+ * const response = await client.fetch('http://api.example.com/analyze', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ text: 'Analyze this' })
+ * })
+ *
+ * const data = await response.json()
+ * ```
+ */
+declare class D402Client {
+    private readonly operatorAccount;
+    private readonly walletAddress;
+    private readonly maxValue?;
+    private readonly paymentRequirementsSelector;
+    private readonly networkFilter?;
+    private readonly schemeFilter;
+    /**
+     * Create a new D402 Client.
+     *
+     * Matches Python: d402Client.__init__ (base.py lines 66-95)
+     *
+     * @param config - Client configuration
+     */
+    constructor(config: D402ClientConfig);
+    /**
+     * Select payment requirement from list of options.
+     *
+     * Matches Python: select_payment_requirements (base.py lines 152-174)
+     *
+     * @param requirements - List of payment requirements from 402 response
+     * @returns Selected payment requirement
+     */
+    selectPaymentRequirement(requirements: PaymentRequirement[]): PaymentRequirement;
+    /**
+     * Get the wallet address used for payments.
+     *
+     * @returns IATPWallet contract address or operator EOA address
+     */
+    getWalletAddress(): `0x${string}`;
+    /**
+     * Get the operator account used for signing.
+     *
+     * @returns Operator account
+     */
+    getOperatorAccount(): Account;
+    /**
+     * Get the maximum payment value limit.
+     *
+     * @returns Maximum value in base units, or undefined if no limit
+     */
+    getMaxValue(): bigint | undefined;
+    /**
+     * Fetch with automatic 402 payment handling.
+     *
+     * Matches Python: HttpxHooks.on_response() (httpx.py lines 33-117)
+     *
+     * Flow:
+     * 1. Make request without payment
+     * 2. If 402 response, parse payment requirements
+     * 3. Select appropriate payment option
+     * 4. Sign payment with EIP-712
+     * 5. Retry request with X-Payment header
+     * 6. Return final response
+     *
+     * @param url - URL to fetch
+     * @param init - Fetch options (method, headers, body, etc.)
+     * @returns Response object (after payment if 402)
+     *
+     * @example
+     * ```ts
+     * const client = new D402Client({ operatorAccount, walletAddress })
+     *
+     * const response = await client.fetch('http://api.example.com/analyze', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({ text: 'Analyze this' })
+     * })
+     *
+     * const data = await response.json()
+     * ```
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * EIP-712 payment signing utilities
+ *
+ * Matches Python implementation: IATP/src/traia_iatp/d402/payment_signing.py
+ */
+
+/**
+ * Sign a D402 payment using EIP-712 signature.
+ *
+ * Matches Python: sign_payment_header(operator_account, payment_requirements, header, wallet_address, request_path)
+ * (payment_signing.py lines 54-155)
+ *
+ * This creates a PullFundsForSettlement signature that matches IATPWallet.sol validation.
+ *
+ * @param params - Signing parameters
+ * @param params.operatorAccount - Operator account with private key for signing (EOA)
+ * @param params.paymentRequirement - Payment requirements from 402 response
+ * @param params.walletAddress - Consumer's IATPWallet contract address (optional, uses operator address if not provided)
+ * @param params.requestPath - API request path (optional, uses payment_requirements.resource if not provided)
+ * @returns Signed payment ready to encode and send
+ *
+ * @example
+ * ```ts
+ * const requirement = await parsePaymentRequirement(response)
+ * const signedPayment = await signD402Payment({
+ *   operatorAccount: account,
+ *   paymentRequirement: requirement,
+ *   walletAddress: '0xUserWallet...'
+ * })
+ * const encoded = encodePayment(signedPayment)
+ * ```
+ */
+declare function signD402Payment(params: {
+    operatorAccount: Account;
+    paymentRequirement: PaymentRequirement;
+    walletAddress?: `0x${string}`;
+    requestPath?: string;
+    d402Version?: number;
+}): Promise<SignedPayment>;
+
+/**
+ * Parse 402 payment requirements from HTTP responses
+ *
+ * Matches Python implementation: IATP/src/traia_iatp/d402/clients/httpx.py lines 64-66
+ * Response structure from: IATP/src/traia_iatp/d402/types.py d402PaymentRequiredResponse
+ */
+
+/**
+ * Parse payment requirements from HTTP 402 response.
+ *
+ * Matches Python:
+ *   data = response.json()
+ *   payment_response = d402PaymentRequiredResponse(**data)
+ *
+ * The 402 response body contains payment requirements in camelCase JSON format.
+ *
+ * @param response - HTTP Response object with status 402
+ * @returns First payment requirement from accepts array
+ * @throws {Invalid402ResponseError} If response is not valid 402 or malformed
+ *
+ * @example
+ * ```ts
+ * const response = await fetch('http://api.example.com')
+ * if (response.status === 402) {
+ *   const requirement = await parsePaymentRequirement(response)
+ *   console.log(requirement.maxAmountRequired) // "10000"
+ * }
+ * ```
+ */
+declare function parsePaymentRequirement(response: Response): Promise<PaymentRequirement>;
+
+/**
+ * Base64 encoding/decoding for payment payloads
+ *
+ * Matches Python implementation: IATP/src/traia_iatp/d402/encoding.py
+ */
+
+/**
+ * Encode a payment object to base64 string.
+ *
+ * This combines JSON serialization with base64 encoding.
+ * Matches Python: encode_payment(payment_payload: Dict[str, Any]) -> str
+ *
+ * @param payment - Payment object to encode
+ * @returns Base64 encoded payment string suitable for X-Payment header
+ *
+ * @example
+ * ```ts
+ * const payment = { d402Version: 1, scheme: 'exact', payload: {...} }
+ * const encoded = encodePayment(payment)
+ * // Use in header: { 'X-Payment': encoded }
+ * ```
+ */
+declare function encodePayment(payment: SignedPayment): string;
+/**
+ * Decode a base64 encoded payment string back to payment object.
+ *
+ * Matches Python: decode_payment(encoded_payment: str) -> Dict[str, Any]
+ *
+ * @param encodedPayment - Base64 encoded payment string
+ * @returns Decoded payment object
+ *
+ * @example
+ * ```ts
+ * const payment = decodePayment(encodedString)
+ * console.log(payment.d402Version) // 1
+ * ```
+ */
+declare function decodePayment(encodedPayment: string): SignedPayment;
+
+/**
+ * Utility functions for D402 payment processing
+ */
+
+/**
+ * Parse a money string or number into atomic units (wei)
+ *
+ * @param amount - Amount as string (e.g., "$1.00", "1.5") or number
+ * @param decimals - Token decimals (e.g., 6 for USDC, 18 for ETH)
+ * @returns Amount in atomic units (wei)
+ *
+ * @example
+ * parseMoney("$1.00", 6) // Returns 1000000n (1 USDC in wei)
+ * parseMoney("0.5", 18)  // Returns 500000000000000000n (0.5 ETH in wei)
+ */
+declare function parseMoney(amount: string | number | bigint, decimals: number): bigint;
+/**
+ * Format atomic units back to human-readable format
+ *
+ * @param amount - Amount in atomic units (wei)
+ * @param decimals - Token decimals
+ * @returns Formatted string
+ *
+ * @example
+ * formatMoney(1000000n, 6) // Returns "1.000000"
+ */
+declare function formatMoney(amount: bigint, decimals: number): string;
+/**
+ * Get USDC token address for a given network
+ *
+ * @param network - Network name
+ * @returns USDC token address
+ *
+ * @throws {UnsupportedNetworkError} If network is not supported
+ */
+declare function getUsdcAddress(network: SupportedNetwork): `0x${string}`;
+/**
+ * Get chain ID for a given network.
+ *
+ * Matches Python: get_chain_id(network: str) -> str (chains.py lines 10-21)
+ *
+ * Supports both network names and numeric chain IDs as strings.
+ *
+ * @param network - Network name or chain ID as string
+ * @returns Chain ID as number
+ *
+ * @throws {UnsupportedNetworkError} If network is not supported
+ *
+ * @example
+ * ```ts
+ * getChainId('sepolia')    // Returns 11155111
+ * getChainId('11155111')   // Returns 11155111 (passthrough)
+ * getChainId('base')       // Returns 8453
+ * ```
+ */
+declare function getChainId(network: string): number;
+/**
+ * Find matching payment requirement from a list
+ *
+ * @param requirements - List of payment requirements
+ * @param scheme - Desired payment scheme (default: "exact")
+ * @param network - Desired network (optional)
+ * @returns Matching payment requirement or undefined
+ */
+declare function findMatchingPaymentRequirement(requirements: PaymentRequirement[], scheme?: string, network?: string): PaymentRequirement | undefined;
+/**
+ * Convert USD amount to USDC atomic units
+ *
+ * @param usdAmount - Amount in USD (e.g., "1.00" or 1.5)
+ * @param decimals - USDC decimals (default: 6)
+ * @returns Amount in USDC atomic units
+ *
+ * @example
+ * usdToUsdc("1.00") // Returns 1000000n
+ * usdToUsdc(1.5)    // Returns 1500000n
+ */
+declare function usdToUsdc(usdAmount: string | number, decimals?: number): bigint;
+/**
+ * Generate a random nonce for payment authorization
+ *
+ * @returns Random 32-byte nonce as hex string
+ */
+declare function generateNonce(): `0x${string}`;
+/**
+ * Get current timestamp in seconds
+ *
+ * @returns Unix timestamp in seconds
+ */
+declare function getCurrentTimestamp(): number;
+/**
+ * Validate Ethereum address format
+ *
+ * @param address - Address to validate
+ * @returns True if valid Ethereum address
+ */
+declare function isValidAddress(address: string): boolean;
+/**
+ * Normalize Ethereum address to checksummed format
+ * Note: This is a simple lowercase normalization. For full checksum validation, use viem's getAddress()
+ *
+ * @param address - Address to normalize
+ * @returns Normalized address
+ */
+declare function normalizeAddress(address: string): `0x${string}`;
+/**
+ * Decode X-PAYMENT-RESPONSE header from server
+ *
+ * @param header - Base64 encoded payment response
+ * @returns Decoded payment response
+ *
+ * @example
+ * const response = decodePaymentResponse(responseHeader)
+ * console.log(response.success, response.transaction)
+ */
+declare function decodePaymentResponse(header: string): {
+    success: boolean;
+    transaction?: string;
+    network?: string;
+    payer?: string;
+    message?: string;
+};
+
+/**
+ * Error classes for D402 payment protocol
+ */
+/**
+ * Base error class for all payment-related errors
+ */
+declare class PaymentError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when payment amount exceeds the configured maximum allowed value
+ */
+declare class PaymentAmountExceededError extends PaymentError {
+    amount: bigint;
+    maxAmount: bigint;
+    tokenAddress?: string | undefined;
+    constructor(amount: bigint, maxAmount: bigint, tokenAddress?: string | undefined);
+}
+/**
+ * Thrown when request configuration is missing required fields
+ */
+declare class MissingRequestConfigError extends PaymentError {
+    constructor(message: string);
+}
+/**
+ * Thrown when payment has already been attempted for a request
+ */
+declare class PaymentAlreadyAttemptedError extends PaymentError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when no supported payment scheme is found in payment requirements
+ */
+declare class UnsupportedSchemeError extends PaymentError {
+    availableSchemes: string[];
+    constructor(availableSchemes: string[], message?: string);
+}
+/**
+ * Thrown when payment verification fails
+ */
+declare class PaymentVerificationError extends PaymentError {
+    constructor(message: string);
+}
+/**
+ * Thrown when HTTP 402 response is malformed
+ */
+declare class Invalid402ResponseError extends PaymentError {
+    constructor(message: string);
+}
+/**
+ * Thrown when network is not supported
+ */
+declare class UnsupportedNetworkError extends PaymentError {
+    network: string;
+    constructor(network: string);
+}
+
+/**
+ * Network and token constants
+ */
+
+/**
+ * Chain IDs for supported networks
+ */
+declare const CHAIN_IDS: Record<SupportedNetwork, number>;
+/**
+ * Network configuration
+ */
+declare const NETWORKS: Record<SupportedNetwork, {
+    chainId: number;
+    name: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+}>;
+/**
+ * Default USDC token addresses per network
+ */
+declare const TOKEN_ADDRESSES: Record<SupportedNetwork, `0x${string}`>;
+/**
+ * Default payment validity window (5 minutes)
+ */
+declare const DEFAULT_VALIDITY_WINDOW_SECONDS = 300;
+/**
+ * EIP-712 type definitions for PullFundsForSettlement
+ */
+declare const EIP712_TYPES: {
+    readonly PullFundsForSettlement: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }, {
+        readonly name: "provider";
+        readonly type: "address";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "requestPath";
+        readonly type: "string";
+    }];
+};
+
+/**
+ * Contract configuration and utilities for IATP.
+ *
+ * Matches Python implementation: IATP/src/traia_iatp/contracts/config.py
+ *
+ * Bundles contract ABIs and addresses directly in the package for reliable access.
+ */
+/**
+ * Supported contract names.
+ *
+ * Matches Python: ContractName enum (config.py lines 16-21)
+ */
+declare enum ContractName {
+    IATP_WALLET = "IATPWallet",
+    IATP_WALLET_FACTORY = "IATPWalletFactory",
+    IATP_SETTLEMENT_LAYER = "IATPSettlementLayer",
+    ROLE_MANAGER = "RoleManager"
+}
+/**
+ * Supported networks for contract deployments.
+ *
+ * Matches Python: SUPPORTED_NETWORKS (config.py line 25)
+ */
+type SupportedContractNetwork = 'sepolia' | 'localhost';
+/**
+ * Get contract address for a given network.
+ *
+ * Matches Python: get_contract_address(contract_name: str, network: str) -> Optional[str]
+ * (config.py lines 77-118)
+ *
+ * @param contractName - Name of the contract (use ContractName enum)
+ * @param network - Network name (default: "sepolia")
+ * @param useProxy - Use proxy address if true, implementation if false (default: true)
+ * @returns Contract address as hex string, or null if not found
+ *
+ * @example
+ * ```ts
+ * const factoryAddr = getContractAddress(ContractName.IATP_WALLET_FACTORY, 'sepolia')
+ * console.log(factoryAddr) // "0x15D83638E339a0f29283f6B93dC1bb90b8339078"
+ * ```
+ */
+declare function getContractAddress(contractName: string | ContractName, network?: SupportedContractNetwork, useProxy?: boolean): string | null;
+/**
+ * Get contract ABI for a given network.
+ *
+ * Matches Python: get_contract_abi(contract_name: str, network: str) -> Optional[List[dict]]
+ * (config.py lines 121-156)
+ *
+ * @param contractName - Name of the contract (use ContractName enum)
+ * @param network - Network name (default: "sepolia")
+ * @returns Contract ABI as array of objects, or null if not found
+ *
+ * @example
+ * ```ts
+ * const factoryAbi = getContractAbi(ContractName.IATP_WALLET_FACTORY, 'sepolia')
+ * console.log(factoryAbi.length) // Number of ABI entries
+ * ```
+ */
+declare function getContractAbi(contractName: string | ContractName, network?: SupportedContractNetwork): any[] | null;
+/**
+ * Get contract configuration (address and ABI) for a network.
+ *
+ * Matches Python: get_contract_config(network: str) from wallet_creator.py
+ *
+ * @param contractName - Name of the contract
+ * @param network - Network name (default: "sepolia")
+ * @returns Object with address and abi, or null if not found
+ *
+ * @example
+ * ```ts
+ * const config = getContractConfig(ContractName.IATP_WALLET_FACTORY, 'sepolia')
+ * if (config) {
+ *   console.log(config.address)
+ *   console.log(config.abi.length)
+ * }
+ * ```
+ */
+declare function getContractConfig(contractName: string | ContractName, network?: SupportedContractNetwork): {
+    address: string;
+    abi: any[];
+} | null;
+/**
+ * Get all contract addresses for a network.
+ *
+ * @param network - Network name
+ * @returns Object with all contract addresses for the network
+ *
+ * @example
+ * ```ts
+ * const addresses = getAllContractAddresses('sepolia')
+ * console.log(addresses.IATPWalletFactory)
+ * ```
+ */
+declare function getAllContractAddresses(network: SupportedContractNetwork): Record<string, string>;
+/**
+ * Check if a contract is deployed on a network.
+ *
+ * @param contractName - Name of the contract
+ * @param network - Network name
+ * @returns True if contract exists on network
+ *
+ * @example
+ * ```ts
+ * if (isContractDeployed(ContractName.IATP_WALLET_FACTORY, 'sepolia')) {
+ *   // Contract is available
+ * }
+ * ```
+ */
+declare function isContractDeployed(contractName: string | ContractName, network: SupportedContractNetwork): boolean;
+
+/**
+ * IATPWallet creation and management
+ *
+ * Matches Python implementation: IATP/src/traia_iatp/scripts/create_wallet.py
+ */
+
+/**
+ * Result of wallet creation.
+ *
+ * Matches Python: create_wallet() return type (lines 138-147)
+ */
+interface WalletCreationResult {
+    /** Address of the created IATPWallet contract */
+    walletAddress: `0x${string}`;
+    /** Owner address (who created it) */
+    ownerAddress: `0x${string}`;
+    /** Operator address (can sign payments) */
+    operatorAddress: `0x${string}`;
+    /** Operator private key (store securely!) */
+    operatorPrivateKey: `0x${string}`;
+    /** Transaction hash */
+    transactionHash: Hash;
+    /** Block number where wallet was created */
+    blockNumber: bigint;
+    /** Network where wallet was deployed */
+    network: string;
+    /** Chain ID */
+    chainId: number;
+}
+/**
+ * Create a new IATPWallet using IATPWalletFactory.
+ *
+ * Matches Python: create_wallet(owner_private_key, network, wait_confirmations)
+ * (create_wallet.py lines 37-149)
+ *
+ * This function:
+ * 1. Generates a new operator keypair
+ * 2. Calls IATPWalletFactory.createWallet(operatorAddress)
+ * 3. Waits for transaction confirmation
+ * 4. Extracts wallet address from WalletCreated event
+ * 5. Returns wallet info including operator keys
+ *
+ * @param params - Creation parameters
+ * @param params.ownerAccount - Owner's account (will own the wallet)
+ * @param params.network - Network to deploy on (default: "sepolia")
+ * @param params.rpcUrl - Custom RPC URL (optional)
+ * @param params.operatorPrivateKey - Use specific operator key instead of generating (optional)
+ * @returns Wallet creation result with addresses and keys
+ *
+ * @example
+ * ```ts
+ * import { createIATPWallet } from '@iatp/d402-client'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ *
+ * const ownerAccount = privateKeyToAccount('0x...')
+ *
+ * const result = await createIATPWallet({
+ *   ownerAccount,
+ *   network: 'sepolia'
+ * })
+ *
+ * console.log('Wallet created:', result.walletAddress)
+ * console.log('Operator key:', result.operatorPrivateKey) // Store securely!
+ * ```
+ */
+declare function createIATPWallet(params: {
+    ownerAccount: Account;
+    network?: 'sepolia' | 'localhost';
+    rpcUrl?: string;
+    operatorPrivateKey?: `0x${string}`;
+}): Promise<WalletCreationResult>;
+
+export { CHAIN_IDS, ContractName, D402Client, type D402ClientConfig, type D402Config, DEFAULT_VALIDITY_WINDOW_SECONDS, type EIP712Domain, EIP712_TYPES, Invalid402ResponseError, MissingRequestConfigError, NETWORKS, PaymentAlreadyAttemptedError, PaymentAmountExceededError, type PaymentAuthorization, PaymentError, type PaymentRequirement, type PaymentSelector, type PaymentSelectorOptions, PaymentVerificationError, type SignedPayment, type SupportedContractNetwork, type SupportedNetwork, TOKEN_ADDRESSES, UnsupportedNetworkError, UnsupportedSchemeError, type WalletCreationResult, createIATPWallet, createPaymentSelector, decodePayment, decodePaymentResponse, encodePayment, findMatchingPaymentRequirement, formatMoney, generateNonce, getAllContractAddresses, getChainId, getContractAbi, getContractAddress, getContractConfig, getCurrentTimestamp, getUsdcAddress, isContractDeployed, isValidAddress, normalizeAddress, parseMoney, parsePaymentRequirement, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc };