@dexterai/x402 1.9.3 → 2.0.0

package/dist/client/index.d.cts

@@ -1,32 +1,11 @@
-export { P as PaymentReceipt, a as X402Client, X as X402ClientConfig, c as createX402Client, f as fireImpressionBeacon, g as getPaymentReceipt, d as getSponsoredAccessInfo, b as getSponsoredRecommendations } from '../sponsored-access-BCB2CxdG.cjs';
-import { A as AccessPassClientConfig } from '../types-BQvaF8lB.cjs';
-export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL, U as USDC_MINT, X as X402Error } from '../types-BQvaF8lB.cjs';
-import { Transaction, VersionedTransaction, Keypair } from '@solana/web3.js';
-import { E as EvmWallet } from '../solana-CfHuiW2H.cjs';
-export { B as BASE_MAINNET, S as SOLANA_MAINNET, a as createEvmAdapter, c as createSolanaAdapter } from '../solana-CfHuiW2H.cjs';
-export { C as ChainAdapter, W as WalletSet } from '../types-DmqH9yD8.cjs';
+export { P as PaymentReceipt, a as X402Client, X as X402ClientConfig, c as createX402Client, f as fireImpressionBeacon, g as getPaymentReceipt, d as getSponsoredAccessInfo, b as getSponsoredRecommendations } from '../sponsored-access-BgEDLg_H.cjs';
+import { A as AccessPassClientConfig, P as PaymentAccept } from '../types-CjLMR7qs.cjs';
+export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL, U as USDC_MINT, X as X402Error } from '../types-CjLMR7qs.cjs';
+import { Keypair } from '@solana/web3.js';
+import { S as SolanaWallet, E as EvmWallet } from '../types-DWhpiOBD.cjs';
+export { B as BASE_MAINNET, C as ChainAdapter, b as SOLANA_MAINNET, W as WalletSet, a as createEvmAdapter, c as createSolanaAdapter } from '../types-DWhpiOBD.cjs';
 export { SponsoredAccessSettlementInfo, SponsoredRecommendation } from '@dexterai/x402-ads-types';
 
-/**
- * Simple Fetch Wrapper for Node.js
- *
- * The easiest way to make x402 payments from Node.js scripts.
- * Just provide a private key and it handles everything automatically.
- *
- * @example
- * ```typescript
- * import { wrapFetch } from '@dexterai/x402/client';
- *
- * const x402Fetch = wrapFetch(fetch, {
- *   walletPrivateKey: process.env.SOLANA_PRIVATE_KEY!,
- * });
- *
- * // Make a paid request - payment happens automatically
- * const response = await x402Fetch('https://api.example.com/protected');
- * const data = await response.json();
- * ```
- */
-
 /**
  * Options for wrapFetch
  */
