@aifinpay/agent 1.6.0 → 1.8.0

package/dist/unifiedAgent.js

@@ -13,13 +13,15 @@ import nacl from "tweetnacl";
 import { blake2b } from "@noble/hashes/blake2b";
 import bs58 from "bs58";
 import { createHash, randomBytes } from "node:crypto";
-import { createPublicClient, createWalletClient, http, keccak256, toHex, toFunctionSelector, } from "viem";
+import { createPublicClient, createWalletClient, http, keccak256, toHex, toFunctionSelector, formatEther, } from "viem";
 import { privateKeyToAccount, } from "viem/accounts";
 import { defineChain } from "viem";
 import { polygon, base, arbitrum, optimism, bsc, mainnet, unichain } from "viem/chains";
 import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction, } from "@solana/web3.js";
 import { AiFinPayError, X402Error, } from "./errors.js";
 import { Agent } from "./agent.js";
+import { MemorySpendLedger, FileSpendLedger } from "./spendLedger.js";
+import { aifp1Fetch, Aifp1ReceiptCache, } from "./aifp1.js";
 import { bridgeQuote as crossChainQuote, bridgeExecute as crossChainExecute, bridgeWaitForArrival, USDC_NATIVE, } from "./crossChain.js";
 // ── B2BSplitter contract ABI ─────────────────────────────────────────────
 // `payMatic` is the splitter's generic NATIVE-token payment entrypoint —
