@coinbase/agentkit 0.10.3 → 0.10.4

package/dist/action-providers/x402/constants.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Known facilitator registry
+ */
+export declare const KNOWN_FACILITATORS: {
+    readonly cdp: "https://api.cdp.coinbase.com/platform/v2/x402";
+    readonly payai: "https://facilitator.payai.network";
+};
+export type KnownFacilitatorName = keyof typeof KNOWN_FACILITATORS;
+export declare const DEFAULT_FACILITATOR: KnownFacilitatorName;
+/**
+ * Supported networks for x402 payment protocol
+ */
+export declare const SUPPORTED_NETWORKS: readonly ["base-mainnet", "base-sepolia", "solana-mainnet", "solana-devnet"];
+/**
+ * USDC token addresses for Solana networks
+ */
+export declare const SOLANA_USDC_ADDRESSES: {
+    readonly "solana-devnet": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
+    readonly "solana-mainnet": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+};
+/**
+ * Network mapping from internal network ID to both v1 and v2 (CAIP-2) formats.
+ * Used for filtering discovery results that may contain either format.
+ */
+export declare const NETWORK_MAPPINGS: Record<string, string[]>;
+/**
+ * x402 protocol version type
+ */
+export type X402Version = 1 | 2;
+/**
+ * Payment option from discovery API (supports both v1 and v2 formats)
+ */
+export interface PaymentOption {
+    scheme: string;
+    network: string;
+    asset: string;
+    maxAmountRequired?: string;
+    amount?: string;
+    price?: string;
+    payTo?: string;
+    description?: string;
+}
+/**
+ * Resource from discovery API
+ */
+export interface DiscoveryResource {
+    url?: string;
+    resource?: string;
+    type?: string;
+    metadata?: {
+        [key: string]: unknown;
+        description?: string;
+        input?: Record<string, unknown>;
+        output?: Record<string, unknown>;
+    };
+    accepts?: PaymentOption[];
+    x402Version?: number;
+    lastUpdated?: string;
+}
+/**
+ * Simplified resource output for LLM consumption
+ */
+export interface SimplifiedResource {
+    url: string;
+    price: string;
+    description: string;
+}