@@ -81,6 +60,11 @@ interface WrapFetchOptions {
      * ```
      */
     accessPass?: AccessPassClientConfig;
+    /**
+     * Called before signing a payment. Return true to proceed, false to reject.
+     * Used internally by Budget Accounts — can also be set directly.
+     */
+    onPaymentRequired?: (requirements: PaymentAccept) => boolean | Promise<boolean>;
 }
 /**
  * Wrap fetch with automatic x402 payment handling
@@ -135,19 +119,27 @@ declare function wrapFetch(fetchImpl: typeof globalThis.fetch, options: WrapFetc
  * ```
  */
 
+/** Symbol key for the underlying Keypair — prevents accidental exposure via console.log or JSON.stringify */
+declare const KEYPAIR_SYMBOL: unique symbol;
 /**
- * Keypair wallet interface (compatible with SDK's SolanaWallet)
+ * Keypair wallet interface — extends SolanaWallet with safe Keypair access.
  */
-interface KeypairWallet {
-    /** Public key with toBase58() method */
-    publicKey: {
-        toBase58(): string;
-    };
-    /** Sign a transaction */
-    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
-    /** Get the underlying keypair (for advanced use) */
+interface KeypairWallet extends SolanaWallet {
+    /**
+     * Get the underlying Keypair. Accessed via Symbol to prevent accidental
+     * exposure through console.log, JSON.stringify, or Object.keys.
+     *
+     * @example
+     * ```typescript
+     * import { KEYPAIR_SYMBOL } from '@dexterai/x402/client';
+     * const kp = wallet[KEYPAIR_SYMBOL];
+     * ```
+     */
+    [KEYPAIR_SYMBOL]: Keypair;
+    /** @deprecated Use wallet[KEYPAIR_SYMBOL] instead — this will be removed in a future major version */
     keypair: Keypair;
 }
+
 /**
  * Create a wallet from a Solana private key
  *
@@ -245,4 +237,190 @@ declare function createEvmKeypairWallet(privateKey: string): Promise<EvmWallet>;
  */
 declare function isEvmKeypairWallet(wallet: unknown): wallet is EvmWallet;
 
-export { AccessPassClientConfig, type KeypairWallet, type WrapFetchOptions, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, wrapFetch };
+/**
+ * API Discovery — Find x402 Paid APIs
+ *
+ * Search the Dexter marketplace for x402-enabled APIs. Discover endpoints
+ * by category, price range, network, and quality score — then pay for them
+ * with the same SDK.
+ *
+ * @example
+ * ```typescript
+ * import { searchAPIs } from '@dexterai/x402/client';
+ *
+ * const results = await searchAPIs({ query: 'sentiment analysis', maxPrice: 0.10 });
+ * for (const api of results) {
+ *   console.log(`${api.name}: ${api.price} — ${api.description}`);
+ * }
+ *
+ * // Then call one with wrapFetch:
+ * const response = await x402Fetch(results[0].url);
+ * ```
+ */
+/**
+ * Search options for discovering x402 APIs
+ */
+interface SearchAPIsOptions {
+    /** Search query (e.g., 'sentiment analysis', 'token price', 'image generation') */
+    query?: string;
+    /** Filter by category (e.g., 'defi', 'ai', 'data', 'social') */
+    category?: string;
+    /** Filter by payment network (e.g., 'solana', 'base', 'polygon') */
+    network?: string;
+    /** Maximum price per call in USDC */
+    maxPrice?: number;
+    /** Only return verified endpoints (quality score 75+) */
+    verifiedOnly?: boolean;
+    /** Sort order */
+    sort?: 'marketplace' | 'relevance' | 'quality_score' | 'settlements' | 'volume' | 'recent';
+    /** Maximum results to return (default 20, max 50) */
+    limit?: number;
+    /** Marketplace API URL (default: Dexter marketplace) */
+    marketplaceUrl?: string;
+}
+/**
+ * A discovered x402 API endpoint
+ */
+interface DiscoveredAPI {
+    /** API name */
+    name: string;
+    /** Full resource URL — pass directly to wrapFetch or createX402Client.fetch */
+    url: string;
+    /** HTTP method */
+    method: string;
+    /** Price per call (formatted, e.g., '$0.05') */
+    price: string;
+    /** Price per call in USDC (raw number, null if free) */
+    priceUsdc: number | null;
+    /** Payment network */
+    network: string | null;
+    /** Human-readable description */
+    description: string;
+    /** Category (e.g., 'defi', 'ai', 'data') */
+    category: string;
+    /** Quality score (0-100, null if unscored) */
+    qualityScore: number | null;
+    /** Whether the endpoint has been verified */
+    verified: boolean;
+    /** Total number of settlements (calls) */
+    totalCalls: number;
+    /** Total volume in USDC (formatted, e.g., '$1,234.56') */
+    totalVolume: string | null;
+    /** Seller name */
+    seller: string | null;
+    /** Seller reputation score */
+    sellerReputation: number | null;
+    /** Whether authentication is required beyond payment */
+    authRequired: boolean;
+    /** Last time someone called this API */
+    lastActive: string | null;
+}
+/**
+ * Search the Dexter marketplace for x402 paid APIs.
+ *
+ * Returns a list of discovered endpoints that can be called directly
+ * with `wrapFetch` or `createX402Client.fetch`.
+ *
+ * @example Find AI APIs under $0.10
+ * ```typescript
+ * const apis = await searchAPIs({ query: 'ai', maxPrice: 0.10 });
+ * ```
+ *
+ * @example Browse all verified DeFi tools
+ * ```typescript
+ * const apis = await searchAPIs({ category: 'defi', verifiedOnly: true });
+ * ```
+ *
+ * @example Find cheapest APIs on Solana
+ * ```typescript
+ * const apis = await searchAPIs({ network: 'solana', sort: 'quality_score' });
+ * ```
+ */
+declare function searchAPIs(options?: SearchAPIsOptions): Promise<DiscoveredAPI[]>;
+
+/**
+ * Budget Account — Autonomous Agent Spending Controls
+ *
+ * Wraps the x402 client with a spending limit, per-request cap,
+ * per-hour rate limit, and optional domain allowlist. Tracks cumulative
+ * spend and exposes remaining budget. When the budget is exhausted,
+ * requests throw instead of paying.
+ *
+ * @example
+ * ```typescript
+ * import { createBudgetAccount } from '@dexterai/x402/client';
+ *
+ * const agent = createBudgetAccount({
+ *   walletPrivateKey: process.env.SOLANA_PRIVATE_KEY,
+ *   budget: {
+ *     total: '50.00',       // $50 total budget
+ *     perRequest: '1.00',   // max $1 per request
+ *     perHour: '10.00',     // max $10/hour
+ *   },
+ *   allowedDomains: ['api.example.com', 'data.example.com'],
+ * });
+ *
+ * const response = await agent.fetch('https://api.example.com/data');
+ * console.log(agent.spent);       // '$0.05'
+ * console.log(agent.remaining);   // '$49.95'
+ * console.log(agent.payments);    // 1
+ * ```
+ */
+
+/** Budget configuration */
+interface BudgetConfig {
+    /** Total spending limit in USD (e.g., '50.00') */
+    total: string;
+    /** Maximum amount per single request in USD (e.g., '1.00'). Optional. */
+    perRequest?: string;
+    /** Maximum spend per hour in USD (e.g., '10.00'). Optional. */
+    perHour?: string;
+}
+/** Budget Account configuration — extends WrapFetchOptions with spending controls */
+interface BudgetAccountConfig extends WrapFetchOptions {
+    /** Spending limits */
+    budget: BudgetConfig;
+    /** Restrict payments to these domains only. If omitted, all domains allowed. */
+    allowedDomains?: string[];
+}
+/** A payment record in the spend ledger */
+interface PaymentRecord {
+    /** Amount paid in USD */
+    amount: number;
+    /** Domain that was paid */
+    domain: string;
+    /** CAIP-2 network used */
+    network: string;
+    /** Timestamp (ms) */
+    timestamp: number;
+}
+/** Budget Account — fetch with spending controls */
+interface BudgetAccount {
+    /** Payment-aware fetch with budget enforcement */
+    fetch: typeof globalThis.fetch;
+    /** Total amount spent (formatted, e.g., '$12.34') */
+    readonly spent: string;
+    /** Remaining budget (formatted, e.g., '$37.66') */
+    readonly remaining: string;
+    /** Number of payments made */
+    readonly payments: number;
+    /** Total spent as a raw number */
+    readonly spentAmount: number;
+    /** Remaining budget as a raw number */
+    readonly remainingAmount: number;
+    /** Full payment history */
+    readonly ledger: readonly PaymentRecord[];
+    /** Spend in the last hour */
+    readonly hourlySpend: number;
+    /** Reset the budget (clears all spend history) */
+    reset: () => void;
+}
+/**
+ * Create a budget-controlled fetch wrapper for autonomous agents.
+ *
+ * Enforces total spend limit, per-request cap, hourly rate limit,
+ * and domain allowlist. Every payment is tracked in an in-memory ledger.
+ */
+declare function createBudgetAccount(config: BudgetAccountConfig): BudgetAccount;
+
+export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, type DiscoveredAPI, KEYPAIR_SYMBOL, type KeypairWallet, type PaymentRecord, type SearchAPIsOptions, type WrapFetchOptions, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, searchAPIs, wrapFetch };

package/dist/client/index.d.ts

@@ -1,32 +1,11 @@
-export { P as PaymentReceipt, a as X402Client, X as X402ClientConfig, c as createX402Client, f as fireImpressionBeacon, g as getPaymentReceipt, d as getSponsoredAccessInfo, b as getSponsoredRecommendations } from '../sponsored-access-H1EX6zpi.js';
-import { A as AccessPassClientConfig } from '../types-BQvaF8lB.js';
-export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL, U as USDC_MINT, X as X402Error } from '../types-BQvaF8lB.js';
-import { Transaction, VersionedTransaction, Keypair } from '@solana/web3.js';
-import { E as EvmWallet } from '../solana-kZcwbUK9.js';
-export { B as BASE_MAINNET, S as SOLANA_MAINNET, a as createEvmAdapter, c as createSolanaAdapter } from '../solana-kZcwbUK9.js';
-export { C as ChainAdapter, W as WalletSet } from '../types-ENcnkof8.js';
+export { P as PaymentReceipt, a as X402Client, X as X402ClientConfig, c as createX402Client, f as fireImpressionBeacon, g as getPaymentReceipt, d as getSponsoredAccessInfo, b as getSponsoredRecommendations } from '../sponsored-access-DjLEKhOV.js';
+import { A as AccessPassClientConfig, P as PaymentAccept } from '../types-CjLMR7qs.js';
+export { b as AccessPassInfo, a as AccessPassTier, D as DEXTER_FACILITATOR_URL, U as USDC_MINT, X as X402Error } from '../types-CjLMR7qs.js';
+import { Keypair } from '@solana/web3.js';
+import { S as SolanaWallet, E as EvmWallet } from '../types-D1TGACsL.js';
+export { B as BASE_MAINNET, C as ChainAdapter, b as SOLANA_MAINNET, W as WalletSet, a as createEvmAdapter, c as createSolanaAdapter } from '../types-D1TGACsL.js';
 export { SponsoredAccessSettlementInfo, SponsoredRecommendation } from '@dexterai/x402-ads-types';
 
