@auteng/agent-utils 0.3.0 → 1.0.0

package/README.md

@@ -1,6 +1,8 @@
 # @auteng/agent-utils
 
-Give your AI agent its own crypto wallets. Create purpose-specific wallets funded with USDC on Base, then let the agent spend autonomously on x402-enabled services like sandboxed compute. No accounts, no KYC — just wallet addresses and USDC.
+x402 payments and sandboxed compute for autonomous AI agents. Discover, probe, and pay for x402-enabled services, and run sandboxed compute — all with USDC on Base.
+
+> **Wallet management** has moved to [`@auteng/pocket-money`](https://www.npmjs.com/package/@auteng/pocket-money). This package focuses on x402 protocol tools and compute. Agents can use any wallet — pocket-money, Coinbase Agentic Wallet, viem, ethers, or raw key management.
 
 ## Install
 
@@ -11,93 +13,68 @@ npm install @auteng/agent-utils
 ## Quick Start
 
 ```typescript
-import { wallet, compute } from '@auteng/agent-utils';
-
-// 1. Create a wallet for this task
-const w = await wallet.create({ name: "my-task" });
-console.log(`Fund me: send USDC on Base to ${w.address}`);
+import { x402, compute } from '@auteng/agent-utils';
 
-// 2. Wait for funding
-await w.waitForFunding(5_000000n); // wait for $5 USDC
-
-// 3. Run sandboxed code (payment handled automatically)
-const result = await compute.run({
-  code: 'print("hello from the sandbox")',
-  stack: 'python',
-  wallet: w,
-});
-console.log(result.stdout);
+// Probe any URL to check if it's x402-enabled
+const info = await x402.probe('https://api.example.com/generate');
+console.log(info.price); // "$0.05 USDC on Base"
 ```
 
-## Wallets
+## x402 — Discover & Inspect Services
 
-Each wallet is an independent keypair with its own address and balance. Create as many as you need — one per task, one per month, one per budget.
+Standalone functions for working with x402 services.
 
-```typescript
-import { wallet } from '@auteng/agent-utils';
+### Probe a URL
 
-const monthly = await wallet.create({ name: "feb-2026" });
-const task    = await wallet.create({ name: "data-pipeline" });
-const dev     = await wallet.create({ name: "testnet", network: "base-sepolia" });
-```
-
-Wallets are persisted at `.auteng/wallets/<name>.json`. Creating a wallet that already exists loads it from disk.
-
-### Check balance
+Check if a URL is x402-enabled and see what it costs:
 
 ```typescript
-const balance = await monthly.checkBalance();
-// Returns USDC in minor units (6 decimals)
-// 10_000000n = $10.00 USDC
-```
+import { x402 } from '@auteng/agent-utils';
 
-### Wait for funding
-
-```typescript
-await monthly.waitForFunding(10_000000n);
-// Polls Base every 10s until >= $10 USDC is available
+const info = await x402.probe('https://api.example.com/generate');
+if (info.enabled) {
+  console.log(info.price);                        // "$0.05 USDC on Base"
+  console.log(info.paymentRequired.accepts[0]);    // full payment details
+  console.log(info.paymentRequired.resource);      // what you're paying for
+}
 ```
 
-### x402 fetch
+### Discover services
 
-Drop-in `fetch()` replacement that handles x402 payments automatically:
+Browse the [Bazaar](https://www.x402.org/) registry to find x402 services:
 
 ```typescript
-const res = await monthly.fetch('https://x402.auteng.ai/api/x402/compute', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ code: 'print("hi")', stack: 'python', size: 'small' }),
-});
+const { services, total } = await x402.discover({ limit: 10 });
+for (const svc of services) {
+  console.log(`${svc.description} — ${svc.price}`);
+  console.log(`  ${svc.url}`);
+}
 ```
 
-If the server returns `402 Payment Required`, the library signs an EIP-3009 authorization and retries with payment headers. No gas needed.
+### Format prices
 
-### Retrieve and list wallets
+Convert raw x402 amounts to human-readable strings:
 
 ```typescript
-const w = wallet.get("feb-2026");   // load by name
-const all = wallet.list();           // list all wallets
+x402.formatPrice("2000", "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "eip155:8453");
+// → "$0.002 USDC on Base"
 
-for (const w of all) {
-  const bal = await w.checkBalance();
-  console.log(`${w.name}: ${w.address} — ${bal} USDC`);
-}
+x402.formatPrice("2000", "0x833589f...", "eip155:8453", { short: true });
+// → "$0.002 USDC"
 ```
 
-## Compute
+## Compute (AutEng)
 
-Run sandboxed code via AutEng's x402 compute endpoint. Pass a wallet to pay for execution:
+Convenience wrapper for AutEng's x402 sandboxed compute service. Accepts any object with a `fetch()` method as the wallet:
 
 ```typescript
-import { wallet, compute } from '@auteng/agent-utils';
-
-const w = await wallet.create({ name: "compute-budget" });
+import { compute } from '@auteng/agent-utils';
 
 const result = await compute.run({
   code: 'print("hello world")',
   stack: 'python',  // 'python' | 'node'
   size: 'small',    // 'small' | 'med' | 'large'
-  wallet: w,
+  wallet: myWallet, // any object with fetch()
 });
 console.log(result.stdout); // "hello world\n"
 ```
@@ -114,73 +91,12 @@ console.log(result.stdout); // "hello world\n"
 compute.pricing(); // returns full pricing table
 ```
 
-## Demo
-
-Run the included demo to see everything in action — wallet creation, funding, and autonomous compute:
-
-```bash
-node demo.mjs
-```
-
-```
-────────────────────────────────────────────────────────
-  POCKET MONEY DEMO — autonomous compute with x402
-────────────────────────────────────────────────────────
-
-  Compute pricing:
-    small  → $0.002 base + $0.00005/s  (2 vCPU, 1GB RAM)
-    med    → $0.008 base + $0.00012/s  (4 vCPU, 4GB RAM)
-    large  → $0.03 base + $0.00025/s  (8 vCPU, 16GB RAM)
-
-  Wallet: "demo-compute"
-  Address: 0x9cc8...e18
-  Balance: $0.0000
-────────────────────────────────────────────────────────
-
-  This wallet needs at least $1.0000 USDC to run the demo.
-
-  Please send USDC on **Base** to:
-  0x9cc8...e18
-
-  Waiting for funds...
-  Funded! New balance: $1.0000
-────────────────────────────────────────────────────────
-
-  Running compute jobs...
-
-  ▸ Python — Fibonacci
-    fib(10) = 55
-    fib(20) = 6765
-    fib(30) = 832040
-    fib(40) = 102334155
-    fib(50) = 12586269025
-
-  ▸ Python — System info
-    Python 3.12.12
-    OS: Linux 6.1.158
-    Arch: x86_64
-    CPUs: 2
-
-  ▸ Node — UUID generation
-    f8b260ec-2dea-401b-b807-544f366a8588
-    8eb115bb-e943-455b-b675-a177ed2c5e81
-    ...
-
-  Starting balance: $1.0000
-  Final balance:    $0.9980
-  Spent:            $0.0020
-────────────────────────────────────────────────────────
-  Done!
-```
-
-The demo creates a wallet, waits for you to fund it with $1 USDC on Base, then runs three sandboxed compute jobs (Python + Node) — all paid automatically via x402. Total cost: ~$0.002.
-
 ## Development
 
 ```bash
 npm install          # install dependencies
 npm run build        # build CJS/ESM/DTS to dist/
-npm test             # run unit + integration tests
+npm test             # run tests
 npm run test:watch   # run tests in watch mode
 ```
 

package/dist/index.d.mts

@@ -1,82 +1,16 @@
-import { PrivateKeyAccount } from 'viem';
-
-type Network = "base" | "base-sepolia";
-interface CreateWalletOptions {
-    /** Wallet identifier. Default: "default" */
-    name?: string;
-    /** Network to use. Default: `base` */
-    network?: Network;
-    /** Custom RPC endpoint. Default: public Base RPC */
-    rpcUrl?: string;
-    /** Base directory for wallet storage. Default: ".auteng/wallets" */
-    walletsDir?: string;
-}
-/** @deprecated Use CreateWalletOptions instead */
-type WalletConfig = CreateWalletOptions;
-interface WaitForFundingOptions {
-    /** Poll interval in milliseconds. Default: 10000 (10s) */
-    pollInterval?: number;
-    /** Timeout in milliseconds. Default: none (waits forever) */
-    timeout?: number;
-}
-
-declare class Wallet {
-    readonly name: string;
-    readonly address: `0x${string}`;
-    readonly network: Network;
-    private _account;
-    private _privateKey;
-    private _rpcUrl;
-    private _paymentFetch;
-    constructor(params: {
-        name: string;
-        account: PrivateKeyAccount;
-        privateKey: `0x${string}`;
-        network: Network;
-        rpcUrl?: string;
-        paymentFetch: typeof globalThis.fetch;
-    });
-    /** Check USDC balance on Base. Returns balance in minor units (6 decimals). */
-    checkBalance(): Promise<bigint>;
-    /**
-     * Poll until USDC balance >= minAmount.
-     * @param minAmount - minimum USDC balance in minor units (6 decimals)
-     */
-    waitForFunding(minAmount: bigint, opts?: WaitForFundingOptions): Promise<void>;
-    /**
-     * Drop-in `fetch()` replacement that handles x402 payments automatically.
-     * If the server returns 402, the library signs an EIP-3009 authorization
-     * and retries the request with payment headers.
-     */
-    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-}
-
-declare const wallet: {
-    /**
-     * Create a new named wallet or load an existing one from disk.
-     * Idempotent: if a wallet with this name already exists, returns it.
-     */
-    create(opts?: CreateWalletOptions): Promise<Wallet>;
-    /**
-     * Retrieve a previously-created wallet by name.
-     * Loads from disk if not in memory. Throws if not found.
-     */
-    get(name: string): Wallet;
-    /** List all persisted wallets. */
-    list(): Wallet[];
-    /** @internal Clear in-memory cache and reset wallets dir. For testing only. */
-    _reset(): void;
-};
-
 type Stack = "python" | "node";
 type Size = "small" | "med" | "large";
+/** Any object with a fetch method — pocket-money Wallet, custom wrapper, etc. */
+interface ComputeWallet {
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
 interface ComputeRequest {
     /** The code to execute */
     code: string;
     /** Runtime stack: 'python' (3.14) or 'node' (24 LTS) */
     stack: Stack;
-    /** The wallet to pay from */
-    wallet: Wallet;
+    /** The wallet to pay from — any object with a fetch() method */
+    wallet: ComputeWallet;
     /** Sandbox size. Default: 'small' */
     size?: Size;
     /** Execution timeout in seconds. Default: per-size default */
@@ -114,4 +48,121 @@ declare const compute: {
     setEndpoint(url: string): void;
 };
 
-export { type ComputeRequest, type ComputeResponse, type CreateWalletOptions, type Network, type PricingTier, type Size, type Stack, type WaitForFundingOptions, Wallet, type WalletConfig, compute, wallet };
+type Network = "base" | "base-sepolia";
+/** A single accepted payment option from a 402 response. */
+interface PaymentOption {
+    scheme: string;
+    network: string;
+    asset: string;
+    /** Raw amount in minor units (e.g. "2000" = $0.002 USDC). */
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+/** Normalized 402 response (works across v1 and v2). */
+interface PaymentRequiredResponse {
+    x402Version: number;
+    resource: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: PaymentOption[];
+    extensions?: Record<string, unknown>;
+}
+/** Result of probing a URL for x402 payment requirements. */
+interface ProbeResult {
+    /** Whether the URL returned 402 Payment Required. */
+    enabled: boolean;
+    /** The URL that was probed. */
+    url: string;
+    /** HTTP status code returned. */
+    status: number;
+    /** Human-readable price summary, e.g. "$0.002 USDC on Base". Null if not x402. */
+    price: string | null;
+    /** The parsed 402 response body. Null if not x402. */
+    paymentRequired: PaymentRequiredResponse | null;
+}
+interface ProbeOptions {
+    /** HTTP method to use. Default: "GET". */
+    method?: string;
+    /** Request headers to include. */
+    headers?: Record<string, string>;
+    /** Request body (for POST endpoints). */
+    body?: string;
+    /** Abort signal for timeout control. */
+    signal?: AbortSignal;
+}
+/** A service listed in the Bazaar registry. */
+interface BazaarService {
+    /** The service endpoint URL. */
+    url: string;
+    /** Service description. */
+    description: string | null;
+    /** Human-readable price of the cheapest accept option. */
+    price: string;
+    /** All accepted payment options. */
+    accepts: PaymentOption[];
+    /** Raw metadata from the Bazaar. */
+    metadata: Record<string, unknown>;
+}
+interface DiscoverResult {
+    services: BazaarService[];
+    total: number;
+}
+interface DiscoverOptions {
+    /** Max results to return. Default: 20. */
+    limit?: number;
+    /** Pagination offset. Default: 0. */
+    offset?: number;
+    /** Bazaar API base URL. Override for testing. */
+    bazaarUrl?: string;
+    /** Abort signal for timeout control. */
+    signal?: AbortSignal;
+}
+interface FormatPriceOptions {
+    /** If true, omit the network suffix (e.g. "$0.002 USDC" instead of "$0.002 USDC on Base"). */
+    short?: boolean;
+}
+
+/**
+ * Check if a URL is x402-enabled and see what it costs, without paying.
+ *
+ * Sends a request to the URL. If the server returns 402 Payment Required,
+ * parses the payment requirements and returns a structured result with
+ * human-readable pricing. Non-402 responses return `{ enabled: false }`.
+ *
+ * No wallet needed — this is a read-only inspection.
+ */
+declare function probe(url: string, options?: ProbeOptions): Promise<ProbeResult>;
+
+/**
+ * Query the Bazaar registry to find available x402 services.
+ *
+ * Fetches from the Coinbase CDP Bazaar discovery endpoint and returns
+ * a normalized list of services with human-readable pricing.
+ *
+ * No wallet or authentication needed.
+ */
+declare function discover(options?: DiscoverOptions): Promise<DiscoverResult>;
+
+/**
+ * Format a raw x402 price into a human-readable string.
+ *
+ * Knows about common assets (USDC on Base = 6 decimals, $-prefixed)
+ * and falls back to raw display for unknown assets.
+ *
+ * @example
+ * formatPrice("2000", "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "eip155:8453")
+ * // → "$0.002 USDC on Base"
+ */
+declare function formatPrice(amount: string, asset: string, network: string, options?: FormatPriceOptions): string;
+
+declare const x402: {
+    probe: typeof probe;
+    discover: typeof discover;
+    formatPrice: typeof formatPrice;
+};
+
+export { type BazaarService, type ComputeRequest, type ComputeResponse, type ComputeWallet, type DiscoverOptions, type DiscoverResult, type FormatPriceOptions, type Network, type PaymentOption, type PaymentRequiredResponse, type PricingTier, type ProbeOptions, type ProbeResult, type Size, type Stack, compute, x402 };

package/dist/index.d.ts

@@ -1,82 +1,16 @@
-import { PrivateKeyAccount } from 'viem';
-
-type Network = "base" | "base-sepolia";
-interface CreateWalletOptions {
-    /** Wallet identifier. Default: "default" */
-    name?: string;
-    /** Network to use. Default: `base` */
-    network?: Network;
-    /** Custom RPC endpoint. Default: public Base RPC */
-    rpcUrl?: string;
-    /** Base directory for wallet storage. Default: ".auteng/wallets" */
-    walletsDir?: string;
-}
-/** @deprecated Use CreateWalletOptions instead */
-type WalletConfig = CreateWalletOptions;
-interface WaitForFundingOptions {
-    /** Poll interval in milliseconds. Default: 10000 (10s) */
-    pollInterval?: number;
-    /** Timeout in milliseconds. Default: none (waits forever) */
-    timeout?: number;
-}
-
-declare class Wallet {
-    readonly name: string;
-    readonly address: `0x${string}`;
-    readonly network: Network;
-    private _account;
-    private _privateKey;
-    private _rpcUrl;
-    private _paymentFetch;
-    constructor(params: {
-        name: string;
-        account: PrivateKeyAccount;
-        privateKey: `0x${string}`;
-        network: Network;
-        rpcUrl?: string;
-        paymentFetch: typeof globalThis.fetch;
-    });
-    /** Check USDC balance on Base. Returns balance in minor units (6 decimals). */
-    checkBalance(): Promise<bigint>;
-    /**
-     * Poll until USDC balance >= minAmount.
-     * @param minAmount - minimum USDC balance in minor units (6 decimals)
-     */
-    waitForFunding(minAmount: bigint, opts?: WaitForFundingOptions): Promise<void>;
-    /**
-     * Drop-in `fetch()` replacement that handles x402 payments automatically.
-     * If the server returns 402, the library signs an EIP-3009 authorization
-     * and retries the request with payment headers.
-     */
-    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-}
-
-declare const wallet: {
-    /**
-     * Create a new named wallet or load an existing one from disk.
-     * Idempotent: if a wallet with this name already exists, returns it.
-     */
-    create(opts?: CreateWalletOptions): Promise<Wallet>;
-    /**
-     * Retrieve a previously-created wallet by name.
-     * Loads from disk if not in memory. Throws if not found.
-     */
-    get(name: string): Wallet;
-    /** List all persisted wallets. */
-    list(): Wallet[];
-    /** @internal Clear in-memory cache and reset wallets dir. For testing only. */
-    _reset(): void;
-};
-
 type Stack = "python" | "node";
 type Size = "small" | "med" | "large";
+/** Any object with a fetch method — pocket-money Wallet, custom wrapper, etc. */
+interface ComputeWallet {
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
 interface ComputeRequest {
     /** The code to execute */
     code: string;
     /** Runtime stack: 'python' (3.14) or 'node' (24 LTS) */
     stack: Stack;
-    /** The wallet to pay from */
-    wallet: Wallet;
+    /** The wallet to pay from — any object with a fetch() method */
+    wallet: ComputeWallet;
     /** Sandbox size. Default: 'small' */
     size?: Size;
     /** Execution timeout in seconds. Default: per-size default */
@@ -114,4 +48,121 @@ declare const compute: {
     setEndpoint(url: string): void;
 };
 
-export { type ComputeRequest, type ComputeResponse, type CreateWalletOptions, type Network, type PricingTier, type Size, type Stack, type WaitForFundingOptions, Wallet, type WalletConfig, compute, wallet };
+type Network = "base" | "base-sepolia";
+/** A single accepted payment option from a 402 response. */
+interface PaymentOption {
+    scheme: string;
+    network: string;
+    asset: string;
+    /** Raw amount in minor units (e.g. "2000" = $0.002 USDC). */
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+/** Normalized 402 response (works across v1 and v2). */
+interface PaymentRequiredResponse {
+    x402Version: number;
+    resource: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: PaymentOption[];
+    extensions?: Record<string, unknown>;
+}
+/** Result of probing a URL for x402 payment requirements. */
+interface ProbeResult {
+    /** Whether the URL returned 402 Payment Required. */
+    enabled: boolean;
+    /** The URL that was probed. */
+    url: string;
+    /** HTTP status code returned. */
+    status: number;
+    /** Human-readable price summary, e.g. "$0.002 USDC on Base". Null if not x402. */
+    price: string | null;
+    /** The parsed 402 response body. Null if not x402. */
+    paymentRequired: PaymentRequiredResponse | null;
+}
+interface ProbeOptions {
+    /** HTTP method to use. Default: "GET". */
+    method?: string;
+    /** Request headers to include. */
+    headers?: Record<string, string>;
+    /** Request body (for POST endpoints). */
+    body?: string;
+    /** Abort signal for timeout control. */
+    signal?: AbortSignal;
+}
+/** A service listed in the Bazaar registry. */
+interface BazaarService {
+    /** The service endpoint URL. */
+    url: string;
+    /** Service description. */
+    description: string | null;
+    /** Human-readable price of the cheapest accept option. */
+    price: string;
+    /** All accepted payment options. */
+    accepts: PaymentOption[];
+    /** Raw metadata from the Bazaar. */
+    metadata: Record<string, unknown>;
+}
+interface DiscoverResult {
+    services: BazaarService[];
+    total: number;
+}
+interface DiscoverOptions {
+    /** Max results to return. Default: 20. */
+    limit?: number;
+    /** Pagination offset. Default: 0. */
+    offset?: number;
+    /** Bazaar API base URL. Override for testing. */
+    bazaarUrl?: string;
+    /** Abort signal for timeout control. */
+    signal?: AbortSignal;
+}
+interface FormatPriceOptions {
+    /** If true, omit the network suffix (e.g. "$0.002 USDC" instead of "$0.002 USDC on Base"). */
+    short?: boolean;
+}
+
+/**
+ * Check if a URL is x402-enabled and see what it costs, without paying.
+ *
+ * Sends a request to the URL. If the server returns 402 Payment Required,
+ * parses the payment requirements and returns a structured result with
+ * human-readable pricing. Non-402 responses return `{ enabled: false }`.
+ *
+ * No wallet needed — this is a read-only inspection.
+ */
+declare function probe(url: string, options?: ProbeOptions): Promise<ProbeResult>;
+
+/**
+ * Query the Bazaar registry to find available x402 services.
+ *
+ * Fetches from the Coinbase CDP Bazaar discovery endpoint and returns
+ * a normalized list of services with human-readable pricing.
+ *
+ * No wallet or authentication needed.
+ */
+declare function discover(options?: DiscoverOptions): Promise<DiscoverResult>;
+
+/**
+ * Format a raw x402 price into a human-readable string.
+ *
+ * Knows about common assets (USDC on Base = 6 decimals, $-prefixed)
+ * and falls back to raw display for unknown assets.
+ *
+ * @example
+ * formatPrice("2000", "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "eip155:8453")
+ * // → "$0.002 USDC on Base"
+ */
+declare function formatPrice(amount: string, asset: string, network: string, options?: FormatPriceOptions): string;
+
+declare const x402: {
+    probe: typeof probe;
+    discover: typeof discover;
+    formatPrice: typeof formatPrice;
+};
+
+export { type BazaarService, type ComputeRequest, type ComputeResponse, type ComputeWallet, type DiscoverOptions, type DiscoverResult, type FormatPriceOptions, type Network, type PaymentOption, type PaymentRequiredResponse, type PricingTier, type ProbeOptions, type ProbeResult, type Size, type Stack, compute, x402 };