@oneshot-agent/sdk 0.28.1 → 0.31.0

package/dist/index.js

@@ -37,9 +37,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OneShot = exports.executeSwap = exports.getSwapQuote = exports.CdpWalletProvider = exports.EthersWalletProvider = void 0;
+const deadline_1 = require("./deadline");
+const errors_1 = require("./errors");
 const ethers_1 = require("ethers");
 const ethers_2 = require("./providers/ethers");
-const errors_1 = require("./errors");
+const errors_2 = require("./errors");
 var ethers_3 = require("./providers/ethers");
 Object.defineProperty(exports, "EthersWalletProvider", { enumerable: true, get: function () { return ethers_3.EthersWalletProvider; } });
 var cdp_1 = require("./providers/cdp");
@@ -49,7 +51,7 @@ Object.defineProperty(exports, "getSwapQuote", { enumerable: true, get: function
 Object.defineProperty(exports, "executeSwap", { enumerable: true, get: function () { return swap_1.executeSwap; } });
 __exportStar(require("./errors"), exports);
 // Keep in sync with package.json `version`. Guarded by version.test.ts.
-const SDK_VERSION = '0.28.1';
+const SDK_VERSION = '0.31.0';
 /** HTTP poll cadence while push is unconfirmed: fast first checks, settling at 2s. */
 const HTTP_POLL_BACKOFF_MS = [300, 600, 1000, 2000];
 /** HTTP poll cadence once the WebSocket has delivered for this request. */
@@ -66,6 +68,29 @@ function chainIdFromNetwork(network) {
     return m ? Number(m[1]) : undefined;
 }
 const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+// ETH-currency mode. A payment is an EIP-3009 authorization that the
+// facilitator settles AFTER the API has responded, so for seconds after a
+// successful call `balanceOf` still shows pre-payment funds. The SDK therefore
+// keeps a ledger of signed-but-unsettled authorizations and works from
+// `balanceOf − pending`, over-reserving (one early buffered swap) rather than
+// under-reserving (a failed settlement).
+/** One balanceOf read per paid call, deduped within roughly one Base block. */
+const USDC_BALANCE_CACHE_MS = 2000;
+/** How long a signed authorization stays subtracted from the on-chain balance (settlement lands well within this). */
+const USDC_RESERVATION_TTL_MS = 90000;
+const DEFAULT_SWAP_BUFFER_MULTIPLIER = 10;
+const MAX_SWAP_BUFFER_MULTIPLIER = 1000;
+/** Fixed-point scale for the multiplier (6 decimals, matching USDC). */
+const SWAP_MULTIPLIER_SCALE = 1000000;
+const ERC20_BALANCE_ABI = ['function balanceOf(address) view returns (uint256)'];
+function validateSwapBufferMultiplier(m) {
+    if (m === undefined)
+        return DEFAULT_SWAP_BUFFER_MULTIPLIER;
+    if (typeof m !== 'number' || !Number.isFinite(m) || m < 1 || m > MAX_SWAP_BUFFER_MULTIPLIER) {
+        throw new errors_2.ValidationError(`swapBufferMultiplier must be a finite number between 1 and ${MAX_SWAP_BUFFER_MULTIPLIER}`, 'swapBufferMultiplier');
+    }
+    return m;
+}
 // ============================================================================
 // Public types — defined in ./types.ts. Re-exported below so existing
 // consumer imports (`import { EmailToolOptions, ... } from '@oneshot-agent/sdk'`)
@@ -95,21 +120,21 @@ function validateBudgetConfig(budgets) {
     // A typo'd key (`daliy`) from an untyped caller must not silently mean "no cap".
     for (const key of Object.keys(budgets)) {
         if (!['daily', 'perTransaction', 'alertAt', 'pauseAt'].includes(key)) {
-            throw new errors_1.ValidationError(`budgets.${key} is not a recognized field`, `budgets.${key}`);
+            throw new errors_2.ValidationError(`budgets.${key} is not a recognized field`, `budgets.${key}`);
         }
     }
     const positive = (v, field) => {
         if (v === undefined)
             return;
         if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) {
-            throw new errors_1.ValidationError(`budgets.${field} must be a positive number`, `budgets.${field}`);
+            throw new errors_2.ValidationError(`budgets.${field} must be a positive number`, `budgets.${field}`);
         }
     };
     const fraction = (v, field) => {
         if (v === undefined)
             return;
         if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0 || v > 1) {
-            throw new errors_1.ValidationError(`budgets.${field} must be a fraction in (0, 1]`, `budgets.${field}`);
+            throw new errors_2.ValidationError(`budgets.${field} must be a fraction in (0, 1]`, `budgets.${field}`);
         }
     };
     positive(budgets.daily, 'daily');
@@ -147,18 +172,24 @@ class OneShot {
             const walletProvider = new ethers_2.EthersWalletProvider(config.privateKey, rpcProvider);
             return new OneShot(config, walletProvider);
         }
-        throw new errors_1.ValidationError('Provide one of: privateKey, cdp, or walletProvider', 'config');
+        throw new errors_2.ValidationError('Provide one of: privateKey, cdp, or walletProvider', 'config');
     }
     /**
      * Sync constructor — works with privateKey (backwards compatible).
      * For CDP wallets, use OneShot.create() instead.
      */
     constructor(config, walletProvider) {
+        /** ETH mode: signed payments not yet observed as settled, keyed by reservation id. */
+        this._usdcPending = new Map();
+        this._usdcReservationSeq = 0;
+        /** ETH mode: serializes read → decide → swap → reserve per instance (also prevents concurrent swap nonce races). */
+        this._usdcLock = Promise.resolve();
         this.baseUrl = config.baseUrl ?? BASE_URL;
         this.debug = config.debug ?? false;
         this.logger = config.logger ?? console.log;
         this._currency = config.currency ?? 'USDC';
         this._slippage = config.slippage ?? 0.01;
+        this._swapBufferMultiplier = validateSwapBufferMultiplier(config.swapBufferMultiplier);
         this._budgets = validateBudgetConfig(config.budgets);
         this._alertEmail = config.alerts?.email;
         this.rpcProvider = new ethers_1.ethers.JsonRpcProvider(config.rpcUrl ?? RPC_URL);
@@ -169,10 +200,10 @@ class OneShot {
             this.provider = new ethers_2.EthersWalletProvider(config.privateKey, this.rpcProvider);
         }
         else {
-            throw new errors_1.ValidationError('Provide privateKey or use OneShot.create() for CDP/custom wallets', 'config');
+            throw new errors_2.ValidationError('Provide privateKey or use OneShot.create() for CDP/custom wallets', 'config');
         }
         if (this._currency === 'ETH' && !this.provider.sendTransaction) {
-            throw new errors_1.ValidationError('ETH currency mode requires a wallet provider that supports sendTransaction', 'currency');
+            throw new errors_2.ValidationError('ETH currency mode requires a wallet provider that supports sendTransaction', 'currency');
         }
         if (this.debug) {
             this.log(`SDK initialized — chain=${CHAIN_ID} currency=${this._currency}`);
@@ -196,6 +227,10 @@ class OneShot {
     get slippage() {
         return this._slippage;
     }
+    /** ETH mode: how many payments' worth of USDC a swap buys (default 10). */
+    get swapBufferMultiplier() {
+        return this._swapBufferMultiplier;
+    }
     /** The budget config this instance was constructed with, if any. */
     get budgetConfig() {
         return this._budgets;
@@ -280,7 +315,7 @@ class OneShot {
             headers: this.headers(),
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to list domains', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list domains', response.status, await response.text());
         }
         return response.json();
     }
@@ -292,7 +327,7 @@ class OneShot {
             headers: this.headers(),
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to pause domain', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to pause domain', response.status, await response.text());
         }
         return response.json();
     }