-/**
- * Simple Fetch Wrapper for Node.js
- *
- * The easiest way to make x402 payments from Node.js scripts.
- * Just provide a private key and it handles everything automatically.
- *
- * @example
- * ```typescript
- * import { wrapFetch } from '@dexterai/x402/client';
- *
- * const x402Fetch = wrapFetch(fetch, {
- *   walletPrivateKey: process.env.SOLANA_PRIVATE_KEY!,
- * });
- *
- * // Make a paid request - payment happens automatically
- * const response = await x402Fetch('https://api.example.com/protected');
- * const data = await response.json();
- * ```
- */
-
 /**
  * Options for wrapFetch
  */
@@ -81,6 +60,11 @@ interface WrapFetchOptions {
      * ```
      */
     accessPass?: AccessPassClientConfig;
+    /**
+     * Called before signing a payment. Return true to proceed, false to reject.
+     * Used internally by Budget Accounts — can also be set directly.
+     */
+    onPaymentRequired?: (requirements: PaymentAccept) => boolean | Promise<boolean>;
 }
 /**
  * Wrap fetch with automatic x402 payment handling
@@ -135,19 +119,27 @@ declare function wrapFetch(fetchImpl: typeof globalThis.fetch, options: WrapFetc
  * ```
  */
 
+/** Symbol key for the underlying Keypair — prevents accidental exposure via console.log or JSON.stringify */
+declare const KEYPAIR_SYMBOL: unique symbol;
 /**
- * Keypair wallet interface (compatible with SDK's SolanaWallet)
+ * Keypair wallet interface — extends SolanaWallet with safe Keypair access.
  */
-interface KeypairWallet {
-    /** Public key with toBase58() method */
-    publicKey: {
-        toBase58(): string;
-    };
-    /** Sign a transaction */
-    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
-    /** Get the underlying keypair (for advanced use) */
+interface KeypairWallet extends SolanaWallet {
+    /**
+     * Get the underlying Keypair. Accessed via Symbol to prevent accidental
+     * exposure through console.log, JSON.stringify, or Object.keys.
+     *
+     * @example
+     * ```typescript
+     * import { KEYPAIR_SYMBOL } from '@dexterai/x402/client';
+     * const kp = wallet[KEYPAIR_SYMBOL];
+     * ```
+     */
+    [KEYPAIR_SYMBOL]: Keypair;
+    /** @deprecated Use wallet[KEYPAIR_SYMBOL] instead — this will be removed in a future major version */
     keypair: Keypair;
 }
+
 /**
  * Create a wallet from a Solana private key
  *
@@ -245,4 +237,190 @@ declare function createEvmKeypairWallet(privateKey: string): Promise<EvmWallet>;
  */
 declare function isEvmKeypairWallet(wallet: unknown): wallet is EvmWallet;
 
-export { AccessPassClientConfig, type KeypairWallet, type WrapFetchOptions, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, wrapFetch };
+/**
+ * API Discovery — Find x402 Paid APIs
+ *
+ * Search the Dexter marketplace for x402-enabled APIs. Discover endpoints
+ * by category, price range, network, and quality score — then pay for them
+ * with the same SDK.
+ *
+ * @example
+ * ```typescript
+ * import { searchAPIs } from '@dexterai/x402/client';
+ *
+ * const results = await searchAPIs({ query: 'sentiment analysis', maxPrice: 0.10 });
+ * for (const api of results) {
+ *   console.log(`${api.name}: ${api.price} — ${api.description}`);
+ * }
+ *
+ * // Then call one with wrapFetch:
+ * const response = await x402Fetch(results[0].url);
+ * ```
+ */
+/**
+ * Search options for discovering x402 APIs
+ */
+interface SearchAPIsOptions {
+    /** Search query (e.g., 'sentiment analysis', 'token price', 'image generation') */
+    query?: string;
+    /** Filter by category (e.g., 'defi', 'ai', 'data', 'social') */
+    category?: string;
+    /** Filter by payment network (e.g., 'solana', 'base', 'polygon') */
+    network?: string;
+    /** Maximum price per call in USDC */
+    maxPrice?: number;
+    /** Only return verified endpoints (quality score 75+) */
+    verifiedOnly?: boolean;
+    /** Sort order */
+    sort?: 'marketplace' | 'relevance' | 'quality_score' | 'settlements' | 'volume' | 'recent';
+    /** Maximum results to return (default 20, max 50) */
+    limit?: number;
+    /** Marketplace API URL (default: Dexter marketplace) */
+    marketplaceUrl?: string;
+}
+/**
+ * A discovered x402 API endpoint
+ */
+interface DiscoveredAPI {
+    /** API name */
+    name: string;
+    /** Full resource URL — pass directly to wrapFetch or createX402Client.fetch */
+    url: string;
+    /** HTTP method */
+    method: string;
+    /** Price per call (formatted, e.g., '$0.05') */
+    price: string;
+    /** Price per call in USDC (raw number, null if free) */
+    priceUsdc: number | null;
+    /** Payment network */
+    network: string | null;
+    /** Human-readable description */
+    description: string;
+    /** Category (e.g., 'defi', 'ai', 'data') */
+    category: string;
+    /** Quality score (0-100, null if unscored) */
+    qualityScore: number | null;
+    /** Whether the endpoint has been verified */
+    verified: boolean;
+    /** Total number of settlements (calls) */
+    totalCalls: number;
+    /** Total volume in USDC (formatted, e.g., '$1,234.56') */
+    totalVolume: string | null;
+    /** Seller name */
+    seller: string | null;
+    /** Seller reputation score */
+    sellerReputation: number | null;
+    /** Whether authentication is required beyond payment */
+    authRequired: boolean;
+    /** Last time someone called this API */
+    lastActive: string | null;
+}
+/**
+ * Search the Dexter marketplace for x402 paid APIs.
+ *
+ * Returns a list of discovered endpoints that can be called directly
+ * with `wrapFetch` or `createX402Client.fetch`.
+ *
+ * @example Find AI APIs under $0.10
+ * ```typescript
+ * const apis = await searchAPIs({ query: 'ai', maxPrice: 0.10 });
+ * ```
+ *
+ * @example Browse all verified DeFi tools
+ * ```typescript
+ * const apis = await searchAPIs({ category: 'defi', verifiedOnly: true });
+ * ```
+ *
+ * @example Find cheapest APIs on Solana
+ * ```typescript
+ * const apis = await searchAPIs({ network: 'solana', sort: 'quality_score' });
+ * ```
+ */
+declare function searchAPIs(options?: SearchAPIsOptions): Promise<DiscoveredAPI[]>;
+
+/**
+ * Budget Account — Autonomous Agent Spending Controls
+ *
+ * Wraps the x402 client with a spending limit, per-request cap,
+ * per-hour rate limit, and optional domain allowlist. Tracks cumulative
+ * spend and exposes remaining budget. When the budget is exhausted,
+ * requests throw instead of paying.
+ *
+ * @example
+ * ```typescript
+ * import { createBudgetAccount } from '@dexterai/x402/client';
+ *
+ * const agent = createBudgetAccount({
+ *   walletPrivateKey: process.env.SOLANA_PRIVATE_KEY,
+ *   budget: {
+ *     total: '50.00',       // $50 total budget
+ *     perRequest: '1.00',   // max $1 per request
+ *     perHour: '10.00',     // max $10/hour
+ *   },
+ *   allowedDomains: ['api.example.com', 'data.example.com'],
+ * });
+ *
+ * const response = await agent.fetch('https://api.example.com/data');
+ * console.log(agent.spent);       // '$0.05'
+ * console.log(agent.remaining);   // '$49.95'
+ * console.log(agent.payments);    // 1
+ * ```
+ */
+
+/** Budget configuration */
+interface BudgetConfig {
+    /** Total spending limit in USD (e.g., '50.00') */
+    total: string;
+    /** Maximum amount per single request in USD (e.g., '1.00'). Optional. */
+    perRequest?: string;
+    /** Maximum spend per hour in USD (e.g., '10.00'). Optional. */
+    perHour?: string;
+}
+/** Budget Account configuration — extends WrapFetchOptions with spending controls */
+interface BudgetAccountConfig extends WrapFetchOptions {
+    /** Spending limits */
+    budget: BudgetConfig;
+    /** Restrict payments to these domains only. If omitted, all domains allowed. */
+    allowedDomains?: string[];
+}
+/** A payment record in the spend ledger */
+interface PaymentRecord {
+    /** Amount paid in USD */
+    amount: number;
+    /** Domain that was paid */
+    domain: string;
+    /** CAIP-2 network used */
+    network: string;
+    /** Timestamp (ms) */
+    timestamp: number;
+}
+/** Budget Account — fetch with spending controls */
+interface BudgetAccount {
+    /** Payment-aware fetch with budget enforcement */
+    fetch: typeof globalThis.fetch;
+    /** Total amount spent (formatted, e.g., '$12.34') */
+    readonly spent: string;
+    /** Remaining budget (formatted, e.g., '$37.66') */
+    readonly remaining: string;
+    /** Number of payments made */
+    readonly payments: number;
+    /** Total spent as a raw number */
+    readonly spentAmount: number;
+    /** Remaining budget as a raw number */
+    readonly remainingAmount: number;
+    /** Full payment history */
+    readonly ledger: readonly PaymentRecord[];
+    /** Spend in the last hour */
+    readonly hourlySpend: number;
+    /** Reset the budget (clears all spend history) */
+    reset: () => void;
+}
+/**
+ * Create a budget-controlled fetch wrapper for autonomous agents.
+ *
+ * Enforces total spend limit, per-request cap, hourly rate limit,
+ * and domain allowlist. Every payment is tracked in an in-memory ledger.
+ */
+declare function createBudgetAccount(config: BudgetAccountConfig): BudgetAccount;
+
+export { AccessPassClientConfig, type BudgetAccount, type BudgetAccountConfig, type BudgetConfig, type DiscoveredAPI, KEYPAIR_SYMBOL, type KeypairWallet, type PaymentRecord, type SearchAPIsOptions, type WrapFetchOptions, createBudgetAccount, createEvmKeypairWallet, createKeypairWallet, isEvmKeypairWallet, isKeypairWallet, searchAPIs, wrapFetch };