package/dist/action-providers/x402/constants.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NETWORK_MAPPINGS = exports.SOLANA_USDC_ADDRESSES = exports.SUPPORTED_NETWORKS = exports.DEFAULT_FACILITATOR = exports.KNOWN_FACILITATORS = void 0;
+/**
+ * Known facilitator registry
+ */
+exports.KNOWN_FACILITATORS = {
+    cdp: "https://api.cdp.coinbase.com/platform/v2/x402",
+    payai: "https://facilitator.payai.network",
+};
+exports.DEFAULT_FACILITATOR = "cdp";
+/**
+ * Supported networks for x402 payment protocol
+ */
+exports.SUPPORTED_NETWORKS = [
+    "base-mainnet",
+    "base-sepolia",
+    "solana-mainnet",
+    "solana-devnet",
+];
+/**
+ * USDC token addresses for Solana networks
+ */
+exports.SOLANA_USDC_ADDRESSES = {
+    "solana-devnet": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+    "solana-mainnet": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+};
+/**
+ * Network mapping from internal network ID to both v1 and v2 (CAIP-2) formats.
+ * Used for filtering discovery results that may contain either format.
+ */
+exports.NETWORK_MAPPINGS = {
+    "base-mainnet": ["base", "eip155:8453"],
+    "base-sepolia": ["base-sepolia", "eip155:84532"],
+    "solana-mainnet": ["solana", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
+    "solana-devnet": ["solana-devnet", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"],
+};

package/dist/action-providers/x402/schemas.d.ts

@@ -1,47 +1,76 @@
 import { z } from "zod";
+/**
+ * Resolves a facilitator name or URL to the actual URL.
+ *
+ * @param facilitator - Either a known facilitator name ('cdp', 'payai') or a custom URL
+ * @returns The facilitator URL
+ */
+export declare function resolveFacilitatorUrl(facilitator: string): string;
 export declare const ListX402ServicesSchema: z.ZodObject<{
+    facilitator: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["cdp", "payai"]>, z.ZodString]>>;
     maxUsdcPrice: z.ZodOptional<z.ZodNumber>;
+    x402Versions: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>]>, "many">>;
+    keyword: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    facilitator: string;
+    x402Versions: (1 | 2)[];
     maxUsdcPrice?: number | undefined;
+    keyword?: string | undefined;
 }, {
+    facilitator?: string | undefined;
     maxUsdcPrice?: number | undefined;
+    x402Versions?: (1 | 2)[] | undefined;
+    keyword?: string | undefined;
 }>;
 export declare const HttpRequestSchema: z.ZodObject<{
     url: z.ZodString;
     method: z.ZodDefault<z.ZodNullable<z.ZodEnum<["GET", "POST", "PUT", "DELETE", "PATCH"]>>>;
     headers: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    queryParams: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
     body: z.ZodNullable<z.ZodOptional<z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
     method: "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | null;
     url: string;
     body?: any;
     headers?: Record<string, string> | null | undefined;
+    queryParams?: Record<string, string> | null | undefined;
 }, {
     url: string;
     method?: "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | null | undefined;
     body?: any;
     headers?: Record<string, string> | null | undefined;
+    queryParams?: Record<string, string> | null | undefined;
 }>;
 export declare const RetryWithX402Schema: z.ZodObject<{
     url: z.ZodString;
     method: z.ZodDefault<z.ZodNullable<z.ZodEnum<["GET", "POST", "PUT", "DELETE", "PATCH"]>>>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    queryParams: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
     body: z.ZodOptional<z.ZodAny>;
     selectedPaymentOption: z.ZodObject<{
         scheme: z.ZodString;
         network: z.ZodString;
-        maxAmountRequired: z.ZodString;
         asset: z.ZodString;
+        maxAmountRequired: z.ZodOptional<z.ZodString>;
+        amount: z.ZodOptional<z.ZodString>;
+        price: z.ZodOptional<z.ZodString>;
+        payTo: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         scheme: string;
         network: string;
         asset: string;
-        maxAmountRequired: string;
+        amount?: string | undefined;
+        price?: string | undefined;
+        maxAmountRequired?: string | undefined;
+        payTo?: string | undefined;
     }, {
         scheme: string;
         network: string;
         asset: string;
-        maxAmountRequired: string;
+        amount?: string | undefined;
+        price?: string | undefined;
+        maxAmountRequired?: string | undefined;
+        payTo?: string | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     method: "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | null;
@@ -50,35 +79,46 @@ export declare const RetryWithX402Schema: z.ZodObject<{
         scheme: string;
         network: string;
         asset: string;
-        maxAmountRequired: string;
+        amount?: string | undefined;
+        price?: string | undefined;
+        maxAmountRequired?: string | undefined;
+        payTo?: string | undefined;
     };
     body?: any;
     headers?: Record<string, string> | undefined;
+    queryParams?: Record<string, string> | null | undefined;
 }, {
     url: string;
     selectedPaymentOption: {
         scheme: string;
         network: string;
         asset: string;
-        maxAmountRequired: string;
+        amount?: string | undefined;
+        price?: string | undefined;
+        maxAmountRequired?: string | undefined;
+        payTo?: string | undefined;
     };
     method?: "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | null | undefined;
     body?: any;
     headers?: Record<string, string> | undefined;
+    queryParams?: Record<string, string> | null | undefined;
 }>;
 export declare const DirectX402RequestSchema: z.ZodObject<{
     url: z.ZodString;
     method: z.ZodDefault<z.ZodNullable<z.ZodEnum<["GET", "POST", "PUT", "DELETE", "PATCH"]>>>;
     headers: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    queryParams: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
     body: z.ZodNullable<z.ZodOptional<z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
     method: "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | null;
     url: string;
     body?: any;
     headers?: Record<string, string> | null | undefined;
+    queryParams?: Record<string, string> | null | undefined;
 }, {
     url: string;
     method?: "POST" | "GET" | "PUT" | "DELETE" | "PATCH" | null | undefined;
     body?: any;
     headers?: Record<string, string> | null | undefined;
+    queryParams?: Record<string, string> | null | undefined;
 }>;

package/dist/action-providers/x402/schemas.js

@@ -1,14 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DirectX402RequestSchema = exports.RetryWithX402Schema = exports.HttpRequestSchema = exports.ListX402ServicesSchema = void 0;
+exports.resolveFacilitatorUrl = resolveFacilitatorUrl;
 const zod_1 = require("zod");
+const constants_1 = require("./constants");
+/**
+ * Resolves a facilitator name or URL to the actual URL.
+ *
+ * @param facilitator - Either a known facilitator name ('cdp', 'payai') or a custom URL
+ * @returns The facilitator URL
+ */
+function resolveFacilitatorUrl(facilitator) {
+    if (facilitator in constants_1.KNOWN_FACILITATORS) {
+        return constants_1.KNOWN_FACILITATORS[facilitator];
+    }
+    return facilitator;
+}
 // Schema for listing x402 services
 exports.ListX402ServicesSchema = zod_1.z
     .object({
+    facilitator: zod_1.z
+        .union([zod_1.z.enum(["cdp", "payai"]), zod_1.z.string().url()])
+        .default(constants_1.DEFAULT_FACILITATOR)
+        .describe("Facilitator to query: 'cdp' (Coinbase CDP), 'payai' (PayAI Network), or a custom facilitator URL."),
     maxUsdcPrice: zod_1.z
         .number()
+        .positive()
+        .finite()
         .optional()
         .describe("Optional maximum price in USDC whole units (e.g., 0.1 for 0.10 USDC). Only USDC payment options will be considered when this filter is applied."),
+    x402Versions: zod_1.z
+        .array(zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]))
+        .default([1, 2])
+        .describe("Filter by x402 protocol version (1 or 2). Defaults to accepting both versions."),
+    keyword: zod_1.z
+        .string()
+        .optional()
+        .describe("Optional keyword to filter services by description (case-insensitive). Example: 'weather' to find weather-related services."),
 })
     .strip()
     .describe("Parameters for listing x402 services with optional filtering");