@@ -304,7 +339,7 @@ class OneShot {
             headers: this.headers(),
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to resume domain', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to resume domain', response.status, await response.text());
         }
         return response.json();
     }
@@ -317,7 +352,7 @@ class OneShot {
     }
     async enrichProfile(options) {
         if (!options.linkedin_url && !options.email && !options.name) {
-            throw new errors_1.ValidationError('At least one of linkedin_url, email, or name is required', 'identifier');
+            throw new errors_2.ValidationError('At least one of linkedin_url, email, or name is required', 'identifier');
         }
         return this.tool('enrich/profile', { ...options });
     }
@@ -326,14 +361,58 @@ class OneShot {
     }
     async enrichCompany(options) {
         if (!options.domain && !options.name && !options.linkedin_url && !options.ticker) {
-            throw new errors_1.ValidationError('At least one of domain, name, linkedin_url, or ticker is required', 'identifier');
+            throw new errors_2.ValidationError('At least one of domain, name, linkedin_url, or ticker is required', 'identifier');
         }
         return this.tool('enrich/company', { ...options });
     }
+    /**
+     * Discover local businesses (restaurants, contractors, practices) by
+     * category/keywords × location. Flat price per search, not per row.
+     */
+    async localSearch(options) {
+        if (!options.location || options.location.length === 0) {
+            throw new errors_2.ValidationError('location is required (e.g. ["Austin, TX"])', 'location');
+        }
+        if (!(options.category && options.category.length) && !(options.keywords && options.keywords.length)) {
+            throw new errors_2.ValidationError('At least one of category or keywords is required', 'category');
+        }
+        return this.tool('local/search', { ...options, limit: options.limit ?? 100 });
+    }
+    /**
+     * Resolve a business name + one locating field to its domain, phone,
+     * category and operating status. A miss resolves with `found: false`
+     * (a completed job), never a rejection.
+     */
+    async localResolve(options) {
+        this.validate(options.name, 'name');
+        if (!options.address && !options.city && !options.postal_code && !options.phone) {
+            throw new errors_2.ValidationError('name plus at least one of address, city, postal_code, or phone is required', 'address');
+        }
+        return this.tool('local/resolve', { ...options });
+    }
+    /**
+     * Federal contract opportunities (SAM.gov) by NAICS code — Sources Sought
+     * and Presolicitation notices with the contracting officer's published
+     * contact. Flat price per search; zero notices is a completed result.
+     */
+    async govSolicitations(options) {
+        if (!options.naics || options.naics.length === 0) {
+            throw new errors_2.ValidationError('naics is required (one or more 6-digit codes, e.g. ["541511"])', 'naics');
+        }
+        const bad = options.naics.find(c => !/^\d{6}$/.test(String(c)));
+        if (bad !== undefined) {
+            throw new errors_2.ValidationError(`NAICS codes are 6 digits (got ${JSON.stringify(bad)})`, 'naics');
+        }
+        return this.tool('gov/solicitations', {
+            ...options,
+            notice_types: options.notice_types ?? ['r', 'p'],
+            limit: options.limit ?? 100,
+        });
+    }
     async findEmail(options) {
         this.validate(options.company_domain, 'company_domain');
         if (!options.full_name && !(options.first_name && options.last_name)) {
-            throw new errors_1.ValidationError('Either full_name or both first_name and last_name required', 'name');
+            throw new errors_2.ValidationError('Either full_name or both first_name and last_name required', 'name');
         }
         return this.tool('enrich/email', { ...options });
     }
@@ -343,13 +422,13 @@ class OneShot {
     }
     async deepResearchPerson(options) {
         if (!options.email && !options.social_media_url && !options.name) {
-            throw new errors_1.ValidationError('At least one of email, social_media_url, or name is required', 'identifier');
+            throw new errors_2.ValidationError('At least one of email, social_media_url, or name is required', 'identifier');
         }
         return this.tool('research/person', { ...options });
     }
     async socialProfiles(options) {
         if (!options.email && !options.social_media_url) {
-            throw new errors_1.ValidationError('At least one of email or social_media_url is required', 'identifier');
+            throw new errors_2.ValidationError('At least one of email or social_media_url is required', 'identifier');
         }
         return this.tool('research/social', { ...options });
     }
@@ -364,7 +443,7 @@ class OneShot {
     }
     async personInterests(options) {
         if (!options.email && !options.phone && !options.social_media_url) {
-            throw new errors_1.ValidationError('At least one of email, phone, or social_media_url is required', 'identifier');
+            throw new errors_2.ValidationError('At least one of email, phone, or social_media_url is required', 'identifier');
         }
         return this.tool('research/interests', { ...options });
     }
@@ -382,7 +461,7 @@ class OneShot {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to list inbox', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list inbox', response.status, await response.text());
         }
         return response.json();
     }
@@ -392,10 +471,10 @@ class OneShot {
             headers: await this.signedReadHeaders()
         });
         if (response.status === 404) {
-            throw new errors_1.ToolError('Email not found', 404, 'Email not found');
+            throw new errors_2.ToolError('Email not found', 404, 'Email not found');
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to get email', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get email', response.status, await response.text());
         }
         return response.json();
     }