@@ -106,7 +108,7 @@ export const SPLITTER_DEPLOYMENTS = {
         usdc: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
         explorer: "https://polygonscan.com",
         nativeUsdEnv: "AIFINPAY_MATIC_USD", // legacy name kept for back-compat
-        nativeUsdDefault: 0.70,
+        nativeUsdDefault: 0.073, // reference only; ~$0.073 on 2026-08-03
     },
     base: {
         version: "1.1",
@@ -117,7 +119,7 @@ export const SPLITTER_DEPLOYMENTS = {
         usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
         explorer: "https://basescan.org",
         nativeUsdEnv: "AIFINPAY_ETH_USD",
-        nativeUsdDefault: 3000,
+        nativeUsdDefault: 1870, // reference only; ~$1870 on 2026-08-03
     },
     optimism: {
         version: "1.2",
@@ -128,7 +130,7 @@ export const SPLITTER_DEPLOYMENTS = {
         usdc: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
         explorer: "https://optimistic.etherscan.io",
         nativeUsdEnv: "AIFINPAY_ETH_USD",
-        nativeUsdDefault: 3000,
+        nativeUsdDefault: 1870, // reference only; ~$1870 on 2026-08-03
     },
     unichain: {
         version: "1.1",
@@ -139,7 +141,7 @@ export const SPLITTER_DEPLOYMENTS = {
         usdc: "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
         explorer: "https://uniscan.xyz",
         nativeUsdEnv: "AIFINPAY_ETH_USD",
-        nativeUsdDefault: 3000,
+        nativeUsdDefault: 1870, // reference only; ~$1870 on 2026-08-03
     },
     botchain: {
         version: "1.2",
@@ -217,10 +219,17 @@ export class WrongChainBalanceError extends AiFinPayError {
 export class InsufficientFundsError extends AiFinPayError {
     needed_usd;
     available_usd;
-    constructor(needed_usd, available_usd, msg) {
+    details;
+    /**
+     * `details` carries the native amounts, which are what the caller acts on —
+     * the USD figures depend on a price feed that may be unavailable, and an
+     * error about missing funds is the worst possible place to invent a number.
+     */
+    constructor(needed_usd, available_usd, msg, details) {
         super(msg);
         this.needed_usd = needed_usd;
         this.available_usd = available_usd;
+        this.details = details;
     }
 }
 export class BudgetCapExceededError extends AiFinPayError {
@@ -284,7 +293,9 @@ export class AiFinPayAgent {
     solanaRpc;
     cachedRegistry;
     budgetCaps;
-    spend24h = new SpendTracker();
+    spend24h = new SpendTracker(); // reporting only; the cap uses the ledger
+    _ledger;
+    ledgerOverride;
     telemetry;
     _polygonPublic;
     _polygonWallet;
@@ -301,6 +312,14 @@ export class AiFinPayAgent {
             ? [opts.registryUrl]
             : DEFAULT_REGISTRY_PATHS.map((path) => `${inner.baseUrl}${path}`);
         this.budgetCaps = opts.budgetCaps ?? {};
+        // `spendLedger` was declared, documented ("pass your own when the agent
+        // runs on more than one host") and read by the `ledger` getter, but never
+        // assigned from the options — so the option was a no-op and every agent
+        // with a daily cap wrote to ~/.aifinpay regardless. A fleet that supplied
+        // a shared ledger silently got a per-host one instead, which is exactly
+        // the failure the option exists to prevent.
+        if (opts.spendLedger)
+            this.ledgerOverride = opts.spendLedger;
         this.telemetry = opts.telemetry !== false;
         this.polygonRpc = opts.polygonRpc ?? "https://polygon.drpc.org";
         this.solanaRpc = opts.solanaRpc
@@ -608,6 +627,61 @@ export class AiFinPayAgent {
      * without submitting an on-chain tx. Throws BudgetCapExceededError
      * in the default "throw" mode.
      */
+    /**
+     * The ledger that enforces the daily cap.
+     *
+     * Chosen late, because setBudget() is usually called after construction and
+     * the choice depends on whether a daily cap exists at all. Durability is
+     * engaged only when one does: a library that writes to a user's disk because
+     * it was imported would be rude, and one that promises a daily limit and
+     * forgets it on restart is worse.
+     */
+    get ledger() {
+        if (this.ledgerOverride)
+            return this.ledgerOverride;
+        if (!this._ledger) {
+            this._ledger = this.budgetCaps.daily_usd !== undefined
+                ? FileSpendLedger.forAgent(this.evmAddress)
+                : new MemorySpendLedger();
+        }
+        return this._ledger;
+    }
+    /**
+     * Claim room in the daily cap before paying.
+     *
+     * Returns a reservation id, or "skip"/throws per on_limit_exceeded. The cap
+     * comparison happens inside the ledger, atomically: a caller that read the
+     * total and then reserved would have rebuilt the race this replaces, where
+     * two concurrent calls both read the same total, both passed, and both paid.
+     */
+    async reserveDaily(costUsd) {
+        const cap = this.budgetCaps.daily_usd;
+        if (cap === undefined)
+            return null; // no daily cap to enforce
+        const id = await this.ledger.reserve(costUsd, cap, 24 * 3600 * 1000);
+        if (id)
+            return id;
+        const err = new BudgetCapExceededError("daily", `this call would take daily spend past the $${cap} cap`);
+        if ((this.budgetCaps.on_limit_exceeded ?? "throw") === "skip")
+            return "skip";
+        throw err;
+    }
+    /**
+     * The per-call cap, which needs no ledger.
+     *
+     * It is a property of one call and cannot be raced: nothing about a
+     * concurrent call changes whether THIS one is too expensive. Only the daily
+     * cap accumulates, and only it goes through reserve/commit.
+     */
+    checkPerCall(costUsd) {
+        const cap = this.budgetCaps.per_call_usd;
+        if (cap === undefined || costUsd <= cap)
+            return true;
+        const err = new BudgetCapExceededError("per_call", `cost $${costUsd} exceeds per-call cap $${cap}`);
+        if ((this.budgetCaps.on_limit_exceeded ?? "throw") === "skip")
+            return false;
+        throw err;
+    }
     checkBudget(costUsd) {
         const mode = this.budgetCaps.on_limit_exceeded ?? "throw";
         if (this.budgetCaps.per_call_usd !== undefined && costUsd > this.budgetCaps.per_call_usd) {
@@ -644,6 +718,107 @@ export class AiFinPayAgent {
      *
      * Returns false (skip) instead of throwing when on_limit_exceeded="skip".
      */
+    /**
+     * The native-token USD price for the pre-sign guard.
+     *
+     * Order: an explicit env var, then the protocol's own price feed, then
+     * nothing. "Nothing" is deliberate and is the whole point of this method.
+     * The guard used to fall back to a constant compiled into the SDK; POL sat
+     * at 0.70 while trading near 0.073, so a real $0.01 payment estimated at
+     * $0.096, cleared the $0.06 ceiling and threw BudgetCapExceededError. The
+     * payment never left, and the error blamed the bridge for demanding too
+     * much.
+     *
+     * A guard that blocks on a number it cannot justify is worse than no guard,
+     * so an unknown price returns NaN and guardChallengeAmount declines to
+     * block. Overpayment protection is given up only in the case where we have
+     * no basis for it, which is the honest trade.
+     */
+    priceCache;
+    async nativeUsdFor(deployment) {
+        const env = process.env[deployment.nativeUsdEnv];
+        if (env !== undefined) {
+            const v = parseFloat(env);
+            if (Number.isFinite(v) && v > 0)
+                return { usd: v, source: deployment.nativeUsdEnv };
+        }
+        const symbol = deployment.chain.nativeCurrency.symbol.toUpperCase();
+        const fresh = this.priceCache && Date.now() - this.priceCache.at < 60_000;
+        if (!fresh) {
+            try {
+                const r = await this.inner.fetchImpl(`${this.inner.baseUrl}/api/price/native`, {
+                    signal: AbortSignal.timeout(5_000),
+                });
+                if (r.ok) {
+                    const body = (await r.json());
+                    if (body?.usd)
+                        this.priceCache = { at: Date.now(), usd: body.usd };
+                }
+            }
+            catch {
+                // A feed that will not answer is not a payment failure. Fall through
+                // to "unknown" rather than to a guess.
+            }
+        }
+        const live = this.priceCache?.usd?.[symbol];
+        if (typeof live === "number" && Number.isFinite(live) && live > 0) {
+            return { usd: live, source: "aifinpay price feed" };
+        }
+        return { usd: NaN, source: "unknown" };
+    }
+    /**
+     * Refuse to broadcast a transaction the account cannot pay for, and say so
+     * in terms the caller can act on.
+     *
+     * Without this the SDK handed back viem's ContractFunctionExecutionError —
+     * several paragraphs explaining that cost is `gas * gas fee + value` — for
+     * the one condition an agent operator can fix in ten seconds. Worse, the SDK
+     * has exported an InsufficientFundsError since the first release and never
+     * threw it, so anyone who wrote `catch (e instanceof InsufficientFundsError)`
+     * had a branch that could not run.
+     */
+    async assertCanAffordNative(publicClient, deployment, valueWei) {
+        const address = this.evmAccount.address;
+        let balance;
+        let gasPrice;
+        try {
+            [balance, gasPrice] = await Promise.all([
+                publicClient.getBalance({ address }),
+                publicClient.getGasPrice(),
+            ]);
+        }
+        catch {
+            // An RPC that will not answer must not turn into a funding error; let
+            // the actual send produce the actual failure.
+            return;
+        }
+        // A splitter payment lands around 120k gas; the headroom covers a fee
+        // spike between this check and inclusion. Being generous here only makes
+        // the check quieter, never wrong — a send that fails anyway still fails.
+        const gasBudget = gasPrice * 200000n;
+        const needed = valueWei + gasBudget;
+        if (balance >= needed)
+            return;
+        const symbol = deployment.chain.nativeCurrency.symbol;
+        const chainName = deployment.chain.name;
+        const short = (wei) => {
+            const s = formatEther(wei);
+            return s.includes(".") ? s.replace(/(\.\d{6})\d+$/, "$1").replace(/\.?0+$/, "") || "0" : s;
+        };
+        const { usd } = await this.nativeUsdFor(deployment);
+        const toUsd = (wei) => Number.isFinite(usd) ? (Number(wei) / 1e18) * usd : Number.NaN;
+        throw new InsufficientFundsError(toUsd(needed), toUsd(balance), `Agent ${address} holds ${short(balance)} ${symbol} on ${chainName}, but this call needs ` +
+            `about ${short(needed)} ${symbol} — ${short(valueWei)} for the payment and up to ` +
+            `${short(gasBudget)} for gas. The gas figure is a ceiling: it assumes 200k gas at the ` +
+            `current price, while a splitter payment typically uses closer to 120k. Fund the ` +
+            `address with ${symbol} on ${chainName} and retry.`, {
+            address,
+            chain: chainName,
+            symbol,
+            needed_wei: needed.toString(),
+            available_wei: balance.toString(),
+        });
+    }
     guardChallengeAmount(estUsd, declaredCost, providerName) {
         if (!Number.isFinite(estUsd) || estUsd <= 0)
             return true; // can't estimate — don't block
@@ -804,141 +979,216 @@ export class AiFinPayAgent {
         // null/NaN cost can't poison the SpendTracker and silently disable caps.
         const rawCost = opts.cost ?? provider.price_usd;
         const cost = typeof rawCost === "number" && Number.isFinite(rawCost) ? rawCost : 0;
-        const withinBudget = this.checkBudget(cost);
-        if (!withinBudget)
+        // The per-call cap still refuses outright; the daily one is reserved, so
+        // that two calls in flight cannot both be told there is room.
+        if (!this.checkPerCall(cost))
             return null;
-        if (provider.mode === "session") {
-            throw new AiFinPayError(`Provider ${provider.name} requires session mode — use openSession() (phase-3 feature)`);
-        }
-        const url = opts.bridgeUrl ?? provider.bridge_url;
-        if (!url) {
-            throw new AiFinPayError(`Provider ${provider.name} has no bridge_url`);
-        }
-        const path = (() => {
-            if (provider.service_type === "search")
-                return "/search";
-            if (provider.service_type === "inference")
-                return "/chat/completions";
-            if (provider.service_type === "compute")
-                return "/run";
-            if (provider.service_type === "analytics")
-                return "/query";
-            return "/";
-        })();
-        const buildInit = (extraHeaders = {}) => ({
-            method: opts.method ?? "POST",
-            headers: { "content-type": "application/json", ...extraHeaders },
-            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-            // CallOptions.timeoutMs was previously declared but never applied.
-            signal: opts.signal
-                ?? (opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined),
-        });
-        // 1. Initial unauthenticated POST → expect 402 challenge from the bridge.
-        const fullUrl = url.replace(/\/$/, "") + path;
-        const initialResp = await this.inner.fetchImpl(fullUrl, buildInit());
-        if (initialResp.status !== 402) {
-            // Bridge didn't ask for payment — pass response through unchanged.
-            // Nothing was paid, so the call does NOT count against budget caps.
-            if (this.telemetry)
-                this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, free: true });
-            return initialResp;
-        }
-        let challenge;
+        const reservation = await this.reserveDaily(cost);
+        if (reservation === "skip")
+            return null;
+        let settled = false;
         try {
-            challenge = (await initialResp.json());
-        }
-        catch (e) {
-            throw new X402Error(`bridge returned 402 with non-JSON body`);
-        }
-        // ── Solana branch (b2b_pay_with_split atomic split, live 2026-05-18) ──
-        if (chain === "solana") {
-            if (!challenge.pay_solana) {
-                throw new X402Error(`Bridge ${provider.name} returned 402 without a pay_solana block. ` +
-                    `Either pick chain: "polygon" or ask the operator to set ` +
-                    `BRIDGE_MERCHANT_SOLANA on the bridge service.`);
+            if (provider.mode === "session") {
+                throw new AiFinPayError(`Provider ${provider.name} requires session mode — use openSession() (phase-3 feature)`);
             }
-            const ps = challenge.pay_solana;
-            // Guard: the bridge controls the challenge — verify the demanded
-            // amount is in the same ballpark as the declared cost / caps before
-            // signing anything. Stops a misquoting bridge from draining the agent.
+            const url = opts.bridgeUrl ?? provider.bridge_url;
+            if (!url) {
+                throw new AiFinPayError(`Provider ${provider.name} has no bridge_url`);
+            }
+            const path = (() => {
+                if (provider.service_type === "search")
+                    return "/search";
+                if (provider.service_type === "inference")
+                    return "/chat/completions";
+                if (provider.service_type === "compute")
+                    return "/run";
+                if (provider.service_type === "analytics")
+                    return "/query";
+                return "/";
+            })();
+            const buildInit = (extraHeaders = {}) => ({
+                method: opts.method ?? "POST",
+                headers: { "content-type": "application/json", ...extraHeaders },
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                // CallOptions.timeoutMs was previously declared but never applied.
+                signal: opts.signal
+                    ?? (opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined),
+            });
+            // 1. Initial unauthenticated POST → expect 402 challenge from the bridge.
+            const fullUrl = url.replace(/\/$/, "") + path;
+            const initialResp = await this.inner.fetchImpl(fullUrl, buildInit());
+            if (initialResp.status !== 402) {
+                // Bridge didn't ask for payment — pass response through unchanged.
+                // Nothing was paid, so the call does NOT count against budget caps.
+                if (this.telemetry)
+                    this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, free: true });
+                return initialResp;
+            }
+            let challenge;
+            try {
+                challenge = (await initialResp.json());
+            }
+            catch (e) {
+                throw new X402Error(`bridge returned 402 with non-JSON body`);
+            }
+            // ── Solana branch (b2b_pay_with_split atomic split, live 2026-05-18) ──
+            if (chain === "solana") {
+                if (!challenge.pay_solana) {
+                    throw new X402Error(`Bridge ${provider.name} returned 402 without a pay_solana block. ` +
+                        `Either pick chain: "polygon" or ask the operator to set ` +
+                        `BRIDGE_MERCHANT_SOLANA on the bridge service.`);
+                }
+                const ps = challenge.pay_solana;
+                // Guard: the bridge controls the challenge — verify the demanded
+                // amount is in the same ballpark as the declared cost / caps before
+                // signing anything. Stops a misquoting bridge from draining the agent.
+                {
+                    const lamports = Number(ps.total_lamports ?? ps.merchant_amount_lamports);
+                    const solUsd = parseFloat(process.env.AIFINPAY_SOL_USD ?? "200");
+                    const estUsd = (Number.isFinite(lamports) ? lamports / 1e9 : 0) * solUsd;
+                    const guarded = this.guardChallengeAmount(estUsd, cost, provider.name);
+                    if (!guarded)
+                        return null;
+                }
+                const solTxSig = await this.submitSolanaB2BPayWithSplit(ps);
+                const paidResp = await this.inner.fetchImpl(fullUrl, buildInit({
+                    "x-solana-tx": solTxSig,
+                    "x-order-id": ps.order_id,
+                }));
+                if (!paidResp.ok) {
+                    const detail = await paidResp.text().catch(() => "<unreadable>");
+                    throw new AiFinPayError(`Bridge retry failed ${paidResp.status} after Solana payment ${solTxSig}: ${detail.slice(0, 300)}`);
+                }
+                // Money moved here, and only here. The reservation becomes a
+                // settled amount; the finally below then has nothing to release.
+                this.spend24h.add(cost);
+                if (typeof reservation === "string") {
+                    await this.ledger.commit(reservation, cost);
+                }
+                settled = true;
+                if (this.telemetry)
+                    this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, tx: solTxSig });
+                // @internal — attach settlement metadata for consumers (MCP, telemetry
+                // dashboards) that need to surface the tx hash without an extra RPC
+                // call. Response headers are read-only after construction so we use
+                // an instance property + cast on the read side.
+                paidResp.aifinpayTx = solTxSig;
+                paidResp.aifinpayChain = "solana";
+                return paidResp;
+            }
+            // ── EVM branch (B2BSplitter.payMatic — generic native-token atomic split) ──
+            // Settles on any chain in SPLITTER_DEPLOYMENTS (polygon default; base,
+            // optimism, unichain, botchain, xrplevm). Native token only — the
+            // deployed splitter payment path has no ERC-20/USDC entrypoint.
+            if (!challenge.pay_matic) {
+                throw new X402Error(`bridge ${provider.name} returned 402 but no pay_matic block — only legacy AiFinPay/Coinbase facilitators not yet wired into AiFinPayAgent.call()`);
+            }
+            const pm = challenge.pay_matic;
+            const deployment = SPLITTER_DEPLOYMENTS[chain];
+            if (!deployment) {
+                throw new AiFinPayError(`No B2BSplitter deployment registered for chain "${chain}" — supported: ${Object.keys(SPLITTER_DEPLOYMENTS).join(", ")}`);
+            }
+            // Refuse to pay a quote denominated for another chain's native token:
+            // total_wei quoted for POL on Polygon would be a massive overpay if
+            // blindly re-sent as ETH on Base. Legacy bridges always emit "polygon".
+            if (pm.chain && pm.chain !== chain) {
+                throw new X402Error(`bridge ${provider.name} quoted pay_matic for chain "${pm.chain}" but the call was routed to "${chain}" — refusing cross-denomination payment`);
+            }
+            // Guard: same ballpark check as the Solana branch — never sign for an
+            // amount wildly above the declared cost / per-call cap. Native-token
+            // USD price per chain via SPLITTER_DEPLOYMENTS.nativeUsdEnv.
             {
-                const lamports = Number(ps.total_lamports ?? ps.merchant_amount_lamports);
-                const solUsd = parseFloat(process.env.AIFINPAY_SOL_USD ?? "200");
-                const estUsd = (Number.isFinite(lamports) ? lamports / 1e9 : 0) * solUsd;
+                const wei = Number(pm.total_wei);
+                const { usd: nativeUsd } = await this.nativeUsdFor(deployment);
+                // NaN when no price is known — guardChallengeAmount then declines to
+                // block rather than blocking on a guess. See nativeUsdFor().
+                const estUsd = (Number.isFinite(wei) ? wei / 1e18 : 0) * nativeUsd;
                 const guarded = this.guardChallengeAmount(estUsd, cost, provider.name);
                 if (!guarded)
                     return null;
             }
-            const solTxSig = await this.submitSolanaB2BPayWithSplit(ps);
+            // 2. Submit the B2BSplitter payment on the selected chain's mainnet and
+            // wait for it to land. Prefer the challenge's splitter address (current
+            // bridge behaviour); fall back to the registry address for bridges that
+            // omit it.
+            const splitterAddress = pm.splitter
+                ?? deployment.splitter;
+            const txHash = await this.settleSplitterNative({
+                chain,
+                splitter: splitterAddress,
+                splitterVersion: pm.splitter_version,
+                merchantWallet: pm.merchant_wallet,
+                totalWei: BigInt(pm.total_wei),
+                orderId: pm.order_id,
+                ipCreator: pm.ip_creator,
+            });
+            // 3. Retry the bridge with payment proof.
             const paidResp = await this.inner.fetchImpl(fullUrl, buildInit({
-                "x-solana-tx": solTxSig,
-                "x-order-id": ps.order_id,
+                "x-tx-hash": txHash,
+                "x-order-id": pm.order_id,
             }));
             if (!paidResp.ok) {
                 const detail = await paidResp.text().catch(() => "<unreadable>");
-                throw new AiFinPayError(`Bridge retry failed ${paidResp.status} after Solana payment ${solTxSig}: ${detail.slice(0, 300)}`);
+                throw new AiFinPayError(`Bridge retry failed ${paidResp.status} after on-chain payment ${txHash}: ${detail.slice(0, 300)}`);
             }
+            // Money moved here, and only here. The reservation becomes a
+            // settled amount; the finally below then has nothing to release.
             this.spend24h.add(cost);
+            if (typeof reservation === "string") {
+                await this.ledger.commit(reservation, cost);
+            }
+            settled = true;
             if (this.telemetry)
-                this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, tx: solTxSig });
-            // @internal — attach settlement metadata for consumers (MCP, telemetry
-            // dashboards) that need to surface the tx hash without an extra RPC
-            // call. Response headers are read-only after construction so we use
-            // an instance property + cast on the read side.
-            paidResp.aifinpayTx = solTxSig;
-            paidResp.aifinpayChain = "solana";
+                this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, tx: txHash });
+            // @internal — see Solana branch above for rationale on property-attach.
+            paidResp.aifinpayTx = txHash;
+            paidResp.aifinpayChain = chain;
             return paidResp;
         }
-        // ── EVM branch (B2BSplitter.payMatic — generic native-token atomic split) ──
-        // Settles on any chain in SPLITTER_DEPLOYMENTS (polygon default; base,
-        // optimism, unichain, botchain, xrplevm). Native token only — the
-        // deployed splitter payment path has no ERC-20/USDC entrypoint.
-        if (!challenge.pay_matic) {
-            throw new X402Error(`bridge ${provider.name} returned 402 but no pay_matic block — only legacy AiFinPay/Coinbase facilitators not yet wired into AiFinPayAgent.call()`);
+        finally {
+            // Every path that did not move money gives the budget back now rather
+            // than waiting for the reservation to expire — an early return, a
+            // refused challenge, a revert, a thrown error. Missing one of them
+            // would leak the cap and eventually stop the agent paying at all,
+            // which is why this is a finally and not a branch.
+            if (typeof reservation === "string" && !settled) {
+                await this.ledger.release(reservation);
+            }
         }
-        const pm = challenge.pay_matic;
-        const deployment = SPLITTER_DEPLOYMENTS[chain];
+    }
+    // ── EVM B2BSplitter native settlement — one quote in, one tx hash out ────
+    //
+    // Extracted from call() when a second caller needed the same settlement.
+    // The version handling below is the reason it is one method and not two
+    // copies: it was already wrong once, and a duplicate would only be fixed
+    // in whichever copy the next revert happened to come from.
+    //
+    // Returns only after the transaction is included AND succeeded — a hash for
+    // a reverted transaction would otherwise be handed to a merchant as proof of
+    // a payment that never moved.
+    async settleSplitterNative(p) {
+        // call() has already checked this for the bridge flow; repeated here
+        // because settlement is now reachable without going through call().
+        const deployment = SPLITTER_DEPLOYMENTS[p.chain];
         if (!deployment) {
-            throw new AiFinPayError(`No B2BSplitter deployment registered for chain "${chain}" — supported: ${Object.keys(SPLITTER_DEPLOYMENTS).join(", ")}`);
-        }
-        // Refuse to pay a quote denominated for another chain's native token:
-        // total_wei quoted for POL on Polygon would be a massive overpay if
-        // blindly re-sent as ETH on Base. Legacy bridges always emit "polygon".
-        if (pm.chain && pm.chain !== chain) {
-            throw new X402Error(`bridge ${provider.name} quoted pay_matic for chain "${pm.chain}" but the call was routed to "${chain}" — refusing cross-denomination payment`);
+            throw new AiFinPayError(`No B2BSplitter deployment registered for chain "${p.chain}" — supported: ${Object.keys(SPLITTER_DEPLOYMENTS).join(", ")}`);
         }
-        // Guard: same ballpark check as the Solana branch — never sign for an
-        // amount wildly above the declared cost / per-call cap. Native-token
-        // USD price per chain via SPLITTER_DEPLOYMENTS.nativeUsdEnv.
-        {
-            const wei = Number(pm.total_wei);
-            const nativeUsd = parseFloat(process.env[deployment.nativeUsdEnv] ?? String(deployment.nativeUsdDefault));
-            const estUsd = (Number.isFinite(wei) ? wei / 1e18 : 0) * nativeUsd;
-            const guarded = this.guardChallengeAmount(estUsd, cost, provider.name);
-            if (!guarded)
-                return null;
-        }
-        // 2. Submit B2BSplitter.payMatic on the selected chain's mainnet.
-        // Prefer the challenge's splitter address (current bridge behaviour);
-        // fall back to the registry address for bridges that omit it.
-        // ipCreator routing: prefer the challenge's explicit ip_creator; else
-        // route the royalty slot to the splitter's treasury (mirrors the Solana
-        // branch). Passing address(0) would skip the transfer and permanently
-        // strand the 1bp inside B2BSplitter — the contract has no sweep function.
-        const splitterAddress = pm.splitter
-            ?? deployment.splitter;
-        const ipCreator = pm.ip_creator
-            ?? await this.splitterTreasury(splitterAddress, chain)
+        // ipCreator routing: prefer the caller's explicit ip_creator; else route
+        // the royalty slot to the splitter's treasury (mirrors the Solana branch).
+        // Passing address(0) would skip the transfer and permanently strand the
+        // 1bp inside B2BSplitter — the contract has no sweep function.
+        const ipCreator = p.ipCreator
+            ?? await this.splitterTreasury(p.splitter, p.chain)
             ?? "0x0000000000000000000000000000000000000000";
-        const { publicClient, walletClient } = this.splitterClients(chain);
+        const { publicClient, walletClient } = this.splitterClients(p.chain);
         // The entrypoint follows the deployed contract, not the SDK release: v1.2
         // (Polygon, Optimism, BOT Chain, XRPL EVM as of 2026-07-31) takes a bytes32
         // paymentId and rejects one it has already settled, while Base and Unichain
         // still run v1.1. Sending v1.2 calldata to a v1.1 contract reverts with no
         // useful reason, so this must be decided per chain.
-        // An explicit `splitter_version` wins — a server that states it knows what
+        // An explicit `splitterVersion` wins — a server that states it knows what
         // it deployed. What it must NOT fall back to is this registry's
-        // chain -> version entry, because the ADDRESS came from the challenge and
+        // chain -> version entry, because the ADDRESS came from the server and
         // the version would come from a table: two sources that can disagree.
         //
         // In production they did. The Exa bridge still hands out the pre-v1.2
@@ -948,57 +1198,116 @@ export class AiFinPayAgent {
         //
         // So when the server is silent, ask the contract at the address we were
         // actually handed. The registry is used only if the chain cannot be read.
-        const splitterVersion = pm.splitter_version
-            ?? await this.detectSplitterVersion(splitterAddress, chain, deployment.version);
+        const splitterVersion = p.splitterVersion
+            ?? await this.detectSplitterVersion(p.splitter, p.chain, deployment.version);
+        await this.assertCanAffordNative(publicClient, deployment, p.totalWei);
         const txHash = splitterVersion === "1.2"
             ? await walletClient.writeContract({
-                address: splitterAddress,
+                address: p.splitter,
                 abi: SPLITTER_PAY_NATIVE_ABI,
                 functionName: "payNative",
                 args: [
-                    paymentIdFor(pm.order_id),
-                    pm.merchant_wallet,
+                    paymentIdFor(p.orderId),
+                    p.merchantWallet,
                     ipCreator,
-                    pm.order_id,
+                    p.orderId,
                 ],
-                value: BigInt(pm.total_wei),
+                value: p.totalWei,
                 chain: deployment.chain,
                 account: this.evmAccount,
             })
             : await walletClient.writeContract({
-                address: splitterAddress,
+                address: p.splitter,
                 abi: SPLITTER_PAY_MATIC_ABI,
                 functionName: "payMatic",
                 args: [
-                    pm.merchant_wallet,
+                    p.merchantWallet,
                     ipCreator,
-                    pm.order_id,
+                    p.orderId,
                 ],
-                value: BigInt(pm.total_wei),
+                value: p.totalWei,
                 chain: deployment.chain,
                 account: this.evmAccount,
             });
-        // 3. Wait for receipt (inclusion is enough on these fast-block chains).
+        // Wait for receipt (inclusion is enough on these fast-block chains).
         const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
         if (receipt.status !== "success") {
             throw new AiFinPayError(`${deployment.chain.name} tx reverted: ${txHash}`);
         }
-        // 4. Retry the bridge with payment proof.
-        const paidResp = await this.inner.fetchImpl(fullUrl, buildInit({
-            "x-tx-hash": txHash,
-            "x-order-id": pm.order_id,
-        }));
-        if (!paidResp.ok) {
-            const detail = await paidResp.text().catch(() => "<unreadable>");
-            throw new AiFinPayError(`Bridge retry failed ${paidResp.status} after on-chain payment ${txHash}: ${detail.slice(0, 300)}`);
-        }
-        this.spend24h.add(cost);
-        if (this.telemetry)
-            this.reportTelemetry({ kind: "call", provider: provider.name, chain, cost, tx: txHash });
-        // @internal — see Solana branch above for rationale on property-attach.
-        paidResp.aifinpayTx = txHash;
-        paidResp.aifinpayChain = chain;
-        return paidResp;
+        return txHash;
+    }
+    // ── AIFP-1 merchant paywall (gateway.aifinpay.io) ───────────────────────
+    //
+    // The protocol lives in aifp1.ts; this is the wiring. Two things only the
+    // agent can supply: the on-chain settlement above, and the budget caps —
+    // aifp1Fetch owns neither, exactly as call() owns them for the bridge flow.
+    _aifp1Cache = new Aifp1ReceiptCache();
+    /**
+     * The prepaid batches this agent is holding.
+     *
+     * Exposed because a batch is money the agent has already spent and has not
+     * finished using: an operator deciding whether to shut an agent down, or a
+     * test asserting that a receipt was reused, both need to see it. The entries
+     * contain bearer JWTs — treat them like keys, and do not log them.
+     */
+    get aifp1Receipts() { return this._aifp1Cache; }
+    /**
+     * Fetch a paywalled URL, paying the AIFP-1 gateway if it asks.
+     *
+     *   const res = await agent.fetchPaid("https://gateway.aifinpay.io/acme/articles/2026/x");
+     *
+     * A URL that is not paywalled — or that answers a 402 belonging to some
+     * other protocol — comes back untouched and costs nothing. A paywalled one
+     * is quoted, settled on-chain, exchanged for a receipt and retried, and the
+     * receipt is kept: subsequent calls it covers cost a header rather than a
+     * transaction. See aifp1.ts for why that reuse is the entire design.
+     *
+     * Returns `null` on the same terms as call(): a budget cap was hit and
+     * `budgetCaps.on_limit_exceeded` is "skip".
+     */
+    async fetchPaid(url, init = {}, opts = {}) {
+        const deployment = SPLITTER_DEPLOYMENTS.polygon;
+        const deps = {
+            fetchImpl: this.inner.fetchImpl,
+            cache: this._aifp1Cache,
+            // A 0x address, because AIFP agent policies are address-keyed
+            // (backend/aifp/agent-policy.js normalizeAddress) — a Solana pubkey here
+            // would silently opt the agent out of its owner's own limits.
+            agentId: opts.agentId ?? this.evmAddress,
+            settle: (p) => this.settleSplitterNative({
+                // Polygon-only, and not by preference: /v1/pay verifies the settlement
+                // by reading the Splitter's Payment event, and that verifier implements
+                // Polygon alone (backend/aifp/verify-settlement.js — Solana returns
+                // notImplemented, anything else unsupported_chain). Settling elsewhere
+                // would move real money for a receipt that can never be issued.
+                chain: "polygon",
+                // The address is not carried in the quote, so it comes from this SDK's
+                // own verified registry. The backend checks the tx against its
+                // configured SPLITTER_ADDRESS_POLYGON; if an operator has pointed that
+                // somewhere else, /v1/pay answers no_splitter_payment_event, which is
+                // loud. Override here if you are running against such a deployment.
+                splitter: opts.splitter ?? deployment.splitter,
+                // Left undetected on purpose — settleSplitterNative asks the contract,
+                // which is the only source that cannot disagree with itself.
+                merchantWallet: p.merchantWallet,
+                totalWei: p.totalWei,
+                orderId: p.orderId,
+            }),
+            checkPerCall: (usd) => this.checkPerCall(usd),
+            reserveDaily: (usd) => this.reserveDaily(usd),
+            commit: (id, usd) => this.ledger.commit(id, usd),
+            release: (id) => this.ledger.release(id),
+            onPaid: ({ merchantId, amountUsd, txRef }) => {
+                this.spend24h.add(amountUsd);
+                if (this.telemetry) {
+                    this.reportTelemetry({
+                        kind: "aifp1", merchant: merchantId, chain: "polygon",
+                        cost: amountUsd, tx: txRef,
+                    });
+                }
+            },
+        };
+        return aifp1Fetch(deps, url, init, opts);
     }
     // ── Solana b2b_pay_with_split — build, sign, send via @solana/web3.js ───
     //