@@ -29,14 +57,40 @@ exports.HttpRequestSchema = zod_1.z
         .optional()
         .nullable()
         .describe("Optional headers to include in the request"),
+    queryParams: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .nullable()
+        .describe("Query parameters to append to the URL as key-value string pairs. " +
+        "Use ONLY for GET/DELETE requests. " +
+        "For POST/PUT/PATCH, you must use the 'body' parameter instead. " +
+        "Example: {location: 'NYC', units: 'metric'} becomes ?location=NYC&units=metric"),
     body: zod_1.z
         .any()
         .optional()
         .nullable()
-        .describe("Optional request body for POST/PUT/PATCH requests"),
+        .describe("Request body - REQUIRED for POST/PUT/PATCH requests when sending data. " +
+        "Always prefer 'body' over 'queryParams' for POST/PUT/PATCH. " +
+        "Do NOT use for GET or DELETE, use queryParams instead."),
 })
     .strip()
     .describe("Instructions for making a basic HTTP request");
+// Payment option schema that supports both v1 and v2 formats
+const PaymentOptionSchema = zod_1.z
+    .object({
+    scheme: zod_1.z.string().describe("Payment scheme (e.g., 'exact')"),
+    network: zod_1.z
+        .string()
+        .describe("Network identifier (v1: 'base-sepolia' or v2 CAIP-2: 'eip155:84532')"),
+    asset: zod_1.z.string().describe("Asset address or identifier"),
+    // v1 format
+    maxAmountRequired: zod_1.z.string().optional().describe("Maximum amount required (v1 format)"),
+    // v2 format
+    amount: zod_1.z.string().optional().describe("Amount required (v2 format)"),
+    price: zod_1.z.string().optional().describe("Price (v2 format, e.g., '$0.01')"),
+    payTo: zod_1.z.string().optional().describe("Payment recipient address (v2 format)"),
+})
+    .describe("Payment option supporting both v1 and v2 x402 formats");
 // Schema for retrying a failed request with x402 payment
 exports.RetryWithX402Schema = zod_1.z
     .object({
@@ -50,15 +104,21 @@ exports.RetryWithX402Schema = zod_1.z
         .default("GET")
         .describe("The HTTP method to use for the request"),
     headers: zod_1.z.record(zod_1.z.string()).optional().describe("Optional headers to include in the request"),
-    body: zod_1.z.any().optional().describe("Optional request body for POST/PUT/PATCH requests"),
-    selectedPaymentOption: zod_1.z
-        .object({
-        scheme: zod_1.z.string(),
-        network: zod_1.z.string(),
-        maxAmountRequired: zod_1.z.string(),
-        asset: zod_1.z.string(),
-    })
-        .describe("The payment option to use for this request"),
+    queryParams: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .nullable()
+        .describe("Query parameters to append to the URL as key-value string pairs. " +
+        "Use ONLY for GET/DELETE requests. " +
+        "For POST/PUT/PATCH, you must use the 'body' parameter instead. " +
+        "Example: {location: 'NYC', units: 'metric'} becomes ?location=NYC&units=metric"),
+    body: zod_1.z
+        .any()
+        .optional()
+        .describe("Request body - REQUIRED for POST/PUT/PATCH requests when sending data. " +
+        "Always prefer 'body' over 'queryParams' for POST/PUT/PATCH. " +
+        "Do NOT use for GET or DELETE, use queryParams instead."),
+    selectedPaymentOption: PaymentOptionSchema.describe("The payment option to use for this request"),
 })
     .strip()
     .describe("Instructions for retrying a request with x402 payment after receiving a 402 response");