@@ -460,13 +539,13 @@ class OneShot {
         this.validate(options.objective, 'objective');
         this.validate(options.target_number, 'target_number');
         if (Array.isArray(options.target_number) && options.target_number.length === 0) {
-            throw new errors_1.ValidationError('target_number array cannot be empty', 'target_number');
+            throw new errors_2.ValidationError('target_number array cannot be empty', 'target_number');
         }
         if (options.objective.length < 10) {
-            throw new errors_1.ValidationError('Objective must be at least 10 characters', 'objective');
+            throw new errors_2.ValidationError('Objective must be at least 10 characters', 'objective');
         }
         if (options.max_duration_minutes !== undefined && (options.max_duration_minutes < 1 || options.max_duration_minutes > 30)) {
-            throw new errors_1.ValidationError('max_duration_minutes must be between 1 and 30', 'max_duration_minutes');
+            throw new errors_2.ValidationError('max_duration_minutes must be between 1 and 30', 'max_duration_minutes');
         }
         const payload = {
             objective: options.objective,
@@ -489,12 +568,12 @@ class OneShot {
             on400: async (resp) => {
                 const errorData = await resp.json();
                 if (errorData.error === 'content_blocked') {
-                    throw new errors_1.ContentBlockedError(errorData.message, errorData.categories || []);
+                    throw new errors_2.ContentBlockedError(errorData.message, errorData.categories || []);
                 }
                 if (errorData.error === 'emergency_number_blocked') {
-                    throw new errors_1.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
+                    throw new errors_2.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
                 }
-                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+                throw new errors_2.ValidationError(errorData.message || 'Invalid request', 'request');
             },
         });
         if (callResp.status !== 202) {
@@ -523,17 +602,17 @@ class OneShot {
         this.validate(options.message, 'message');
         this.validate(options.to_number, 'to_number');
         if (Array.isArray(options.to_number) && options.to_number.length === 0) {
-            throw new errors_1.ValidationError('to_number array cannot be empty', 'to_number');
+            throw new errors_2.ValidationError('to_number array cannot be empty', 'to_number');
         }
         if (options.message.length < 1) {
-            throw new errors_1.ValidationError('Message is required', 'message');
+            throw new errors_2.ValidationError('Message is required', 'message');
         }
         if (options.message.length > 1600) {
-            throw new errors_1.ValidationError('Message must be 1600 characters or less', 'message');
+            throw new errors_2.ValidationError('Message must be 1600 characters or less', 'message');
         }
         const recipientCount = Array.isArray(options.to_number) ? options.to_number.length : 1;
         if (recipientCount > 10) {
-            throw new errors_1.ValidationError('Maximum 10 recipients allowed', 'to_number');
+            throw new errors_2.ValidationError('Maximum 10 recipients allowed', 'to_number');
         }
         const payload = {
             message: options.message,
@@ -551,12 +630,12 @@ class OneShot {
             on400: async (resp) => {
                 const errorData = await resp.json();
                 if (errorData.error === 'content_blocked') {
-                    throw new errors_1.ContentBlockedError(errorData.message, errorData.categories || []);
+                    throw new errors_2.ContentBlockedError(errorData.message, errorData.categories || []);
                 }
                 if (errorData.error === 'emergency_number_blocked') {
-                    throw new errors_1.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
+                    throw new errors_2.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
                 }
-                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+                throw new errors_2.ValidationError(errorData.message || 'Invalid request', 'request');
             },
         });
         if (sendResp.status !== 202) {
@@ -590,7 +669,7 @@ class OneShot {
         this.validate(options.product?.name, 'product.name');
         this.validate(options.product?.description, 'product.description');
         if (options.product.description.length < 10) {
-            throw new errors_1.ValidationError('Product description must be at least 10 characters', 'product.description');
+            throw new errors_2.ValidationError('Product description must be at least 10 characters', 'product.description');
         }
         const payload = {
             type: options.type ?? 'saas',
@@ -625,7 +704,7 @@ class OneShot {
             },
             on400: async (resp) => {
                 const errorData = await resp.json();
-                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+                throw new errors_2.ValidationError(errorData.message || 'Invalid request', 'request');
             },
         });
         if (buildResp.status !== 202) {
@@ -653,10 +732,10 @@ class OneShot {
     async browser(options) {
         this.validate(options.task, 'task');
         if (options.task.length < 10) {
-            throw new errors_1.ValidationError('Task must be at least 10 characters', 'task');
+            throw new errors_2.ValidationError('Task must be at least 10 characters', 'task');
         }
         if (options.max_steps !== undefined && (options.max_steps < 1 || options.max_steps > 100)) {
-            throw new errors_1.ValidationError('max_steps must be between 1 and 100', 'max_steps');
+            throw new errors_2.ValidationError('max_steps must be between 1 and 100', 'max_steps');
         }
         const payload = {
             task: options.task,
@@ -687,7 +766,7 @@ class OneShot {
             onQuote: (ctx) => this.log(`Browser quote: $${ctx.estimated_cost} for ~${ctx.estimated_steps} steps`),
             on400: async (resp) => {
                 const errorData = await resp.json();
-                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+                throw new errors_2.ValidationError(errorData.message || 'Invalid request', 'request');
             },
         });
         if (execResp.status !== 202) {
@@ -717,7 +796,7 @@ class OneShot {
             body: JSON.stringify({ name }),
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to create browser profile', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to create browser profile', response.status, await response.text());
         }
         return response.json();
     }
@@ -737,7 +816,7 @@ class OneShot {
             headers: await this.signedReadHeaders(),
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to list browser profiles', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list browser profiles', response.status, await response.text());
         }
         const data = await response.json();
         return data.profiles;
@@ -757,7 +836,7 @@ class OneShot {
             headers: await this.signedReadHeaders(),
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to delete browser profile', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to delete browser profile', response.status, await response.text());
         }
     }
     /**
@@ -803,7 +882,7 @@ class OneShot {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to list SMS inbox', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list SMS inbox', response.status, await response.text());
         }
         return response.json();
     }
@@ -822,10 +901,10 @@ class OneShot {
             headers: await this.signedReadHeaders()
         });
         if (response.status === 404) {
-            throw new errors_1.ToolError('SMS message not found', 404, 'Message not found');
+            throw new errors_2.ToolError('SMS message not found', 404, 'Message not found');
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to get SMS message', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get SMS message', response.status, await response.text());
         }
         return response.json();
     }
@@ -850,7 +929,7 @@ class OneShot {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to list notifications', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list notifications', response.status, await response.text());
         }
         return response.json();
     }
@@ -869,10 +948,10 @@ class OneShot {
             headers: await this.signedReadHeaders()
         });
         if (response.status === 404) {
-            throw new errors_1.ToolError('Notification not found', 404, 'Notification not found');
+            throw new errors_2.ToolError('Notification not found', 404, 'Notification not found');
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to mark notification as read', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to mark notification as read', response.status, await response.text());
         }
     }
     async getUnifiedBalance() {
@@ -880,7 +959,7 @@ class OneShot {
             headers: await this.signedReadHeaders()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to fetch balance', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to fetch balance', response.status, await response.text());
         }
         return response.json();
     }
@@ -950,9 +1029,9 @@ class OneShot {
             on400: async (resp) => {
                 const errorData = await resp.json();
                 if (errorData.error === 'content_blocked') {
-                    throw new errors_1.ContentBlockedError(errorData.message, []);
+                    throw new errors_2.ContentBlockedError(errorData.message, []);
                 }
-                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+                throw new errors_2.ValidationError(errorData.message || 'Invalid request', 'request');
             },
         });
         if (createResp.status !== 202) {
@@ -975,10 +1054,10 @@ class OneShot {
             headers: this.headers()
         });
         if (response.status === 404) {
-            throw new errors_1.ToolError('Goal not found', 404, 'Goal not found');
+            throw new errors_2.ToolError('Goal not found', 404, 'Goal not found');
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to get compute goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get compute goal', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1000,7 +1079,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to get compute tasks', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get compute tasks', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1020,10 +1099,10 @@ class OneShot {
             headers: this.headers()
         });
         if (response.status === 404) {
-            throw new errors_1.ToolError('Budget not found', 404, 'Budget not found for this goal');
+            throw new errors_2.ToolError('Budget not found', 404, 'Budget not found for this goal');
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to get compute budget', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get compute budget', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1045,10 +1124,10 @@ class OneShot {
             body: JSON.stringify({ reason })
         });
         if (response.status === 404) {
-            throw new errors_1.ToolError('Goal not found', 404, 'Goal not found');
+            throw new errors_2.ToolError('Goal not found', 404, 'Goal not found');
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to cancel compute goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to cancel compute goal', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1074,10 +1153,10 @@ class OneShot {
             body: JSON.stringify(input)
         });
         if (response.status === 404) {
-            throw new errors_1.ToolError('Goal or task not found', 404, await response.text());
+            throw new errors_2.ToolError('Goal or task not found', 404, await response.text());
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to respond to compute task', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to respond to compute task', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1098,7 +1177,7 @@ class OneShot {
             body: JSON.stringify({ reason })
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to pause compute goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to pause compute goal', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1120,7 +1199,7 @@ class OneShot {
             body: JSON.stringify({})
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to resume compute goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to resume compute goal', response.status, await response.text());
         }
         const json = await response.json();
         return json.data;
@@ -1140,7 +1219,7 @@ class OneShot {
     async fundComputeGoal(goalId, amount) {
         this.validate(goalId, 'goalId');
         if (!amount || amount <= 0) {
-            throw new errors_1.ValidationError('amount must be a positive number', 'amount');
+            throw new errors_2.ValidationError('amount must be a positive number', 'amount');
         }
         const path = `/v1/compute/${goalId}/fund`;
         const payload = { amount };
@@ -1164,8 +1243,8 @@ class OneShot {
         };
         const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, path, payload, quoteData.context.quote_id);
         paymentInfo.amount = this.chargeAmount(accepted, quoteData.payment_request.amount);
-        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const fundResp = await this.makeRequest(path, payload, auth, quoteData.context.quote_id);
+        const signed = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
+        const fundResp = await this.makePaidRequest(signed, path, payload, quoteData.context.quote_id);
         if (!fundResp.ok) {
             await this.failFromResponse('Failed to fund compute goal', fundResp);
         }
@@ -1193,7 +1272,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to get spend breakdown', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get spend breakdown', response.status, await response.text());
         }
         return response.json();
     }
@@ -1212,7 +1291,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to get RoCS', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get RoCS', response.status, await response.text());
         }
         return response.json();
     }
@@ -1248,7 +1327,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to list receipts', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to list receipts', response.status, await response.text());
         }
         return response.json();
     }
@@ -1287,7 +1366,7 @@ class OneShot {
                 body: JSON.stringify({ goal_id: ref.goalId, ...valueTag }),
             });
             if (!response.ok) {
-                throw new errors_1.ToolError('Failed to record outcome value', response.status, await response.text());
+                throw new errors_2.ToolError('Failed to record outcome value', response.status, await response.text());
             }
             return;
         }
@@ -1299,10 +1378,10 @@ class OneShot {
             body: JSON.stringify(valueTag)
         });
         if (response.status === 404) {
-            throw new errors_1.ToolError('Receipt not found', 404, 'Receipt not found or not owned by this agent');
+            throw new errors_2.ToolError('Receipt not found', 404, 'Receipt not found or not owned by this agent');
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to tag receipt value', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to tag receipt value', response.status, await response.text());
         }
     }
     /**
@@ -1328,7 +1407,7 @@ class OneShot {
             headers: this.headers()
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to get RoCS by goal', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to get RoCS by goal', response.status, await response.text());
         }
         return response.json();
     }
@@ -1341,7 +1420,7 @@ class OneShot {
     }
     validate(value, field) {
         if (!value)
-            throw new errors_1.ValidationError(`${field} is required`, field);
+            throw new errors_2.ValidationError(`${field} is required`, field);
     }
     headers() {
         return {
@@ -1435,11 +1514,11 @@ class OneShot {
                 });
             }
             catch (err) {
-                throw new errors_1.BudgetSyncError(`Could not sync spend budget (network): ${err}`);
+                throw new errors_2.BudgetSyncError(`Could not sync spend budget (network): ${err}`);
             }
             if (!response.ok) {
                 const text = await response.text();
-                throw new errors_1.BudgetSyncError(`Could not sync spend budget (${response.status}): ${text}`, response.status, text);
+                throw new errors_2.BudgetSyncError(`Could not sync spend budget (${response.status}): ${text}`, response.status, text);
             }
             this.log('Budget synced');
         })();
@@ -1467,7 +1546,7 @@ class OneShot {
             return;
         const amount = parseFloat(total);
         if (Number.isFinite(amount) && amount > cap) {
-            throw new errors_1.BudgetExceededError(`Quote $${total} exceeds this agent's per-transaction budget of $${cap}`, 'per_transaction', cap, undefined, amount);
+            throw new errors_2.BudgetExceededError(`Quote $${total} exceeds this agent's per-transaction budget of $${cap}`, 'per_transaction', cap, undefined, amount);
         }
     }
     /**
@@ -1484,7 +1563,7 @@ class OneShot {
             headers: await this.signedReadHeaders(),
         });
         if (!response.ok) {
-            throw new errors_1.ToolError('Failed to fetch budgets', response.status, await response.text());
+            throw new errors_2.ToolError('Failed to fetch budgets', response.status, await response.text());
         }
         const body = await response.json();
         return (body.data ?? body);
@@ -1492,7 +1571,7 @@ class OneShot {
     /** Local fast-fail guard: throw when a quote total exceeds the caller's cap. */
     assertWithinMaxCost(total, maxCost) {
         if (maxCost && parseFloat(total) > maxCost) {
-            throw new errors_1.OneShotError(`Quote $${total} exceeds maxCost $${maxCost}`);
+            throw new errors_2.OneShotError(`Quote $${total} exceeds maxCost $${maxCost}`);
         }
     }
     /**
@@ -1538,7 +1617,7 @@ class OneShot {
         const budget = response.status === 403 ? this.parseBudgetRejection(text) : undefined;
         if (budget)
             throw budget;
-        throw new errors_1.ToolError(message, response.status, text);
+        throw new errors_2.ToolError(message, response.status, text);
     }
     /**
      * Map a 403 `budget_exceeded` body onto a typed error, so callers can catch
@@ -1551,7 +1630,7 @@ class OneShot {
             if (body.error !== 'budget_exceeded')
                 return undefined;
             const b = body.budget ?? {};
-            return new errors_1.BudgetExceededError(body.message ?? 'Agent spend budget exceeded', b.reason === 'per_transaction' ? 'per_transaction' : 'daily', b.cap !== undefined ? parseFloat(b.cap) : undefined, b.spent !== undefined ? parseFloat(b.spent) : undefined, b.charge !== undefined ? parseFloat(b.charge) : undefined, b.resets_at);
+            return new errors_2.BudgetExceededError(body.message ?? 'Agent spend budget exceeded', b.reason === 'per_transaction' ? 'per_transaction' : 'daily', b.cap !== undefined ? parseFloat(b.cap) : undefined, b.spent !== undefined ? parseFloat(b.spent) : undefined, b.charge !== undefined ? parseFloat(b.charge) : undefined, b.resets_at);
         }
         catch {
             return undefined;
@@ -1574,7 +1653,7 @@ class OneShot {
             expectedAmount ? `expected $${expectedAmount}` : null,
             receivedAmount ? `signed $${receivedAmount}` : null,
         ].filter(Boolean).join(', ');
-        return new errors_1.PaymentError(`payment rejected: ${reason}${detail ? ` — ${detail}` : ''}${data.message ? ` (${data.message})` : ''}`, reason, {
+        return new errors_2.PaymentError(`payment rejected: ${reason}${detail ? ` — ${detail}` : ''}${data.message ? ` (${data.message})` : ''}`, reason, {
             amount: expectedAmount,
             asset: data.expected?.asset,
             network: data.expected?.network,
@@ -1610,8 +1689,59 @@ class OneShot {
             return undefined;
         return { 'Idempotency-Key': idempotencyKey };
     }
+    async readReliabilityJson(path, signed, allowDegraded = false) {
+        const scope = (0, deadline_1.deadlineScope)(undefined, signed ? 10000 : 5000);
+        try {
+            return await (0, deadline_1.abortable)((async () => {
+                const headers = signed ? await this.signedReadHeaders() : undefined;
+                if (scope.signal.aborted)
+                    throw new errors_2.OneShotError('Read deadline exceeded');
+                const response = await fetch(`${this.baseUrl}${path}`, { headers, signal: scope.signal });
+                if (!response.ok && !(allowDegraded && response.status === 503))
+                    await this.failFromResponse('Reliability read failed', response);
+                return await response.json();
+            })(), scope.signal);
+        }
+        finally {
+            scope.close();
+        }
+    }
+    async recoverRequest(options) {
+        const query = new URLSearchParams({ endpoint: options.endpoint, key: options.idempotencyKey });
+        return this.readReliabilityJson(`/v1/submissions/recover?${query}`, true);
+    }
+    async getServiceStatus() {
+        return this.readReliabilityJson('/v1/status', false, true);
+    }
     async executeToolRequest(endpoint, options, quoteId) {
-        const { signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, idempotencyKey, maxCost, ...payload } = options;
+        const reliable = /(?:^|\/)(enrich\/(profile|email)|verify\/email)$/.test(endpoint);
+        const key = options.idempotencyKey ?? (reliable ? ethers_1.ethers.hexlify(ethers_1.ethers.randomBytes(16)) : undefined);
+        if (options.totalTimeoutMs !== undefined && (!Number.isFinite(options.totalTimeoutMs) || options.totalTimeoutMs <= 0)) {
+            throw new errors_2.ValidationError('totalTimeoutMs must be positive', 'totalTimeoutMs');
+        }
+        const scope = (0, deadline_1.deadlineScope)(options.signal, options.totalTimeoutMs);
+        const context = { phase: 'initialization' };
+        const started = Date.now();
+        try {
+            if (scope.signal.aborted)
+                throw new errors_2.OneShotError('Operation cancelled');
+            if (key)
+                options.onRequestCreated?.({ idempotencyKey: key });
+            return await (0, deadline_1.abortable)(this.executeToolRequestImpl(endpoint, { ...options, idempotencyKey: key, signal: scope.signal }, quoteId, context), scope.signal);
+        }
+        catch (error) {
+            if (scope.timedOut())
+                throw new errors_1.RequestTimeoutError(Date.now() - started, context.phase, key, context.requestId, context.receiptId);
+            if (error instanceof Error)
+                Object.assign(error, { idempotencyKey: key, requestId: context.requestId, receiptId: context.receiptId, phase: context.phase });
+            throw error;
+        }
+        finally {
+            scope.close();
+        }
+    }
+    async executeToolRequestImpl(endpoint, options, quoteId, context = { phase: "initialization" }) {
+        const { totalTimeoutMs, onRequestCreated, onAccepted, signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, idempotencyKey, maxCost, ...payload } = options;
         const extraHeaders = {
             ...this.maxCostHeader(maxCost),
             ...this.idempotencyHeader(idempotencyKey),
@@ -1640,11 +1770,18 @@ class OneShot {
             }
         }
         if (signal?.aborted) {
-            throw new errors_1.OneShotError('Operation cancelled');
+            throw new errors_2.OneShotError('Operation cancelled');
         }
         // One-time push of config.budgets before the first paid call, so the
         // server-side gate knows about them on this very request.
         await this.ensureBudgetsSynced();
+        if (signal?.aborted)
+            throw new errors_2.OneShotError('Operation cancelled');
+        if (idempotencyKey)
+            Object.assign(extraHeaders, { 'x-agent-proof': 'required' });
+        if (signal?.aborted)
+            throw new errors_2.OneShotError('Operation cancelled');
+        context.phase = 'submission';
         let response = await this.makeRequest(endpoint, payload, undefined, quoteId, signal, undefined, extraHeaders);
         // Handle 402 Payment Required
         if (response.status === 402) {
@@ -1665,8 +1802,11 @@ class OneShot {
             this.log(`Payment required: ${paymentInfo.amount} USDC`);
             this.assertWithinBudget(paymentInfo.amount);
             this.checkAbortBeforePayment(signal);
-            const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-            response = await this.makeRequest(endpoint, payload, auth, quoteId, signal, undefined, extraHeaders);
+            context.phase = 'payment';
+            const signed = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
+            this.checkAbortBeforePayment(signal);
+            context.phase = 'submission';
+            response = await this.makePaidRequest(signed, endpoint, payload, quoteId, signal, undefined, extraHeaders);
         }
         if (!response.ok) {
             await this.failFromResponse('Tool request failed', response);
@@ -1674,11 +1814,19 @@ class OneShot {
         const result = await response.json();
         // Handle async jobs
         if ((result.status === 'pending' || result.status === 'processing') && result.request_id) {
+            context.requestId = String(result.request_id);
+            context.receiptId = typeof result.receipt_id === 'string' ? result.receipt_id : undefined;
+            onAccepted?.({ request_id: context.requestId, receipt_id: context.receiptId, idempotencyKey });
+            context.phase = 'polling';
             this.log(`Job queued: ${result.request_id}`);
             if (!wait) {
-                return { request_id: result.request_id, status: result.status };
+                return { ...result, idempotencyKey };
+            }
+            const completed = await this.pollJob(result.request_id, options.timeout, signal, onStatusUpdate, waitForPhones ? { waitForPhones, phoneTimeoutSec } : undefined);
+            if (completed && typeof completed === 'object' && !Array.isArray(completed)) {
+                return { ...completed, request_id: context.requestId, receipt_id: completed.receipt_id ?? context.receiptId, idempotencyKey };
             }
-            return this.pollJob(result.request_id, options.timeout, signal, onStatusUpdate, waitForPhones ? { waitForPhones, phoneTimeoutSec } : undefined);
+            return completed;
         }
         return (result.data ?? result);
     }
@@ -1716,8 +1864,8 @@ class OneShot {
         this.checkAbortBeforePayment(cfg.signal);
         const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal);
         paymentInfo.amount = this.chargeAmount(accepted, quoteData.payment_request.amount);
-        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const execResp = await this.makeRequest(cfg.endpoint, cfg.payload, auth, quoteData.context.quote_id, cfg.signal, cfg.execTimeoutMs);
+        const signed = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
+        const execResp = await this.makePaidRequest(signed, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal, cfg.execTimeoutMs);
         return { context: quoteData.context, execResp };
     }
     /**
@@ -1757,7 +1905,7 @@ class OneShot {
         const wsBranch = this.waitViaWebSocket(requestId, inner.signal, emit, wait).catch((err) => {
             // A failed job or a cancellation is a real outcome. Anything else is a
             // transport problem: never settle the race on it, HTTP carries on.
-            if (err instanceof errors_1.OneShotError)
+            if (err instanceof errors_2.OneShotError)
                 throw err;
             this.log(`WebSocket unavailable (${err instanceof Error ? err.message : String(err)}) — relying on HTTP polling`);
             return new Promise(() => { });
@@ -1827,7 +1975,7 @@ class OneShot {
         let lastResult = initialResult;
         while (Date.now() < deadline) {
             if (signal?.aborted)
-                throw new errors_1.OneShotError('Operation cancelled');
+                throw new errors_2.OneShotError('Operation cancelled');
             try {
                 const resp = await fetch(`${this.baseUrl}/v1/requests/${requestId}`, {
                     headers: this.headers(),
@@ -1838,7 +1986,7 @@ class OneShot {
                     // whatever we last had so consumers don't lose the sync result.
                     if (lastResult !== undefined)
                         return lastResult;
-                    throw new errors_1.ToolError('Failed to check job status', resp.status, await resp.text());
+                    throw new errors_2.ToolError('Failed to check job status', resp.status, await resp.text());
                 }
                 const job = await resp.json();
                 lastResult = (job.result ?? job);
@@ -1847,7 +1995,7 @@ class OneShot {
                 }
             }
             catch (err) {
-                if (err instanceof errors_1.OneShotError)
+                if (err instanceof errors_2.OneShotError)
                     throw err;
                 if (lastResult !== undefined)
                     return lastResult;
@@ -1873,7 +2021,7 @@ class OneShot {
                 return reject(new Error('WebSocket not available'));
             }
             if (signal.aborted) {
-                return reject(new errors_1.OneShotError('Operation cancelled'));
+                return reject(new errors_2.OneShotError('Operation cancelled'));
             }
             const wsUrl = this.baseUrl.replace(/^http/, 'ws') +
                 `/v1/requests/subscribe?wallet=${encodeURIComponent(this.provider.address)}`;
@@ -1901,7 +2049,7 @@ class OneShot {
             const onAbort = () => {
                 settle(() => {
                     cleanup();
-                    reject(new errors_1.OneShotError('Operation cancelled'));
+                    reject(new errors_2.OneShotError('Operation cancelled'));
                 });
             };
             signal.addEventListener('abort', onAbort, { once: true });
@@ -1934,7 +2082,7 @@ class OneShot {
                         settle(() => {
                             cleanup();
                             wait.via = 'ws';
-                            reject(new errors_1.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown'), msg.error_code));
+                            reject(new errors_2.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown'), msg.error_code));
                         });
                     }
                     else {
@@ -1967,6 +2115,21 @@ class OneShot {
      * Owns the caller's deadline (`JobTimeoutError`).
      */
     async pollJobHttp(requestId, timeoutSec, signal, emit, wait) {
+        const scope = (0, deadline_1.deadlineScope)(signal, (timeoutSec ?? 120) * 1000);
+        const started = Date.now();
+        try {
+            return await (0, deadline_1.abortable)(this.pollJobHttpImpl(requestId, timeoutSec, scope.signal, emit, wait), scope.signal);
+        }
+        catch (error) {
+            if (scope.timedOut())
+                throw new errors_2.JobTimeoutError(requestId, Date.now() - started);
+            throw error;
+        }
+        finally {
+            scope.close();
+        }
+    }
+    async pollJobHttpImpl(requestId, timeoutSec, signal, emit, wait) {
         const maxWaitMs = (timeoutSec ?? 120) * 1000;
         const startTime = Date.now();
         let retries = 0;
@@ -1974,7 +2137,7 @@ class OneShot {
         let polls = 0;
         while (Date.now() - startTime < maxWaitMs) {
             if (signal?.aborted)
-                throw new errors_1.OneShotError('Operation cancelled');
+                throw new errors_2.OneShotError('Operation cancelled');
             try {
                 const resp = await fetch(`${this.baseUrl}/v1/requests/${requestId}`, {
                     headers: this.headers(),
@@ -1987,7 +2150,7 @@ class OneShot {
                     if (resp.status >= 500 || resp.status === 429) {
                         throw new Error(`Poll returned ${resp.status}: ${body.slice(0, 200)}`);
                     }
-                    throw new errors_1.ToolError('Failed to check job status', resp.status, body);
+                    throw new errors_2.ToolError('Failed to check job status', resp.status, body);
                 }
                 const job = await resp.json();
                 if (job.status === 'completed') {
@@ -1999,12 +2162,18 @@ class OneShot {
                     if (job.request_id && typeof result === 'object' && result !== null && !('request_id' in result)) {
                         result.request_id = job.request_id;
                     }
+                    if (result && typeof result === 'object' && !Array.isArray(result)) {
+                        if (job.receipt_id && !result.receipt_id)
+                            result.receipt_id = job.receipt_id;
+                        if (job.settlement_status && !result.settlement_status)
+                            result.settlement_status = job.settlement_status;
+                    }
                     return result;
                 }
                 if (job.status === 'failed') {
                     if (wait)
                         wait.via = 'http';
-                    throw new errors_1.JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'), job.error_code);
+                    throw new errors_2.JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'), job.error_code);
                 }
                 emit?.(String(job.status));
                 retries = 0;
@@ -2018,27 +2187,27 @@ class OneShot {
                 await this.sleep(Math.min(interval, remaining), signal);
             }
             catch (err) {
-                if (err instanceof errors_1.OneShotError)
+                if (err instanceof errors_2.OneShotError)
                     throw err;
                 if (++retries > maxRetries) {
-                    throw new errors_1.OneShotError(`Polling failed after ${maxRetries} retries: ${err}`);
+                    throw new errors_2.OneShotError(`Polling failed after ${maxRetries} retries: ${err}`);
                 }
                 const backoff = 2000 * Math.pow(2, retries - 1);
                 this.log(`Retry ${retries}/${maxRetries} in ${backoff}ms`);
                 await this.sleep(backoff, signal);
             }
         }
-        throw new errors_1.JobTimeoutError(requestId, Date.now() - startTime);
+        throw new errors_2.JobTimeoutError(requestId, Date.now() - startTime);
     }
     sleep(ms, signal) {
         return new Promise((resolve, reject) => {
             if (signal?.aborted) {
-                return reject(new errors_1.OneShotError('Operation cancelled'));
+                return reject(new errors_2.OneShotError('Operation cancelled'));
             }
-            const timer = setTimeout(resolve, ms);
+            const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
             const onAbort = () => {
                 clearTimeout(timer);
-                reject(new errors_1.OneShotError('Operation cancelled'));
+                reject(new errors_2.OneShotError('Operation cancelled'));
             };
             signal?.addEventListener('abort', onAbort, { once: true });
         });
@@ -2047,7 +2216,8 @@ class OneShot {
         const headers = {
             'Content-Type': 'application/json',
             ...this.headers(),
-            ...(extraHeaders ?? {})
+            ...(extraHeaders ?? {}),
+            ...(extraHeaders?.['x-agent-proof'] ? await this.signedReadHeaders(/(enrich\/(profile|email)|verify\/email)$/.test(endpoint) ? 'submit' : 'read') : {})
         };
         if (payment) {
             const paymentJson = JSON.stringify(payment);
@@ -2058,42 +2228,179 @@ class OneShot {
         }
         if (quoteId)
             headers['x-quote-id'] = quoteId;
-        let fetchSignal = signal;
-        let timeoutId;
-        if (timeoutMs && !signal) {
-            const controller = new AbortController();
-            timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-            fetchSignal = controller.signal;
-        }
+        const transportDeadline = timeoutMs === undefined ? undefined : (0, deadline_1.deadlineScope)(signal, timeoutMs);
+        const fetchSignal = transportDeadline?.signal ?? signal;
+        // Node 18 compatibility: do not require AbortSignal.any. Retain the deadline
+        // through response-body consumption; cleanup occurs when it expires/aborts.
+        transportDeadline?.signal.addEventListener('abort', () => transportDeadline.close(), { once: true });
+        if (fetchSignal?.aborted)
+            throw new errors_2.OneShotError('Operation cancelled');
+        const work = fetch(`${this.baseUrl}${endpoint}`, {
+            method: 'POST', headers, body: JSON.stringify(data), signal: fetchSignal,
+        });
         try {
-            return await fetch(`${this.baseUrl}${endpoint}`, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify(data),
-                signal: fetchSignal
-            });
+            return await (fetchSignal ? (0, deadline_1.abortable)(work, fetchSignal) : work);
         }
-        finally {
-            if (timeoutId)
-                clearTimeout(timeoutId);
+        catch (error) {
+            transportDeadline?.close();
+            throw error;
         }
     }
     checkAbortBeforePayment(signal) {
         if (signal?.aborted) {
-            throw new errors_1.OneShotError('Operation cancelled before payment');
+            throw new errors_2.OneShotError('Operation cancelled before payment');
         }
     }
+    // ---------------------------------------------------------------------------
+    // ETH-currency mode: USDC ledger + buffered swaps
+    // ---------------------------------------------------------------------------
     /**
-     * If currency is ETH, swap ETH→USDC to ensure the wallet has enough USDC for payment.
-     * This is called before signing the x402 payment authorization.
+     * ETH mode only. Make sure the wallet's *effective* USDC (on-chain balance
+     * minus payments signed but not yet settled) covers this charge, swapping
+     * ETH→USDC for a buffer of `swapBufferMultiplier` payments when it does not,
+     * then reserve the charge. Returns the reservation so the caller can release
+     * it if the payment never settles (request failed). Runs under a per-instance
+     * lock so concurrent calls never double-swap or race the wallet nonce.
      */
     async ensureUsdcBalance(paymentInfo) {
         if (this._currency !== 'ETH')
-            return;
+            return undefined;
+        const { chainId, usdcAddress } = this.assertEthModeSupported(paymentInfo);
+        const charge = ethers_1.ethers.parseUnits(paymentInfo.amount, paymentInfo.token.decimals);
+        return this.withUsdcLock(async () => {
+            let balance = await this.readUsdcBalance(usdcAddress);
+            const effective = this.effectiveUsdcBalance(balance);
+            if (effective >= charge) {
+                this.log(`USDC balance covers payment (${ethers_1.ethers.formatUnits(effective, 6)} available for ${paymentInfo.amount}); skipping ETH swap`);
+            }
+            else {
+                const swapAmount = await this.sizeSwap(charge, effective, chainId);
+                const swapAmountStr = ethers_1.ethers.formatUnits(swapAmount, 6);
+                this.log(`USDC ${ethers_1.ethers.formatUnits(effective, 6)} is below ${paymentInfo.amount}; swapping ETH→USDC for ${swapAmountStr} USDC (${this._swapBufferMultiplier}x buffer, slippage: ${this._slippage * 100}%)`);
+                try {
+                    const result = await this.executeUsdcSwap(swapAmountStr, chainId);
+                    balance += result.usdcReceived;
+                    // exactOutput delivers exactly amountOut and tx.wait() has confirmed it.
+                    this._usdcBalanceCache = { balance, at: Date.now() };
+                    this.log(`Swap complete: tx=${result.txHash}, USDC received=${ethers_1.ethers.formatUnits(result.usdcReceived, 6)}`);
+                }
+                catch (err) {
+                    this._usdcBalanceCache = undefined;
+                    throw err;
+                }
+            }
+            return this.reserveUsdc(charge);
+        });
+    }
+    /** ETH mode is Base-mainnet-only (that is where the Uniswap route lives); fail clearly before any RPC. */
+    assertEthModeSupported(paymentInfo) {
+        const chainId = chainIdFromNetwork(paymentInfo.network) ?? CHAIN_ID;
+        if (chainId !== CHAIN_ID) {
+            throw new errors_2.ValidationError(`ETH currency mode is only supported on Base mainnet (eip155:${CHAIN_ID}); this payment is on ${paymentInfo.network}. Fund the wallet with USDC or use currency: 'USDC'.`, 'currency');
+        }
+        const usdcAddress = paymentInfo.token.address;
+        if (usdcAddress.toLowerCase() !== USDC_ADDRESS.toLowerCase()) {
+            throw new errors_2.ValidationError(`ETH→USDC swap buys ${USDC_ADDRESS} but this payment requires ${usdcAddress}`, 'currency');
+        }
+        return { chainId, usdcAddress };
+    }
+    withUsdcLock(fn) {
+        // A failed predecessor must not poison the chain: the waiter runs its own attempt.
+        const run = this._usdcLock.then(fn, fn);
+        this._usdcLock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** On-chain USDC balance (atomic units), deduped within one block. Overridable in tests. */
+    async readUsdcBalance(usdcAddress) {
+        const cached = this._usdcBalanceCache;
+        if (cached && Date.now() - cached.at < USDC_BALANCE_CACHE_MS)
+            return cached.balance;
+        const usdc = new ethers_1.ethers.Contract(usdcAddress, ERC20_BALANCE_ABI, this.rpcProvider);
+        const balance = BigInt(await usdc.balanceOf(this.provider.address));
+        this._usdcBalanceCache = { balance, at: Date.now() };
+        return balance;
+    }
+    /** `balanceOf − Σ pending` (never negative); drops reservations older than the TTL. */
+    effectiveUsdcBalance(balance) {
+        const cutoff = Date.now() - USDC_RESERVATION_TTL_MS;
+        let pending = 0n;
+        for (const [id, r] of this._usdcPending) {
+            if (r.createdAt < cutoff)
+                this._usdcPending.delete(id);
+            else
+                pending += r.amount;
+        }
+        return balance > pending ? balance - pending : 0n;
+    }
+    reserveUsdc(amount) {
+        const reservation = { id: ++this._usdcReservationSeq, amount, createdAt: Date.now() };
+        this._usdcPending.set(reservation.id, reservation);
+        return reservation;
+    }
+    /** Forget a reservation whose payment will never settle (signing or request failed). */
+    releaseUsdcReservation(reservation) {
+        if (reservation)
+            this._usdcPending.delete(reservation.id);
+    }
+    /**
+     * How much USDC to buy: top up to `charge × swapBufferMultiplier`, counting
+     * whatever effective balance is already there. When the wallet provider
+     * exposes `getBalance` and its ETH cannot cover the buffered quote, fall
+     * back to the bare shortfall so an ETH-poor wallet can still make the one
+     * payment in front of it (a send-only provider always gets the buffer).
+     */
+    async sizeSwap(charge, effective, chainId) {
+        const shortfall = charge - effective;
+        // Integer math on a 10^6 scale (multiplier ≤ 1000, so ≤ 10^9 — always a
+        // finite, exact integer): keeps the multiplier's precision, no float→BigInt
+        // on an unbounded value.
+        const mScaled = BigInt(Math.round(this._swapBufferMultiplier * SWAP_MULTIPLIER_SCALE));
+        const target = (charge * mScaled + BigInt(SWAP_MULTIPLIER_SCALE) - 1n) / BigInt(SWAP_MULTIPLIER_SCALE);
+        let amount = target > effective ? target - effective : shortfall;
+        if (amount > shortfall && this.provider.getBalance) {
+            try {
+                const amountInMax = await this.quoteSwapAmountInMax(ethers_1.ethers.formatUnits(amount, 6), chainId);
+                const eth = await this.provider.getBalance();
+                if (amountInMax !== undefined && eth < amountInMax) {
+                    this.log(`ETH balance cannot cover a ${ethers_1.ethers.formatUnits(amount, 6)} USDC buffer; swapping only the ${ethers_1.ethers.formatUnits(shortfall, 6)} USDC shortfall`);
+                    amount = shortfall;
+                }
+            }
+            catch {
+                // Quoting failed — let executeSwap quote again and report properly.
+            }
+        }
+        return amount;
+    }
+    /** Max ETH the buffered swap could cost (quote), or undefined if unavailable. Overridable in tests. */
+    async quoteSwapAmountInMax(usdcAmount, chainId) {
+        const { getSwapQuote } = await Promise.resolve().then(() => __importStar(require('./swap')));
+        const quote = await getSwapQuote(this.rpcProvider, usdcAmount, chainId, this._slippage);
+        return quote?.amountInMax;
+    }
+    /** Perform the on-chain swap. Overridable in tests. */
+    async executeUsdcSwap(usdcAmount, chainId) {
         const { executeSwap } = await Promise.resolve().then(() => __importStar(require('./swap')));
-        this.log(`Swapping ETH→USDC for ${paymentInfo.amount} USDC (slippage: ${this._slippage * 100}%)`);
-        const result = await executeSwap(this.provider, this.rpcProvider, paymentInfo.amount, CHAIN_ID, this._slippage);
-        this.log(`Swap complete: tx=${result.txHash}, USDC received=${ethers_1.ethers.formatUnits(result.usdcReceived, 6)}`);
+        return executeSwap(this.provider, this.rpcProvider, usdcAmount, chainId, this._slippage);
+    }
+    /**
+     * Send the paid leg of a request. The server settles the authorization only
+     * on acceptance. A transport failure on a durable endpoint is ambiguous;
+     * retain its short-lived ETH-mode reservation until recovery or expiry.
+     */
+    async makePaidRequest(signed, endpoint, data, quoteId, signal, timeoutMs, extraHeaders) {
+        let resp;
+        try {
+            resp = await this.makeRequest(endpoint, data, signed.auth, quoteId, signal, timeoutMs, extraHeaders);
+        }
+        catch (err) {
+            if (!/(enrich\/(profile|email)|verify\/email)$/.test(endpoint))
+                this.releaseUsdcReservation(signed.reservation);
+            throw err;
+        }
+        if (!resp.ok && !(extraHeaders?.['Idempotency-Key'] && resp.status >= 500))
+            this.releaseUsdcReservation(signed.reservation);
+        return resp;
     }
     /** Parse the PAYMENT-REQUIRED header from a 402 response into the accepted requirements and Bazaar metadata. */
     parsePaymentRequired(header) {
@@ -2148,26 +2455,26 @@ class OneShot {
         // always receives a payment-signature header (avoids 402 from x402 SDK).
         if (parseFloat(paymentInfo.amount) === 0) {
             this.log('Credits cover full cost — sending zero-cost authorization');
-            return {
-                x402Version: 2,
-                ...(resource ? { resource } : {}),
-                ...(extensions ? { extensions } : {}),
-                accepted,
-                payload: {
-                    signature: '0x',
-                    authorization: {
-                        from: this.provider.address,
-                        to: paymentInfo.payTo,
-                        value: '0',
-                        validAfter: '0',
-                        validBefore: '0',
-                        nonce: '0x' + '00'.repeat(32),
+            return { auth: {
+                    x402Version: 2,
+                    ...(resource ? { resource } : {}),
+                    ...(extensions ? { extensions } : {}),
+                    accepted,
+                    payload: {
+                        signature: '0x',
+                        authorization: {
+                            from: this.provider.address,
+                            to: paymentInfo.payTo,
+                            value: '0',
+                            validAfter: '0',
+                            validBefore: '0',
+                            nonce: '0x' + '00'.repeat(32),
+                        },
                     },
-                },
-            };
+                } };
         }
-        // If paying with ETH, swap to USDC first
-        await this.ensureUsdcBalance(paymentInfo);
+        // If paying with ETH, make sure USDC covers the charge (swapping a buffer if not) and reserve it
+        const reservation = await this.ensureUsdcBalance(paymentInfo);
         const now = Math.floor(Date.now() / 1000);
         const nonce = ethers_1.ethers.randomBytes(32);
         const value = ethers_1.ethers.parseUnits(paymentInfo.amount, paymentInfo.token.decimals);
@@ -2182,46 +2489,53 @@ class OneShot {
         const domainVersion = accepted.extra?.version || '2';
         const chainId = chainIdFromNetwork(accepted.network ?? paymentInfo.network) ?? CHAIN_ID;
         // Sign EIP-3009 TransferWithAuthorization
-        const signature = await this.provider.signTypedData({
-            name: domainName,
-            version: domainVersion,
-            chainId,
-            verifyingContract: paymentInfo.token.address
-        }, {
-            TransferWithAuthorization: [
-                { name: 'from', type: 'address' },
-                { name: 'to', type: 'address' },
-                { name: 'value', type: 'uint256' },
-                { name: 'validAfter', type: 'uint256' },
-                { name: 'validBefore', type: 'uint256' },
-                { name: 'nonce', type: 'bytes32' }
-            ]
-        }, {
-            from: this.provider.address,
-            to: paymentInfo.payTo,
-            value,
-            validAfter,
-            validBefore,
-            nonce: nonceHex
-        });
+        let signature;
+        try {
+            signature = await this.provider.signTypedData({
+                name: domainName,
+                version: domainVersion,
+                chainId,
+                verifyingContract: paymentInfo.token.address
+            }, {
+                TransferWithAuthorization: [
+                    { name: 'from', type: 'address' },
+                    { name: 'to', type: 'address' },
+                    { name: 'value', type: 'uint256' },
+                    { name: 'validAfter', type: 'uint256' },
+                    { name: 'validBefore', type: 'uint256' },
+                    { name: 'nonce', type: 'bytes32' }
+                ]
+            }, {
+                from: this.provider.address,
+                to: paymentInfo.payTo,
+                value,
+                validAfter,
+                validBefore,
+                nonce: nonceHex
+            });
+        }
+        catch (err) {
+            this.releaseUsdcReservation(reservation);
+            throw err;
+        }
         // Return x402 PaymentPayload v2 format (including resource + extensions for Bazaar discovery)
-        return {
-            x402Version: 2,
-            ...(resource ? { resource } : {}),
-            ...(extensions ? { extensions } : {}),
-            accepted,
-            payload: {
-                signature,
-                authorization: {
-                    from: this.provider.address,
-                    to: paymentInfo.payTo,
-                    value: value.toString(),
-                    validAfter: validAfter.toString(),
-                    validBefore: validBefore.toString(),
-                    nonce: nonceHex,
+        return { reservation, auth: {
+                x402Version: 2,
+                ...(resource ? { resource } : {}),
+                ...(extensions ? { extensions } : {}),
+                accepted,
+                payload: {
+                    signature,
+                    authorization: {
+                        from: this.provider.address,
+                        to: paymentInfo.payTo,
+                        value: value.toString(),
+                        validAfter: validAfter.toString(),
+                        validBefore: validBefore.toString(),
+                        nonce: nonceHex,
+                    },
                 },
-            },
-        };
+            } };
     }
 }
 exports.OneShot = OneShot;