@coinbase/agentkit/dist/action-providers/x402/utils.d.ts

Coinbase AgentKit core primitives

import { Network } from "../../network";
import { WalletProvider } from "../../wallet-providers";
import { type DiscoveryResource, type SimplifiedResource, type X402Version } from "./constants";
/**
 * Returns array of matching network identifiers (both v1 and v2 CAIP-2 formats).
 * Used for filtering discovery results that may contain either format.
 *
 * @param network - The network object
 * @returns Array of network identifiers that match the wallet's network
 */
export declare function getX402Networks(network: Network): string[];
/**
 * Gets network ID from a CAIP-2 or v1 network identifier.
 *
 * @param network - The x402 network identifier (e.g., "eip155:8453" for v2 or "base" for v1)
 * @returns The network ID (e.g., "base-mainnet") or the original if not found
 */
export declare function getNetworkId(network: string): string;
/**
 * Fetches all resources from the discovery API with pagination.
 *
 * @param discoveryUrl - The base URL for discovery
 * @param pageSize - Number of resources per page (default 100)
 * @returns Array of all discovered resources
 */
export declare function fetchAllDiscoveryResources(discoveryUrl: string, pageSize?: number): Promise<DiscoveryResource[]>;
/**
 * Filters resources by network compatibility.
 * Matches resources that accept any of the wallet's network identifiers (v1 or v2 format).
 *
 * @param resources - Array of discovery resources
 * @param walletNetworks - Array of network identifiers to match
 * @returns Filtered array of resources
 */
export declare function filterByNetwork(resources: DiscoveryResource[], walletNetworks: string[]): DiscoveryResource[];
/**
 * Filters resources by having a valid description.
 * Removes resources with empty or default descriptions.
 * Supports both v1 (accepts[].description) and v2 (metadata.description) formats.
 *
 * @param resources - Array of discovery resources
 * @returns Filtered array of resources with valid descriptions
 */
export declare function filterByDescription(resources: DiscoveryResource[]): DiscoveryResource[];
/**
 * Filters resources by x402 protocol version.
 * Uses the x402Version field on the resource.
 *
 * @param resources - Array of discovery resources
 * @param allowedVersions - Array of allowed versions (default: [1, 2])
 * @returns Filtered array of resources matching the allowed versions
 */
export declare function filterByX402Version(resources: DiscoveryResource[], allowedVersions?: X402Version[]): DiscoveryResource[];
/**
 * Filters resources by keyword appearing in description or URL.
 * Case-insensitive search.
 * Supports both v1 (accepts[].description) and v2 (metadata.description) formats.
 *
 * @param resources - Array of discovery resources
 * @param keyword - The keyword to search for in descriptions and URLs
 * @returns Filtered array of resources with matching descriptions or URLs
 */
export declare function filterByKeyword(resources: DiscoveryResource[], keyword: string): DiscoveryResource[];
/**
 * Filters resources by maximum USDC price.
 *
 * @param resources - Array of discovery resources
 * @param maxUsdcPrice - Maximum price in whole USDC units
 * @param walletProvider - Wallet provider for asset identification
 * @param walletNetworks - Array of network identifiers to match
 * @returns Filtered array of resources within price limit
 */
export declare function filterByMaxPrice(resources: DiscoveryResource[], maxUsdcPrice: number, walletProvider: WalletProvider, walletNetworks: string[]): Promise<DiscoveryResource[]>;
/**
 * Formats resources into simplified output for LLM consumption.
 *
 * @param resources - Array of discovery resources
 * @param walletNetworks - Array of network identifiers to match for price extraction
 * @param walletProvider - Wallet provider for formatting
 * @returns Array of simplified resources with url, price, description
 */
export declare function formatSimplifiedResources(resources: DiscoveryResource[], walletNetworks: string[], walletProvider: WalletProvider): Promise<SimplifiedResource[]>;
/**
 * Helper method to handle HTTP errors consistently.
 *
 * @param error - The error to handle
 * @param url - The URL that was being accessed when the error occurred
 * @returns A JSON string containing formatted error details
 */
export declare function handleHttpError(error: unknown, url: string): string;
/**
 * Formats a payment option into a human-readable string.
 *
 * @param option - The payment option to format
 * @param option.asset - The asset address or identifier
 * @param option.maxAmountRequired - The maximum amount required for the payment
 * @param option.network - The network identifier
 * @param walletProvider - The wallet provider for token details lookup
 * @returns A formatted string like "0.1 USDC on base"
 */
export declare function formatPaymentOption(option: {
    asset: string;
    maxAmountRequired: string;
    network: string;
}, walletProvider: WalletProvider): Promise<string>;
/**
 * Checks if an asset is USDC on any supported network.
 *
 * @param asset - The asset address or identifier
 * @param walletProvider - The wallet provider for network context
 * @returns True if the asset is USDC, false otherwise
 */
export declare function isUsdcAsset(asset: string, walletProvider: WalletProvider): boolean;
/**
 * Converts whole units to atomic units for a given asset.
 *
 * @param wholeUnits - The amount in whole units (e.g., 0.1 for 0.1 USDC)
 * @param asset - The asset address or identifier
 * @param walletProvider - The wallet provider for token details lookup
 * @returns The amount in atomic units as a string, or null if conversion fails
 */
export declare function convertWholeUnitsToAtomic(wholeUnits: number, asset: string, walletProvider: WalletProvider): Promise<string | null>;
/**
 * Builds a URL with query parameters appended.
 *
 * @param baseUrl - The base URL
 * @param queryParams - Optional query parameters to append
 * @returns URL string with query parameters
 */
export declare function buildUrlWithParams(baseUrl: string, queryParams?: Record<string, string> | null): string;