@@ -79,11 +139,21 @@ exports.DirectX402RequestSchema = zod_1.z
         .optional()
         .nullable()
         .describe("Optional headers to include in the request"),
+    queryParams: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .nullable()
+        .describe("Query parameters to append to the URL as key-value string pairs. " +
+        "Use ONLY for GET/DELETE requests. " +
+        "For POST/PUT/PATCH, use the 'body' parameter instead. " +
+        "Example: {location: 'NYC', units: 'metric'} becomes ?location=NYC&units=metric"),
     body: zod_1.z
         .any()
         .optional()
         .nullable()
-        .describe("Optional request body for POST/PUT/PATCH requests"),
+        .describe("Request body - REQUIRED for POST/PUT/PATCH requests when sending data. " +
+        "Always prefer 'body' over 'queryParams' for POST/PUT/PATCH. " +
+        "Do NOT use for GET or DELETE, use queryParams instead."),
 })
     .strip()
     .describe("Instructions for making an HTTP request with automatic x402 payment handling. WARNING: This bypasses user confirmation - only use when explicitly told to skip confirmation!");

package/dist/action-providers/x402/utils.d.ts

@@ -1,26 +1,93 @@
 import { Network } from "../../network";
-import { AxiosError } from "axios";
 import { WalletProvider } from "../../wallet-providers";
+import { type DiscoveryResource, type SimplifiedResource, type X402Version } from "./constants";
 /**
- * Supported network types for x402 protocol
+ * 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 type X402Network = "base" | "base-sepolia" | "solana" | "solana-devnet";
+export declare function filterByDescription(resources: DiscoveryResource[]): DiscoveryResource[];
 /**
- * Converts the internal network ID to the format expected by the x402 protocol.
+ * Filters resources by x402 protocol version.
+ * Uses the x402Version field on the resource.
  *
- * @param network - The network to convert
- * @returns The network ID in x402 format
- * @throws Error if the network is not supported
+ * @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 getX402Network(network: Network): X402Network | string | undefined;
+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 axios error to handle
+ * @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: AxiosError, url: string): string;
+export declare function handleHttpError(error: unknown, url: string): string;
 /**
  * Formats a payment option into a human-readable string.
  *
@@ -53,3 +120,11 @@ export declare function isUsdcAsset(asset: string, walletProvider: WalletProvide
  * @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;