@oneshot-agent/sdk 0.27.0 → 0.29.0

package/dist/index.js

@@ -49,14 +49,44 @@ 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.27.0';
+const SDK_VERSION = '0.29.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. */
+const HTTP_POLL_RELAXED_MS = 5000;
 // ============================================================================
 // Environment Configuration
 // ============================================================================
 const BASE_URL = 'https://win.oneshotagent.com';
 const RPC_URL = 'https://mainnet.base.org';
 const CHAIN_ID = 8453;
+/** Chain id from an x402 network id such as `eip155:84532`; undefined when absent or malformed. */
+function chainIdFromNetwork(network) {
+    const m = /^eip155:(\d+)$/.exec(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;
+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_1.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'`)
@@ -145,11 +175,17 @@ class OneShot {
      * 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);
@@ -162,7 +198,6 @@ class OneShot {
         else {
             throw new errors_1.ValidationError('Provide privateKey or use OneShot.create() for CDP/custom wallets', 'config');
         }
-        // Validate ETH mode requirements
         if (this._currency === 'ETH' && !this.provider.sendTransaction) {
             throw new errors_1.ValidationError('ETH currency mode requires a wallet provider that supports sendTransaction', 'currency');
         }
@@ -188,6 +223,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;
@@ -451,7 +490,6 @@ class OneShot {
     async voice(options) {
         this.validate(options.objective, 'objective');
         this.validate(options.target_number, 'target_number');
-        // Check for empty arrays
         if (Array.isArray(options.target_number) && options.target_number.length === 0) {
             throw new errors_1.ValidationError('target_number array cannot be empty', 'target_number');
         }
@@ -515,7 +553,6 @@ class OneShot {
     async sms(options) {
         this.validate(options.message, 'message');
         this.validate(options.to_number, 'to_number');
-        // Check for empty arrays
         if (Array.isArray(options.to_number) && options.to_number.length === 0) {
             throw new errors_1.ValidationError('to_number array cannot be empty', 'to_number');
         }
@@ -1139,7 +1176,6 @@ class OneShot {
         const path = `/v1/compute/${goalId}/fund`;
         const payload = { amount };
         await this.ensureBudgetsSynced();
-        // First call: get quote (402)
         const quoteResp = await this.makeRequest(path, payload);
         if (quoteResp.status !== 402) {
             // A 403 here is the budget gate on the quote leg → BudgetExceededError.
@@ -1159,8 +1195,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);
         }
@@ -1611,7 +1647,6 @@ class OneShot {
             ...this.maxCostHeader(maxCost),
             ...this.idempotencyHeader(idempotencyKey),
         };
-        // Validate memo
         if (payload.memo !== undefined) {
             if (typeof payload.memo !== 'string' || payload.memo.trim().length === 0) {
                 delete payload.memo; // Drop invalid memo silently
@@ -1624,7 +1659,6 @@ class OneShot {
         else if (!endpoint.includes('/inbox') && !endpoint.includes('/notifications') && !endpoint.includes('/balance')) {
             this.log('No memo provided — consider adding a reason for audit trail');
         }
-        // Validate decisionContext
         if (payload.decisionContext !== undefined) {
             if (typeof payload.decisionContext !== 'object' || payload.decisionContext === null) {
                 delete payload.decisionContext;
@@ -1662,8 +1696,8 @@ 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);
+            const signed = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
+            response = await this.makePaidRequest(signed, endpoint, payload, quoteId, signal, undefined, extraHeaders);
         }
         if (!response.ok) {
             await this.failFromResponse('Tool request failed', response);
@@ -1713,27 +1747,66 @@ 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 };
     }
+    /**
+     * Wait for a previously dispatched job and return its result.
+     *
+     * Use this to resolve the `request_id` returned by a call made with
+     * `wait: false`, or to resume waiting after a client restart. Delivery is the
+     * same as for blocking calls: WebSocket push when the server offers it, HTTP
+     * polling of `GET /v1/requests/:id` as the source of truth.
+     */
+    async waitForResult(requestId, options = {}) {
+        this.validate(requestId, 'requestId');
+        return this.pollJob(requestId, options.timeout, options.signal, options.onStatusUpdate, options.waitForPhones ? { waitForPhones: true, phoneTimeoutSec: options.phoneTimeoutSec } : undefined);
+    }
     async pollJob(requestId, timeoutSec, signal, onStatusUpdate, phoneOpts) {
-        // Try WebSocket push first, fall back to HTTP polling. Both phases share a
-        // single deadline so the combined wait never exceeds the caller's timeout —
-        // previously the WS cap (≤180s) plus a fresh full HTTP timeout could total
-        // up to ~1.6× timeoutSec (e.g. ~480s for a 300s request).
-        const deadline = timeoutSec != null ? Date.now() + timeoutSec * 1000 : undefined;
+        // HTTP polling is the source of truth; the WebSocket is an accelerator.
+        // Both run concurrently from the start and the first terminal outcome wins,
+        // so a broken push channel (Redis down, worker unconfigured, proxy that
+        // swallows frames) costs nothing beyond the poll cadence. Previously the
+        // client waited 60% of its timeout on the socket before polling at all —
+        // in prod that was ~72s of dead air on every call while the push never came.
+        const inner = new AbortController();
+        const onOuterAbort = () => inner.abort();
+        if (signal?.aborted)
+            inner.abort();
+        else
+            signal?.addEventListener('abort', onOuterAbort, { once: true });
+        const wait = { pushConfirmed: false, lastStatus: undefined, via: undefined };
+        // Two sources now report status; only surface changes to the caller.
+        const emit = (status) => {
+            if (status === wait.lastStatus)
+                return;
+            wait.lastStatus = status;
+            onStatusUpdate?.(status, requestId);
+        };
+        const startedAt = Date.now();
+        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)
+                throw err;
+            this.log(`WebSocket unavailable (${err instanceof Error ? err.message : String(err)}) — relying on HTTP polling`);
+            return new Promise(() => { });
+        });
+        const httpBranch = this.pollJobHttp(requestId, timeoutSec, inner.signal, emit, wait);
+        // The losing branch rejects on abort; mark both handled so it never
+        // surfaces as an unhandled rejection.
+        wsBranch.catch(() => { });
+        httpBranch.catch(() => { });
         let result;
         try {
-            result = await this.waitViaWebSocket(requestId, timeoutSec, signal, onStatusUpdate);
+            result = await Promise.race([wsBranch, httpBranch]);
         }
-        catch {
-            this.log('WebSocket unavailable, falling back to HTTP polling');
-            const remainingSec = deadline != null
-                ? Math.max(1, Math.ceil((deadline - Date.now()) / 1000))
-                : undefined;
-            result = await this.pollJobHttp(requestId, remainingSec, signal, onStatusUpdate);
+        finally {
+            inner.abort();
+            signal?.removeEventListener('abort', onOuterAbort);
         }
+        this.log(`Job ${requestId} ready after ${Date.now() - startedAt}ms via ${wait.via ?? 'unknown'}`);
         // Optional second phase: keep polling for the async phone-reveal webhook.
         // Only kicks in when the caller explicitly opts in AND the result still
         // has phones_pending=true (set by the worker when the upstream enrichment
@@ -1817,88 +1890,70 @@ class OneShot {
         // so the consumer knows phones never arrived.
         return lastResult;
     }
-    waitViaWebSocket(requestId, timeoutSec, signal, onStatusUpdate) {
+    /**
+     * WebSocket branch of a job wait. Resolves on a `completed` push for this
+     * request, rejects with `JobError` on `failed` and with `OneShotError` on
+     * abort. Every other failure (no WebSocket global, handshake refused, socket
+     * closed early) rejects with a plain `Error`, which `pollJob` treats as
+     * "no push available" rather than as an outcome. There is no timeout here:
+     * the HTTP branch owns the deadline and aborts this one when it settles.
+     */
+    waitViaWebSocket(requestId, signal, emit, wait) {
         return new Promise((resolve, reject) => {
-            const maxWaitMs = (timeoutSec ?? 120) * 1000;
-            // Cap WS timeout to 60% of caller timeout so HTTP fallback has real time to work.
-            // Floor at 10s (below that, skip WS entirely). This prevents the WS timeout
-            // from racing with Cloud Run / load balancer timeouts.
-            const wsTimeoutMs = Math.max(Math.floor(maxWaitMs * 0.6), 10000);
-            if (wsTimeoutMs >= maxWaitMs) {
-                // Timeout too short for WS + HTTP — reject immediately to force HTTP path
-                return reject(new Error('Timeout too short for WebSocket path'));
+            if (typeof WebSocket === 'undefined') {
+                return reject(new Error('WebSocket not available'));
+            }
+            if (signal.aborted) {
+                return reject(new errors_1.OneShotError('Operation cancelled'));
             }
             const wsUrl = this.baseUrl.replace(/^http/, 'ws') +
                 `/v1/requests/subscribe?wallet=${encodeURIComponent(this.provider.address)}`;
             let ws;
-            let settled = false;
-            let receivedAnyMessage = false;
             try {
                 ws = new WebSocket(wsUrl);
             }
             catch {
                 return reject(new Error('WebSocket not available'));
             }
+            let settled = false;
             const settle = (fn) => {
                 if (settled)
                     return;
                 settled = true;
                 fn();
             };
-            // Overall WS timeout — bail to HTTP fallback with time to spare
-            const timeout = setTimeout(() => {
-                settle(() => {
-                    ws.close();
-                    reject(new Error('WebSocket timeout — falling back to HTTP'));
-                });
-            }, wsTimeoutMs);
-            // First-message deadline: if no relevant message arrives within 15s of
-            // subscribing, the WS connection is likely silent (load balancer proxying
-            // without forwarding, scale-from-zero, etc). Bail fast to HTTP.
-            let firstMessageTimer = null;
             const cleanup = () => {
-                clearTimeout(timeout);
-                if (firstMessageTimer)
-                    clearTimeout(firstMessageTimer);
-                if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                signal.removeEventListener('abort', onAbort);
+                // 0 = CONNECTING, 1 = OPEN (avoid relying on static props of a fake global)
+                if (ws.readyState === 0 || ws.readyState === 1) {
                     ws.close();
                 }
             };
-            if (signal) {
-                signal.addEventListener('abort', () => {
-                    settle(() => {
-                        cleanup();
-                        reject(new errors_1.OneShotError('Operation cancelled'));
-                    });
-                }, { once: true });
-            }
+            const onAbort = () => {
+                settle(() => {
+                    cleanup();
+                    reject(new errors_1.OneShotError('Operation cancelled'));
+                });
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
             ws.onopen = () => {
                 ws.send(JSON.stringify({ subscribe: [requestId] }));
-                // Start first-message deadline after subscribing
-                firstMessageTimer = setTimeout(() => {
-                    if (!receivedAnyMessage) {
-                        settle(() => {
-                            this.log('WebSocket silent after subscribe — falling back to HTTP');
-                            cleanup();
-                            reject(new Error('WebSocket silent — no messages received'));
-                        });
-                    }
-                }, 15000);
             };
             ws.onmessage = (event) => {
-                receivedAnyMessage = true;
-                if (firstMessageTimer) {
-                    clearTimeout(firstMessageTimer);
-                    firstMessageTimer = null;
-                }
                 try {
                     const msg = JSON.parse(typeof event.data === 'string' ? event.data : event.data.toString());
+                    // The subscribe ack and other jobs' pushes are not request-scoped.
                     if (msg.request_id !== requestId)
                         return;
+                    if (!wait.pushConfirmed) {
+                        wait.pushConfirmed = true;
+                        this.log('WebSocket push confirmed — relaxing HTTP polling');
+                    }
                     if (msg.status === 'completed') {
                         this.log('Job completed (WebSocket)');
                         settle(() => {
                             cleanup();
+                            wait.via = 'ws';
                             const result = (msg.result ?? msg);
                             if (msg.request_id && typeof result === 'object' && result !== null && !('request_id' in result)) {
                                 result.request_id = msg.request_id;
@@ -1909,11 +1964,12 @@ class OneShot {
                     else if (msg.status === 'failed') {
                         settle(() => {
                             cleanup();
+                            wait.via = 'ws';
                             reject(new errors_1.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown'), msg.error_code));
                         });
                     }
                     else {
-                        onStatusUpdate?.(msg.status, requestId);
+                        emit(String(msg.status));
                     }
                 }
                 catch {
@@ -1927,9 +1983,7 @@ class OneShot {
                 });
             };
             ws.onclose = () => {
-                // Any close before we got a result — reject so HTTP fallback kicks in.
-                // Previously we only rejected on non-1000 codes, but a clean close
-                // without a result is equally fatal for the poll loop.
+                // Any close before we got a result means no push is coming.
                 settle(() => {
                     cleanup();
                     reject(new Error('WebSocket closed before result'));
@@ -1937,12 +1991,18 @@ class OneShot {
             };
         });
     }
-    async pollJobHttp(requestId, timeoutSec, signal, onStatusUpdate) {
+    /**
+     * HTTP branch of a job wait: polls `GET /v1/requests/:id` immediately, then
+     * on a short backoff (300ms → 2s). Once the WebSocket has proven it delivers
+     * for this request, polling relaxes to 5s and acts as a safety net only.
+     * Owns the caller's deadline (`JobTimeoutError`).
+     */
+    async pollJobHttp(requestId, timeoutSec, signal, emit, wait) {
         const maxWaitMs = (timeoutSec ?? 120) * 1000;
         const startTime = Date.now();
-        const pollInterval = 2000;
         let retries = 0;
         const maxRetries = 3;
+        let polls = 0;
         while (Date.now() - startTime < maxWaitMs) {
             if (signal?.aborted)
                 throw new errors_1.OneShotError('Operation cancelled');
@@ -1952,11 +2012,19 @@ class OneShot {
                     signal
                 });
                 if (!resp.ok) {
-                    throw new errors_1.ToolError('Failed to check job status', resp.status, await resp.text());
+                    const body = await resp.text();
+                    // 5xx / 429 from the poll endpoint are transient — keep polling.
+                    // Any other non-2xx (401/403/404) is a real answer about this job.
+                    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);
                 }
                 const job = await resp.json();
                 if (job.status === 'completed') {
                     this.log('Job completed');
+                    if (wait)
+                        wait.via = 'http';
                     const result = (job.result ?? job);
                     // Propagate request_id into the result so callers always have it
                     if (job.request_id && typeof result === 'object' && result !== null && !('request_id' in result)) {
@@ -1965,11 +2033,20 @@ class OneShot {
                     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);
                 }
-                onStatusUpdate?.(job.status, requestId);
+                emit?.(String(job.status));
                 retries = 0;
-                await this.sleep(pollInterval, signal);
+                const interval = wait?.pushConfirmed
+                    ? HTTP_POLL_RELAXED_MS
+                    : HTTP_POLL_BACKOFF_MS[Math.min(polls, HTTP_POLL_BACKOFF_MS.length - 1)];
+                polls++;
+                const remaining = maxWaitMs - (Date.now() - startTime);
+                if (remaining <= 0)
+                    break;
+                await this.sleep(Math.min(interval, remaining), signal);
             }
             catch (err) {
                 if (err instanceof errors_1.OneShotError)
@@ -1977,7 +2054,7 @@ class OneShot {
                 if (++retries > maxRetries) {
                     throw new errors_1.OneShotError(`Polling failed after ${maxRetries} retries: ${err}`);
                 }
-                const backoff = pollInterval * Math.pow(2, retries - 1);
+                const backoff = 2000 * Math.pow(2, retries - 1);
                 this.log(`Retry ${retries}/${maxRetries} in ${backoff}ms`);
                 await this.sleep(backoff, signal);
             }
@@ -2012,7 +2089,6 @@ class OneShot {
         }
         if (quoteId)
             headers['x-quote-id'] = quoteId;
-        // Create timeout signal if specified
         let fetchSignal = signal;
         let timeoutId;
         if (timeoutMs && !signal) {
@@ -2038,17 +2114,152 @@ class OneShot {
             throw new errors_1.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_1.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_1.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. If the wallet's 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.
+     */
+    async sizeSwap(charge, effective, chainId) {
+        const shortfall = charge - effective;
+        // Integer math on a 1000× scale: no float→BigInt on an unbounded value.
+        const mScaled = BigInt(Math.round(this._swapBufferMultiplier * 1000));
+        const target = (charge * mScaled + 999n) / 1000n;
+        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 a 2xx, so a thrown request or a non-2xx response means nothing will be
+     * debited on-chain — release the ETH-mode reservation in that case.
+     */
+    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) {
+            this.releaseUsdcReservation(signed.reservation);
+            throw err;
+        }
+        if (!resp.ok)
+            this.releaseUsdcReservation(signed.reservation);
+        return resp;
     }
     /** Parse the PAYMENT-REQUIRED header from a 402 response into the accepted requirements and Bazaar metadata. */
     parsePaymentRequired(header) {
@@ -2103,76 +2314,87 @@ 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);
         const validAfter = now - 300; // Buffer for clock skew
         const validBefore = now + 3600;
         const nonceHex = ethers_1.ethers.hexlify(nonce);
-        // Use EIP-712 domain from the server's payment requirements
+        // Use the EIP-712 domain from the server's payment requirements — name,
+        // version AND chain. The chain used to be the mainnet constant, which made
+        // every signature invalid against Base Sepolia (the domain separator
+        // includes chainId), so the SDK could never pay on staging.
         const domainName = accepted.extra?.name || 'USD Coin';
         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: CHAIN_ID,
-            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;