keyring-agent-core 0.1.1 → 0.2.1

package/dist/tools/builtin/wallet-action/BuyTokenTool.js

@@ -0,0 +1,1257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BuyTokenTool = void 0;
+const BaseTool_1 = require("../../BaseTool");
+const web3_1 = require("../../../functions/web3");
+const MoralisService_1 = require("../../../services/MoralisService");
+const PantographService_1 = require("../../../services/PantographService");
+const swap_1 = require("../../../services/swap");
+const PoolService_1 = require("../../../services/PoolService");
+const abi_1 = require("../../../constants/abi");
+const amountSpec_1 = require("./amountSpec");
+const gasReserve_1 = require("./gasReserve");
+const chainResolver_1 = require("../../chainResolver");
+/**
+ * Tool: open-buy-token-form
+ *
+ * A STANDALONE wallet-action tool (NOT a `BaseWalletActionTool`): instead of
+ * emitting the shared form payload, it does the quote + approval work itself and
+ * ships a custom `BuyTokenConfirmTx` UI payload the FE executes directly. That's
+ * why `buy_token` is intentionally NOT a member of `WalletActionType`.
+ *
+ * Branches, picked deterministically from the args:
+ *
+ *  0. **Trending picker** — the user wants to buy but did NOT name a token
+ *     (`token_symbol` empty). The tool fetches the chain's live trending list
+ *     and emits `actionButtons` so the user picks one. A click submits a new
+ *     prompt like `"buy PEPE"` which routes back here for the standard flow.
+ *
+ *  1. **Pay-token picker** — the user named the dest token only (`token_symbol`)
+ *     but not the pay token. The tool fetches the wallet's native + ERC-20
+ *     holdings and emits `actionButtons` so the user picks the pay token.
+ *
+ *  1.4 **Balance check** — the user named a pay token (amount optional). Runs
+ *     first so we never proceed with a token the user can't fund: if the wallet
+ *     holds NONE of it, the tool reports that and offers the tokens the user
+ *     DOES hold as alternatives (pay-token picker); if it holds SOME but less
+ *     than the requested amount, it reports the shortfall and emits
+ *     25/50/75/100% buttons sized off the real balance. Skipped for the native
+ *     pay token and when balances can't be read.
+ *
+ *  1.5 **Amount picker** — dest + pay token are known but no amount was given.
+ *     The tool reads the pay-token balance and emits 25/50/75/100% buttons so
+ *     the user sizes the spend in one tap (or types a custom amount).
+ *
+ *  1.75 **Confirm tx** — dest + pay token + a PAY-TOKEN amount are all known.
+ *     The tool fetches a swap quote (estimated receive amount + the raw swap
+ *     tx), checks allowance, and emits a `BuyTokenConfirmTx` payload bundling
+ *     the estimate, the raw swap transaction, and the approve transaction (when
+ *     one is needed). The FE executes approve (if any) then swap itself.
+ *
+ *  When none of the above produces a result (couldn't resolve the dest token,
+ *  quote failed, amount given only on the buy side, …) the tool returns an
+ *  error/_instructions object — it never opens a generic form.
+ *
+ * Amount disambiguation mirrors the chatbot SDK:
+ *   - "buy PEPE with 10 USDC"  → pay_with_amount = "10"
+ *   - "buy 0.02 PCM with USDC" → buy_amount = "0.02"
+ */
+class BuyTokenTool extends BaseTool_1.BaseTool {
+    name = 'open-buy-token-form';
+    kind = 'action';
+    category = 'wallet-action';
+    // The tool drives a concrete confirm/pick step — no generic LLM follow-ups.
+    noSuggestions = true;
+    moralis;
+    /** Trending tokens come from Pantograph (top-gainers), not Moralis. */
+    pantograph;
+    /** Branch-tracing on/off — shares AgentCore's `debug` flag (passed in). */
+    debug;
+    constructor(config, options) {
+        super();
+        if (config !== undefined) {
+            this.moralis = new MoralisService_1.MoralisService(config);
+            this.pantograph = new PantographService_1.PantographService({ baseUrl: config.pantographUrl });
+        }
+        this.debug = options?.debug ?? false;
+    }
+    /**
+     * Branch-tracing logger. Prints which branch the tool takes and the key
+     * values feeding that decision. Enabled by AgentCore's shared `debug` flag
+     * (so one switch covers the LLM trace and this tool). Kept terse.
+     */
+    dbg(label, data) {
+        if (this.debug) {
+            if (data === undefined)
+                console.log(`[BuyTokenTool] ${label}`);
+            else
+                console.log(`[BuyTokenTool] ${label}`, JSON.stringify(data));
+        }
+    }
+    description = 'Open the BUY TOKEN flow for ANY buy/purchase intent. Handles both cases: ' +
+        '(a) the user NAMED a token — "buy PEPE", "mua DOGE", "buy 100 USDC with ETH": pass `token_symbol` ' +
+        '(the destination); if you also know the pay token, fill `pay_with_symbol` (or `pay_with_address`), ' +
+        'else leave pay_with_* blank and the tool returns a wallet picker. ' +
+        '(b) the user did NOT name a token — "buy a trending token", "mua token trending", "buy something ' +
+        'pumping", "buy hot tokens", "mua token tăng mạnh": leave `token_symbol` blank and the tool returns ' +
+        "buttons of the chain's current trending tokens so the user picks one. " +
+        'Amount: `buy_amount` = destination to RECEIVE; `pay_with_amount` = payment to SPEND. Never both.';
+    parameters = [
+        { name: 'chain', type: 'string', description: 'Hex chain id. Defaults to connected chain.', required: false },
+        {
+            name: 'token_symbol',
+            type: 'string',
+            description: 'Symbol of the token the user wants to BUY (e.g. "PEPE"). Leave EMPTY when the user did not name ' +
+                'a token (e.g. "buy a trending token") — the tool then returns trending tokens to pick from.',
+            required: false,
+        },
+        {
+            name: 'contract_address',
+            type: 'string',
+            description: 'Destination token address (0x…), or "native" for the chain\'s native coin. Leave empty when ' +
+                'unknown — the tool resolves it from token_symbol.',
+            required: false,
+        },
+        {
+            name: 'buy_amount',
+            type: 'string',
+            description: 'Quantity of the DESTINATION token (the one being bought) the user wants to RECEIVE. ' +
+                'Set this when the amount sits next to the token being bought: "buy 5 PEPE", "mua 5 PEPE", ' +
+                '"buy 0.02 PCM with USDC" → buy_amount = the number next to PEPE/PCM. ' +
+                'May also be a USD value when the user sizes the buy in dollars ("buy $5 of PEPE" → "5$"); ' +
+                'pass the user\'s expression VERBATIM (the tool converts "$" to a token quantity). ' +
+                'Mutually exclusive with pay_with_amount — set at most ONE of the two.',
+            required: false,
+        },
+        {
+            name: 'pay_with_symbol',
+            type: 'string',
+            description: 'Symbol of the payment token (e.g. "USDC", "ETH").',
+            required: false,
+        },
+        {
+            name: 'pay_with_address',
+            type: 'string',
+            description: 'Address of the payment token (0x…), OR "native" for the chain\'s native coin.',
+            required: false,
+        },
+        {
+            name: 'pay_with_amount',
+            type: 'string',
+            description: 'Quantity of the PAYMENT token (the one being spent) the user wants to SPEND. ' +
+                'Set this when the amount sits next to the payment token: "buy PEPE with 10 USDC", ' +
+                '"mua PEPE bằng 10 USDC", "spend 0.5 ETH on DOGE" → pay_with_amount = the number next to USDC/ETH. ' +
+                'May also be a PERCENT of the pay-token balance ("buy USDC with 50% USDT" → "50%"), the literal word ' +
+                '"max" meaning the WHOLE balance, or a USD value ("buy USDC with 5$ USDT" → "5$"). NORMALIZE any ' +
+                '"whole balance / everything / maximum" phrasing in ANY language (e.g. "all", "max", "tất cả", ' +
+                '"toàn bộ", "全部", "すべて", "전부", "todo", "tout") to the literal "max"; pass plain/percent/USD ' +
+                'numbers VERBATIM (the tool converts "%"/"$"/"max"). "max" is an AMOUNT, never a token — still set ' +
+                'pay_with_symbol to the payment token ("ETH" in "buy USDC with max ETH"). ' +
+                'Mutually exclusive with buy_amount — set at most ONE of the two.',
+            required: false,
+        },
+        {
+            name: 'limit',
+            type: 'number',
+            description: 'Only used when no token is named: max number of trending tokens to show as buttons. Default 6. Clamped to [1, 10].',
+            required: false,
+        },
+        {
+            name: 'buy_prompt_template',
+            type: 'string',
+            description: 'A short "buy" command IN THE USER\'S CURRENT LANGUAGE, used as the click-command for the trending-token ' +
+                'picker (when the user named no token). Use the exact placeholder "{token}" (do not translate the braces) ' +
+                'for the token symbol; put the localized verb directly in the text. ' +
+                'English example: "buy {token}". Vietnamese example: "mua {token}". Japanese example: "{token} を買う". ' +
+                'Always include {token}.',
+            required: true,
+        },
+        {
+            name: 'buy_with_prompt_template',
+            type: 'string',
+            description: 'A short "buy X with Y" command IN THE USER\'S CURRENT LANGUAGE, used as the click-command for the ' +
+                'pay-token picker and the percentage-spend buttons. Use these exact placeholders (do not translate the ' +
+                'braces): "{token}" = token being bought, "{pay}" = payment token, "{buy_amount}" = quantity of the ' +
+                'BOUGHT token (place it next to {token}), "{pay_amount}" = quantity of the PAYMENT token (place it next ' +
+                'to {pay}). Put the localized verb and the "with" preposition directly in the text. ' +
+                'English example: "buy {buy_amount} {token} with {pay_amount} {pay}". ' +
+                'Vietnamese example: "mua {buy_amount} {token} bằng {pay_amount} {pay}". ' +
+                'Japanese example: "{pay_amount} {pay} で {buy_amount} {token} を買う". ' +
+                'Always include {token} and {pay}. Include both {buy_amount} and {pay_amount} too — the tool removes ' +
+                'whichever amount is unknown (only one side ever carries an amount).',
+            required: true,
+        },
+    ];
+    // -------------------------------------------------------------------------
+    // execute: lift `ui` / `actionButtons` from run() onto the ToolResult.
+    // -------------------------------------------------------------------------
+    async execute(args, userContext) {
+        const callId = `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const start = Date.now();
+        try {
+            const out = (await this.run(args, userContext));
+            const result = {
+                toolName: this.name,
+                callId,
+                success: true,
+                data: out,
+                duration: Date.now() - start,
+            };
+            if (out && typeof out === 'object' && out.ui) {
+                result.ui = out.ui;
+            }
+            if (out && Array.isArray(out.actionButtons) && out.actionButtons.length > 0) {
+                result.actionButtons = out.actionButtons;
+            }
+            return result;
+        }
+        catch (err) {
+            return {
+                toolName: this.name,
+                callId,
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                duration: Date.now() - start,
+            };
+        }
+    }
+    async run(args, userContext) {
+        const walletAddress = userContext?.walletAddress;
+        if (!walletAddress) {
+            return {
+                error: 'wallet_not_connected',
+                _instructions: 'The user is not connected. Ask them to connect their wallet before buying. Do NOT proceed.',
+            };
+        }
+        // The wallet can only sign on the chain it's connected to. If the user named
+        // a chain that differs from their connected chain, ask them to switch first
+        // instead of building a buy they can't sign.
+        const mismatch = (0, chainResolver_1.detectChainMismatch)(args.chain, userContext);
+        if (mismatch) {
+            return {
+                error: 'wrong_chain',
+                _instructions: `The user asked to buy on ${mismatch.requestedLabel}, but their wallet is connected to ${mismatch.connectedLabel}. ` +
+                    `Tell them, in their language, that to buy on ${mismatch.requestedLabel} they must first switch their wallet's network to ${mismatch.requestedLabel}, ` +
+                    `or they can buy on ${mismatch.connectedLabel} (their current network) instead. Do NOT proceed. Do NOT mention tool names, UI, or forms.`,
+            };
+        }
+        const chainId = this.requireChain(args, userContext);
+        if (!chainId) {
+            return {
+                error: 'missing_chain',
+                _instructions: 'No chain is set. Pass the hex chain id explicitly (e.g. "0x1") or set userContext.chain before calling.',
+            };
+        }
+        return this.buildResult(args, userContext);
+    }
+    // -------------------------------------------------------------------------
+    // Main branch dispatch
+    // -------------------------------------------------------------------------
+    async buildResult(args, userContext) {
+        const symbol = typeof args.token_symbol === 'string' ? args.token_symbol.trim() : '';
+        const destRef = typeof args.contract_address === 'string' ? args.contract_address.trim() : '';
+        const chain = this.requireChain(args, userContext) ?? undefined;
+        const walletAddress = userContext?.walletAddress ?? undefined;
+        this.dbg('buildResult:args', { args, chain, walletAddress, hasMoralis: !!this.moralis });
+        // ----- Branch 0: TRENDING PICKER — no token named at all ---------------
+        if (!symbol && !destRef) {
+            this.dbg('→ Branch 0: trending picker (no token named)');
+            return await this.buildTrendingPicker(args, userContext);
+        }
+        // ----- Resolve DEST token (symbol/address → address + decimals) --------
+        const destSide = await this.resolveSide(args.contract_address, symbol, chain, walletAddress, 'dest');
+        const destContract = destSide.address;
+        const destSymbol = destSide.symbol ?? symbol;
+        const destDecimals = destSide.decimals;
+        // ----- Resolve PAY token (if user gave one) ----------------------------
+        const paySide = await this.resolveSide(args.pay_with_address, args.pay_with_symbol, chain, walletAddress, 'pay');
+        const payAddr = paySide.address;
+        const paySymbol = paySide.symbol;
+        const payDecimals = paySide.decimals;
+        // Amounts may be plain ("10"), a percent of balance ("50%"), or a USD value
+        // ("5$"). Pay-side percent/usd resolve against the PAY token's balance/price;
+        // buy-side usd resolves against the DEST token's price (percent on the buy
+        // side is meaningless, so it's ignored). Pay-side resolution needs payAddr —
+        // when it's missing the pay picker runs first and re-submits with a token.
+        const buyAmount = await this.resolveBuyAmountSpec(args.buy_amount, destContract, chain, destSymbol);
+        let payAmount = payAddr
+            ? await this.resolvePayAmountSpec(args.pay_with_amount, payAddr, chain, walletAddress, paySymbol)
+            : this.normaliseAmount(args.pay_with_amount);
+        // Whether the pay amount was sized off the balance (percent / "max" / usd):
+        // such an amount is ≤ spendable by construction, so the balance check skips
+        // the over-balance comparison for it (a re-read spendable can drift a hair).
+        const paySpec = (0, amountSpec_1.parseAmountSpec)(args.pay_with_amount);
+        let amountSizedToBalance = !!paySpec && paySpec.kind !== 'token';
+        // Set to the buy-side amount once we convert it into `payAmount` (Branch 1.3)
+        // so downstream messaging can explain the conversion rather than pretend the
+        // user typed the pay amount.
+        let derivedFromBuy = null;
+        this.dbg('resolved sides', {
+            dest: { destContract, destSymbol, destDecimals },
+            pay: { payAddr, paySymbol, payDecimals },
+            buyAmount,
+            payAmount,
+        });
+        // Could not resolve the destination token — surface it (never open a form).
+        if (!destContract) {
+            this.dbg('→ dest token not resolved');
+            return {
+                error: 'dest_token_not_found',
+                _instructions: `Could not find the token "${destSymbol || destRef}" to buy on this chain. ` +
+                    'Tell the user, in their language, that the token could not be found and ask them to check the name ' +
+                    'or provide its contract address. Do NOT invent an address. Do NOT mention tool names, UI, or forms.',
+            };
+        }
+        // ----- Branch 1: PAY PICKER — dest known, pay missing ------------------
+        if (!payAddr && this.moralis && userContext?.walletAddress) {
+            this.dbg('→ Branch 1: pay picker (pay token missing)');
+            return await this.buildPayWithPicker({ args, userContext, destSymbol, destContract, buyAmount, payAmount });
+        }
+        if (!payAddr) {
+            return {
+                error: 'pay_token_missing',
+                _instructions: `Ask the user, in their language, which token they want to spend to buy ${destSymbol}. ` +
+                    'Do NOT invent a token. Do NOT mention tool names, UI, or forms.',
+            };
+        }
+        // ----- Branch 1.3: BUY-SIDE AMOUNT → PAY AMOUNT ------------------------
+        // deBridge only supports EXACT_INPUT (spend X, receive ~Y). When the user
+        // sized the BUY side instead ("mua 5 PEPE", "mua 5 PEPE bằng USDC") we have
+        // no pay amount to seed the quote — derive one from the live USD price ratio
+        // (payAmount ≈ buyAmount × destPrice / payPrice, +2% buffer for slippage/fees
+        // so they receive AT LEAST about the requested amount). The derived amount
+        // then flows through the SAME balance-check + confirm-tx path below.
+        if (buyAmount && !payAmount) {
+            this.dbg('Branch 1.3: deriving pay amount from buy amount', { buyAmount, destSymbol, paySymbol });
+            const derived = await this.derivePayAmountFromBuy({
+                chain,
+                buyAmount,
+                destContract,
+                destSymbol,
+                payAddr,
+                paySymbol,
+            });
+            if (!derived) {
+                // No reliable USD price for one of the tokens — fall back to asking how
+                // much of the pay token to spend (we can't convert the buy side).
+                this.dbg('→ Branch 1.3: price unavailable — needs pay amount');
+                return {
+                    error: 'needs_pay_amount',
+                    _instructions: `Could not work out how much ${paySymbol ?? 'of the payment token'} equals ${buyAmount} ${destSymbol} right now. ` +
+                        `Tell the user, in their language, that the price couldn't be fetched at the moment, and ask how much ${paySymbol ?? 'of the payment token'} they want to spend instead. ` +
+                        'Do NOT invent an amount or a price. Do NOT mention tool names, UI, or forms.',
+                };
+            }
+            payAmount = derived;
+            derivedFromBuy = buyAmount;
+            // A derived amount is a real cost that CAN exceed the balance — it must be
+            // checked (it was sized off the buy amount, not off the pay balance).
+            amountSizedToBalance = false;
+            this.dbg('→ Branch 1.3: derived pay amount', { payAmount, derivedFromBuy });
+        }
+        // ----- Branch 1.4: BALANCE CHECK — pay token named ---------------------
+        // Native is included: its spendable balance (held − gas reserve) is read by
+        // readPayBalance, so an amount that wouldn't leave room for gas is caught
+        // here just like an over-balance ERC-20 amount.
+        if (this.moralis && userContext?.walletAddress) {
+            this.dbg('Branch 1.4: checking pay balance', { payAddr, paySymbol, payAmount });
+            const shortfall = await this.checkPayBalance({
+                args,
+                userContext,
+                chain,
+                destSymbol,
+                destContract,
+                payAddr,
+                paySymbol,
+                payAmount,
+                buyAmount,
+                derivedFromBuy,
+                amountSizedToBalance,
+            });
+            if (shortfall) {
+                this.dbg('→ Branch 1.4: balance shortfall — returning', {
+                    error: shortfall.error,
+                    hasButtons: Array.isArray(shortfall.actionButtons),
+                });
+                return shortfall;
+            }
+            this.dbg('Branch 1.4: balance OK — continuing');
+        }
+        // ----- Branch 1.5: AMOUNT PICKER — dest + pay known, no amount ----------
+        if (!buyAmount && !payAmount && this.moralis && userContext?.walletAddress) {
+            this.dbg('Branch 1.5: building amount picker');
+            const picker = await this.buildAmountPicker({
+                userContext,
+                chain,
+                destSymbol,
+                payAddr,
+                paySymbol,
+                buyWithTemplate: typeof args.buy_with_prompt_template === 'string' ? args.buy_with_prompt_template : '',
+            });
+            if (picker) {
+                this.dbg('→ Branch 1.5: amount picker returned');
+                return picker;
+            }
+            this.dbg('Branch 1.5: amount picker null — needs amount');
+        }
+        // ----- Branch 1.75: BUILD CONFIRM TX -----------------------------------
+        // Everything is known AND the spend is expressed as a pay-token amount
+        // (EXACT_INPUT): estimate, build raw swap tx, check approval, ship the cube.
+        if (payAmount && (payDecimals !== undefined || payAddr === 'native')) {
+            this.dbg('Branch 1.75: building confirm tx');
+            const confirm = await this.buildConfirmTx({
+                userContext,
+                chain,
+                destContract,
+                destSymbol,
+                destDecimals,
+                payAddr,
+                paySymbol,
+                payDecimals,
+                payAmount,
+            });
+            if (confirm && 'ui' in confirm) {
+                this.dbg('→ Branch 1.75: confirm tx returned');
+                return confirm;
+            }
+            // The swap provider returned a concrete reason — relay it to the user
+            // (it explains WHY, e.g. amount too small, no route, min/max limits).
+            if (confirm && 'quoteError' in confirm) {
+                this.dbg('→ Branch 1.75: quote error from provider', { quoteError: confirm.quoteError });
+                return {
+                    error: 'quote_failed',
+                    quoteError: confirm.quoteError,
+                    _instructions: `Could not quote buying ${destSymbol} with ${paySymbol ?? 'the selected token'}. The swap provider reported: "${confirm.quoteError}". ` +
+                        'Tell the user, in their language, exactly that reason (translate the wording, keep any numbers/limits verbatim) and suggest they adjust the amount or try again shortly. ' +
+                        'Do NOT invent numbers or a different reason. Do NOT mention tool names, UI, or forms.',
+                };
+            }
+            // null — couldn't even attempt a quote (bad chain, missing decimals, …).
+            this.dbg('Branch 1.75: confirm tx unavailable (null)');
+            return {
+                error: 'quote_failed',
+                _instructions: `Could not get a quote to buy ${destSymbol} with ${paySymbol ?? 'the selected token'} right now. ` +
+                    'Tell the user, in their language, that the swap could not be quoted at the moment and ask them to try ' +
+                    'again shortly or with a different amount. Do NOT invent numbers. Do NOT mention tool names, UI, or forms.',
+            };
+        }
+        // The only thing missing is a spendable amount (or it was given on the buy
+        // side, which EXACT_INPUT can't seed off). Ask the user to size the spend.
+        this.dbg('→ needs pay amount');
+        return {
+            error: 'needs_pay_amount',
+            _instructions: `Ask the user, in their language, how much ${paySymbol ?? 'of the payment token'} they want to spend to buy ${destSymbol}. ` +
+                'Do NOT invent an amount. Do NOT mention tool names, UI, or forms.',
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Token resolution (standalone — no BaseWalletActionTool dependency)
+    // -------------------------------------------------------------------------
+    normaliseAddress(value) {
+        if (typeof value !== 'string')
+            return null;
+        const v = value.trim();
+        return (0, web3_1.isAddressEVM)(v) ? v : null;
+    }
+    normaliseAmount(value) {
+        if (typeof value === 'number' && Number.isFinite(value) && value > 0)
+            return String(value);
+        if (typeof value !== 'string')
+            return null;
+        const v = value.trim();
+        if (!v)
+            return null;
+        const n = parseFloat(v);
+        return Number.isFinite(n) && n > 0 ? v : null;
+    }
+    requireChain(args, userContext) {
+        const fromArgs = typeof args.chain === 'string' && args.chain.trim() ? args.chain.trim() : null;
+        if (fromArgs)
+            return fromArgs;
+        return typeof userContext?.chain === 'string' && userContext.chain.trim() ? userContext.chain.trim() : null;
+    }
+    /**
+     * Resolve a token reference (symbol "USDC" or address "0x…") on a chain.
+     * Wallet balances first (most reliable), then Pantograph search. Decimals come
+     * from the API — never from the LLM.
+     */
+    async resolveContractAddress(key, chain, walletAddress) {
+        if (!this.moralis || !key)
+            return undefined;
+        const keyLower = key.trim().toLowerCase();
+        const keyIsAddress = (0, web3_1.isAddressEVM)(key.trim());
+        const matches = (t) => keyIsAddress ? (t.token_address ?? '').toLowerCase() === keyLower : (t.symbol ?? '').toLowerCase() === keyLower;
+        if (walletAddress) {
+            const balRes = await this.moralis.getWalletTokenBalances({ address: walletAddress, chain });
+            if (balRes.success && balRes.data?.result?.length) {
+                const match = balRes.data.result.find(matches);
+                if (match) {
+                    return {
+                        address: match.token_address,
+                        symbol: match.symbol,
+                        name: match.name,
+                        decimals: typeof match.decimals === 'number' ? match.decimals : undefined,
+                    };
+                }
+            }
+        }
+        const searchRes = await this.moralis.searchTokensByKey({ key, chain });
+        if (searchRes.success && searchRes.data?.length) {
+            const exact = searchRes.data.find(matches);
+            const candidate = exact ?? searchRes.data[0];
+            if (candidate?.token_address) {
+                return {
+                    address: candidate.token_address,
+                    symbol: candidate.symbol,
+                    name: candidate.name,
+                    decimals: typeof candidate.decimals === 'number' ? candidate.decimals : undefined,
+                };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolve one side of the buy (dest or pay). Honours the `"native"` sentinel
+     * the swap providers expect. Never errors — a side that can't be resolved
+     * just comes back with `address: null`.
+     */
+    async resolveSide(refArg, symbolArg, chain, walletAddress, label = 'side') {
+        const refStr = typeof refArg === 'string' ? refArg.trim() : '';
+        const symbolStr = typeof symbolArg === 'string' ? symbolArg.trim() : '';
+        if (refStr.toLowerCase() === 'native' || symbolStr.toLowerCase() === 'native') {
+            return { address: 'native', symbol: symbolStr || undefined };
+        }
+        const directAddress = this.normaliseAddress(refArg);
+        const symbolHint = symbolStr || undefined;
+        // The native coin surfaces as the zero address (in wallet balances, or when a
+        // user pastes it) — map it back to the 'native' sentinel so downstream native
+        // handling kicks in: gas-reserve deduction, approval skip, native-side quote.
+        const toNative = (addr) => (addr.toLowerCase() === PoolService_1.ZERO_ADDRESS ? 'native' : addr);
+        const key = directAddress ?? symbolHint ?? (refStr || undefined);
+        if (!key) {
+            this.dbg(`resolveSide:${label}`, { refStr, symbolStr, chain, resolved: 'none' });
+            return { address: null, symbol: symbolHint };
+        }
+        const lookup = await this.resolveContractAddress(key, chain, walletAddress);
+        this.dbg(`resolveSide:${label}`, { refStr, symbolStr, chain, key, lookup });
+        if (!lookup) {
+            // A concrete address with no enrichment — still usable.
+            if (directAddress)
+                return { address: toNative(directAddress), symbol: symbolHint };
+            return { address: null, symbol: symbolHint };
+        }
+        return { address: toNative(lookup.address), symbol: symbolHint ?? lookup.symbol, decimals: lookup.decimals };
+    }
+    // -------------------------------------------------------------------------
+    // Branch 1.75: build confirm tx (estimate + raw swap tx + approve)
+    // -------------------------------------------------------------------------
+    /**
+     * Pay token + dest token + a pay-token amount are known. Fetch a swap quote
+     * (estimated receive amount + raw swap tx), check approval, and return a
+     * `BuyTokenConfirmTx` UI payload the FE executes itself. Returns `null` when
+     * anything we need can't be produced (bad chain, quote failed, non-EVM tx).
+     */
+    async buildConfirmTx(input) {
+        const { userContext, chain, destContract, destSymbol, destDecimals, payAddr, paySymbol, payDecimals, payAmount } = input;
+        const walletAddress = userContext?.walletAddress;
+        if (!walletAddress || !chain || !destContract)
+            return null;
+        const meta = (0, PoolService_1.getChainMeta)(chain);
+        const numericChainId = Number.parseInt(chain, 16);
+        if (!meta || !Number.isFinite(numericChainId))
+            return null;
+        // Native pay token needs no decimals (chain meta) and never approves.
+        const payIsNative = payAddr === 'native';
+        const payDec = payIsNative ? (meta.native.decimals ?? 18) : payDecimals;
+        if (payDec === undefined)
+            return null;
+        const rawAmount = this.toRawAmount(payAmount, payDec);
+        if (!rawAmount)
+            return null;
+        // Providers want a concrete address for the native side; both accept zero.
+        const srcTokenAddress = payIsNative ? PoolService_1.ZERO_ADDRESS : payAddr;
+        const dstTokenAddress = destContract === 'native' ? PoolService_1.ZERO_ADDRESS : destContract;
+        let quote;
+        try {
+            const service = await swap_1.swapServiceFactory.getServiceByProvider('debridge');
+            quote = await service.getQuote({
+                srcChainId: numericChainId,
+                srcTokenAddress,
+                srcTokenAmount: rawAmount,
+                dstChainId: numericChainId,
+                dstTokenAddress,
+                recipientAddress: walletAddress,
+                senderAddress: walletAddress,
+                slippage: 'auto',
+                isCrossChain: false,
+            });
+        }
+        catch (err) {
+            // Network/throw — surface the message so the user sees the real reason.
+            return { quoteError: err instanceof Error ? err.message : String(err) };
+        }
+        // The provider returned a structured failure — forward its reason verbatim.
+        if (!quote.success) {
+            this.dbg('buildConfirmTx: quote failed', { error: quote.error, errorMessage: quote.errorMessage });
+            return { quoteError: this.extractQuoteError(quote) };
+        }
+        if (!quote.tx)
+            return { quoteError: 'No route available for this swap.' };
+        const tx = quote.tx;
+        if (!tx.to || typeof tx.data !== 'string')
+            return null; // non-EVM payload.
+        const swapTx = {
+            chainId: chain,
+            to: tx.to,
+            data: tx.data,
+            value: tx.value ?? '0',
+            from: walletAddress,
+        };
+        // Estimated receive amount of the dest token (provider-specific shape).
+        const estimatedOutRaw = this.extractOutRaw(quote);
+        const estimatedOut = estimatedOutRaw && destDecimals !== undefined
+            ? this.trimAmount(Number(estimatedOutRaw) / 10 ** destDecimals)
+            : undefined;
+        // Approval: native never approves; otherwise ask the provider.
+        let approveTx;
+        if (!payIsNative) {
+            approveTx = await this.buildApproveTx({ chain, walletAddress, payAddr, payDec, rawAmount, quote });
+        }
+        const props = {
+            chain: { hexId: chain, name: meta.name },
+            payToken: {
+                address: payIsNative ? 'native' : payAddr,
+                symbol: paySymbol,
+                decimals: payDec,
+                amount: payAmount,
+                rawAmount,
+            },
+            buyToken: {
+                address: destContract,
+                symbol: destSymbol,
+                decimals: destDecimals,
+                amount: estimatedOut,
+                rawAmount: estimatedOutRaw,
+            },
+            estimatedOut,
+            estimatedOutRaw,
+            provider: quote.provider,
+            swapTx,
+            approveTx,
+        };
+        const ui = { component: 'BuyTokenConfirmTx', props };
+        const estPart = estimatedOut ? ` They will receive about ${estimatedOut} ${destSymbol}.` : '';
+        return {
+            ui: ui,
+            _instructions: `A confirmation panel has been opened for buying ${destSymbol} with ${payAmount} ${paySymbol ?? 'the selected token'}.${estPart} ` +
+                'Briefly tell the user, in their language, the amount they are spending and the estimated amount they will receive, ' +
+                'and ask them to review and confirm to complete the purchase. The estimate is approximate — say "about"/"estimated", never a guaranteed amount. ' +
+                'NEVER invent numbers not provided here. Do NOT mention tool names, UI, forms, or internal steps like approval.',
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Branch 1.3: derive a pay amount from a buy-side amount via USD prices
+    // -------------------------------------------------------------------------
+    /**
+     * deBridge only quotes EXACT_INPUT, so a "buy X of the dest token" request has
+     * no input amount to seed the quote. Convert the desired output into a pay-token
+     * amount using each side's live USD price:
+     *
+     *   payAmount ≈ (buyAmount × destPriceUsd) / payPriceUsd × (1 + buffer)
+     *
+     * The +2% buffer covers slippage + fees so the user receives AT LEAST roughly
+     * the requested amount (the confirm panel still shows the REAL estimate from
+     * the quote, not this derived figure). Returns `null` when either token's USD
+     * price can't be fetched — the caller then asks for a pay amount instead.
+     */
+    async derivePayAmountFromBuy(input) {
+        const { chain, buyAmount, destContract, payAddr } = input;
+        const [destPrice, payPrice] = await Promise.all([
+            this.getUsdPrice(destContract, chain),
+            this.getUsdPrice(payAddr, chain),
+        ]);
+        this.dbg('derivePayAmountFromBuy: prices', { destPrice, payPrice });
+        if (!destPrice || !payPrice)
+            return null;
+        const buyNum = Number(buyAmount);
+        if (!Number.isFinite(buyNum) || buyNum <= 0)
+            return null;
+        const BUFFER = 1.02; // +2% headroom for slippage + provider/protocol fees.
+        const rawPay = (buyNum * destPrice) / payPrice;
+        if (!Number.isFinite(rawPay) || rawPay <= 0)
+            return null;
+        return this.trimAmount(rawPay * BUFFER);
+    }
+    /**
+     * Best-effort live USD price for one side of the swap, sourced from
+     * Pantograph (via `MoralisService.getTokenMetadata`, which queries Pantograph
+     * first). The native coin (`'native'`) is looked up with the zero address —
+     * the Pantograph token endpoint returns the native row for it. Returns `null`
+     * when no positive price is available so the caller can degrade gracefully.
+     */
+    async getUsdPrice(tokenAddrOrNative, chain) {
+        if (!this.moralis)
+            return null;
+        const address = tokenAddrOrNative === 'native' ? PoolService_1.ZERO_ADDRESS : tokenAddrOrNative;
+        const res = await this.moralis.getTokenMetadata({ address, chain });
+        const price = res.success ? res.data?.usd_price : undefined;
+        return typeof price === 'number' && Number.isFinite(price) && price > 0 ? price : null;
+    }
+    // -------------------------------------------------------------------------
+    // Amount-spec resolution ("50%" / "5$" / plain) for the pay / buy sides
+    // -------------------------------------------------------------------------
+    /**
+     * Resolve the PAY-side amount, which may be plain ("10"), a PERCENT of the
+     * held pay-token balance ("50%"), or a USD value ("5$"). Percent reads the
+     * wallet's pay-token balance; usd divides by the pay token's USD price. Returns
+     * a plain token amount string, or `null` when nothing usable was given / the
+     * balance or price needed for a percent/usd couldn't be fetched (the caller's
+     * existing "needs amount" / amount-picker branches then take over).
+     */
+    async resolvePayAmountSpec(rawAmount, payAddr, chain, walletAddress, paySymbol) {
+        const spec = (0, amountSpec_1.parseAmountSpec)(rawAmount);
+        if (!spec)
+            return null;
+        if (spec.kind === 'token')
+            return this.trimAmount(spec.value);
+        if (spec.kind === 'percent') {
+            if (!walletAddress)
+                return null;
+            const bal = await this.readPayBalance(walletAddress, payAddr, chain);
+            this.dbg('resolvePayAmountSpec: percent', { percent: spec.percent, paySymbol, bal: bal?.balanceNum });
+            if (!bal || !Number.isFinite(bal.balanceNum) || bal.balanceNum <= 0)
+                return null;
+            // 100% ("max"/"all") spends the EXACT spendable balance string, never a
+            // re-rounded number — `trimAmount` can round UP, which would then trip the
+            // balance check (a second gas-reserve read can land a hair lower). The
+            // exact string is the gas-aware spendable for native (readPayBalance) or
+            // the held balance for an ERC-20.
+            if (spec.percent >= 100)
+                return this.cleanAmountString(bal.balanceFormatted);
+            return this.trimAmount((bal.balanceNum * spec.percent) / 100);
+        }
+        // usd
+        const price = await this.getUsdPrice(payAddr, chain);
+        this.dbg('resolvePayAmountSpec: usd', { usd: spec.usd, paySymbol, price });
+        if (!price)
+            return null;
+        return this.trimAmount(spec.usd / price);
+    }
+    /**
+     * Resolve the BUY-side amount, which may be plain ("5") or a USD value ("5$",
+     * "buy $5 of PEPE"). USD divides by the DEST token's price to get how many
+     * dest tokens "$X worth" is — that token figure then flows through Branch 1.3
+     * to derive the pay amount. A PERCENT on the buy side is meaningless (percent
+     * of what?), so it's ignored (returns null). Returns a plain token amount
+     * string or `null`.
+     */
+    async resolveBuyAmountSpec(rawAmount, destContract, chain, destSymbol) {
+        const spec = (0, amountSpec_1.parseAmountSpec)(rawAmount);
+        if (!spec)
+            return null;
+        if (spec.kind === 'token')
+            return this.trimAmount(spec.value);
+        if (spec.kind === 'percent')
+            return null; // not meaningful for the buy side.
+        // usd → dest-token quantity via the dest price.
+        if (!destContract)
+            return null;
+        const price = await this.getUsdPrice(destContract, chain);
+        this.dbg('resolveBuyAmountSpec: usd', { usd: spec.usd, destSymbol, price });
+        if (!price)
+            return null;
+        return this.trimAmount(spec.usd / price);
+    }
+    /**
+     * Check whether the pay token needs an allowance for this swap and, if so,
+     * return a ready-to-sign ERC-20 approve tx. Relay bundles the approve step in
+     * the quote (`approvalData` is the tx); deBridge only reports the spender
+     * (`tx.to`), so we encode the approve calldata ourselves.
+     */
+    async buildApproveTx(input) {
+        const { chain, walletAddress, payAddr, payDec, rawAmount, quote } = input;
+        try {
+            const service = await swap_1.swapServiceFactory.getServiceByProvider('debridge');
+            const approval = await service.checkApproval({
+                chain,
+                userAddress: walletAddress,
+                tokenAddress: payAddr,
+                amount: rawAmount,
+                tokenDecimals: payDec,
+                quoteData: quote,
+            });
+            if (!approval.isNeeded)
+                return undefined;
+            // Integrated providers (Relay) hand back the approve tx directly.
+            const data = (approval.approvalData ?? {});
+            if (data.to && typeof data.data === 'string') {
+                return { chainId: chain, to: data.to, data: data.data, value: data.value ?? '0', from: walletAddress };
+            }
+            // deBridge: we only know the spender (the swap router). Encode approve().
+            const spender = approval.contractAddress;
+            if (!spender)
+                return undefined;
+            const approveData = (0, web3_1.encodeFunctionData)({
+                abi: abi_1.erc20Abi,
+                functionName: 'approve',
+                args: [spender, BigInt(rawAmount)],
+            });
+            return { chainId: chain, to: payAddr, data: approveData, value: '0', from: walletAddress };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Human amount → smallest-unit decimal string (no float drift via BigInt). */
+    toRawAmount(human, decimals) {
+        const trimmed = human.trim();
+        if (!/^\d*\.?\d+$/.test(trimmed))
+            return null;
+        const [intPart, fracPartRaw = ''] = trimmed.split('.');
+        const fracPart = fracPartRaw.slice(0, decimals).padEnd(decimals, '0');
+        try {
+            const raw = BigInt(intPart || '0') * 10n ** BigInt(decimals) + BigInt(fracPart || '0');
+            return raw <= 0n ? null : raw.toString();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Pull a human-readable failure reason out of a failed quote. Adapters set
+     * `errorMessage` (string) and `error` (string or a provider object). deBridge
+     * also nests a reason in `raw.errorMessage` / `raw.error`. Falls back to a
+     * generic line so the caller always has something to show.
+     */
+    extractQuoteError(quote) {
+        if (quote.errorMessage && quote.errorMessage.trim())
+            return quote.errorMessage.trim();
+        const fromError = (e) => {
+            if (typeof e === 'string' && e.trim())
+                return e.trim();
+            if (e && typeof e === 'object') {
+                const o = e;
+                for (const v of [o.message, o.errorMessage, o.error]) {
+                    if (typeof v === 'string' && v.trim())
+                        return v.trim();
+                }
+            }
+            return undefined;
+        };
+        const raw = (quote.raw ?? {});
+        return (fromError(quote.error) ??
+            fromError(raw.errorMessage) ??
+            fromError(raw.error) ??
+            'The swap could not be quoted right now.');
+    }
+    /**
+     * Estimated receive amount in the dest token's smallest units. Shape differs
+     * per provider — deBridge same-chain: `raw.tokenOut.minAmount`; deBridge
+     * cross-chain: `raw.estimation.dstChainTokenOut.amount`; Relay:
+     * `raw.details.currencyOut.{amount|minimumAmount}`.
+     */
+    extractOutRaw(quote) {
+        const raw = (quote.raw ?? {});
+        const candidate = raw.tokenOut?.amount ??
+            raw.tokenOut?.minAmount ??
+            raw.details?.currencyOut?.amount ??
+            raw.details?.currencyOut?.minimumAmount ??
+            raw.estimation?.dstChainTokenOut?.recommendedAmount ??
+            raw.estimation?.dstChainTokenOut?.amount;
+        return candidate && /^\d+$/.test(candidate) ? candidate : undefined;
+    }
+    // -------------------------------------------------------------------------
+    // Branch 1: pay-token picker
+    // -------------------------------------------------------------------------
+    async buildPayWithPicker(input) {
+        const { args, userContext, destSymbol, destContract } = input;
+        const chain = this.requireChain(args, userContext) ?? undefined;
+        const moralis = this.moralis;
+        const walletAddress = userContext.walletAddress;
+        const balancesRes = await moralis.getWalletTokenBalances({
+            address: walletAddress,
+            chain,
+            excludeSpam: true,
+            excludeUnverifiedContracts: true,
+        });
+        const balances = balancesRes.success ? (balancesRes.data?.result ?? []) : [];
+        // Include native + ERC-20s, but skip the dest token itself: paying with the
+        // token you're buying is a self-swap the provider rejects. Match by symbol OR
+        // address so a same-symbol holding at a different address is still excluded.
+        const destLower = destContract?.toLowerCase();
+        const destSymLower = destSymbol.trim().toLowerCase();
+        const holdings = balances
+            .filter((t) => {
+            if (!t.symbol)
+                return false;
+            if (destSymLower && t.symbol.toLowerCase() === destSymLower)
+                return false;
+            if (t.native_token)
+                return destLower !== 'native';
+            if (!t.token_address)
+                return false;
+            if (destLower && t.token_address.toLowerCase() === destLower)
+                return false;
+            return true;
+        })
+            .sort((a, b) => (b.usd_value ?? 0) - (a.usd_value ?? 0))
+            .slice(0, 8);
+        if (holdings.length === 0) {
+            return {
+                error: 'no_pay_token_holdings',
+                _instructions: 'The wallet has no tokens that can pay for this purchase on this chain. Tell the user to top up first. Do NOT mention tool names, UI, or forms.',
+            };
+        }
+        // Prefer the caller's already-converted amounts (so "1$"/"50%" become a real
+        // token quantity in the click-prompt); fall back to re-parsing args.
+        const buyAmount = input.buyAmount ?? this.normaliseAmount(args.buy_amount);
+        const payAmount = input.payAmount ?? this.normaliseAmount(args.pay_with_amount);
+        // Click-prompt is re-submitted as a fresh user turn → phrase it in the
+        // user's language via the LLM-supplied "buy X with Y" template. The {token}
+        // is always the destination; {pay} is the chosen wallet token; {amount} is
+        // whichever side already has a value (buy amount rides with the dest token,
+        // pay amount rides with the pay token).
+        const buyWithTemplate = typeof args.buy_with_prompt_template === 'string' ? args.buy_with_prompt_template : '';
+        const actionButtons = holdings.map((t) => {
+            const sym = t.symbol;
+            const name = t.name?.trim() || sym;
+            const amount = t.balance_formatted ? `${this.cleanAmountString(t.balance_formatted)} ` : '';
+            const usdLabel = typeof t.usd_value === 'number' && t.usd_value > 0 ? ` ($${t.usd_value.toFixed(2)})` : '';
+            const label = `${name}: ${amount}${sym}${usdLabel}`;
+            // buy_amount sits next to the bought token ({buy_amount}); otherwise an
+            // optional pay_with_amount sits next to the pay token ({pay_amount}).
+            // Only one side ever carries an amount.
+            const prompt = buyAmount
+                ? this.buildBuyWithPrompt(buyWithTemplate, destSymbol, sym, buyAmount, null)
+                : this.buildBuyWithPrompt(buyWithTemplate, destSymbol, sym, null, payAmount);
+            return { label, prompt };
+        });
+        return {
+            actionButtons,
+            _instructions: `Reply briefly in the user's language: ask them to pick which token they want to spend to buy ${destSymbol} from the options below. Do NOT list the tokens in text. Do NOT mention tool names, UI, or forms.`,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Branch 1.4: balance check (pay token named — with or without an amount)
+    // -------------------------------------------------------------------------
+    /**
+     * Guard the buy flow against a pay token the user can't fund. Returns:
+     *   - `null` when the user holds enough (or no amount yet, or balances can't be read).
+     *   - `no_pay_balance` (+ picker buttons) when the wallet holds none of it.
+     *   - `insufficient_pay_balance` (+ percentage buttons) when it holds some but
+     *     less than the requested amount.
+     */
+    async checkPayBalance(input) {
+        const { args, userContext, chain, destSymbol, destContract, payAddr, payAmount, buyAmount, derivedFromBuy } = input;
+        const walletAddress = userContext.walletAddress;
+        const bal = await this.readPayBalance(walletAddress, payAddr, chain);
+        const paySymbol = input.paySymbol ?? bal?.symbol ?? 'the selected token';
+        // No holding at all: tell the user, then offer the tokens they DO hold.
+        if (!bal) {
+            this.dbg('checkPayBalance: NOT held → pay picker fallback', { paySymbol });
+            const picker = await this.buildPayWithPicker({
+                args,
+                userContext,
+                destSymbol,
+                destContract,
+                buyAmount,
+                payAmount,
+            });
+            if ('actionButtons' in picker) {
+                return {
+                    error: 'no_pay_balance',
+                    actionButtons: picker.actionButtons,
+                    _instructions: `The user wanted to spend ${paySymbol} to buy ${destSymbol}, but their wallet holds no ${paySymbol} on this chain. ` +
+                        `Tell them, in their language, that they don't have any ${paySymbol}, then say they can instead choose one of the tokens they already hold (shown below) to pay with. ` +
+                        'Do NOT list the tokens in text, do NOT invent a balance, and do NOT mention tool names, UI, or forms.',
+                };
+            }
+            return picker;
+        }
+        // No amount yet — the holding exists, so let the amount picker take over.
+        if (!payAmount)
+            return null;
+        // When the amount was SIZED OFF the balance (a percent / "max" / usd spec),
+        // it's already ≤ spendable by construction — skip the over-balance check.
+        // Re-checking would compare it against a freshly re-read spendable, which can
+        // drift a hair (the gas reserve is read from a separate RPC call), and a
+        // legitimate "max" would falsely trip as "insufficient". Only a plain
+        // user-typed amount ("buy USDC with 5 ETH") is genuinely checked.
+        if (input.amountSizedToBalance)
+            return null;
+        const wanted = Number(payAmount);
+        if (!Number.isFinite(wanted) || wanted <= bal.balanceNum)
+            return null;
+        // Holds some but not enough: report the shortfall + percentage options.
+        const spendable = this.trimAmount(bal.balanceNum);
+        const actionButtons = this.percentSpendButtons({
+            balanceFormatted: bal.balanceFormatted,
+            balanceNum: bal.balanceNum,
+            paySymbol,
+            destSymbol,
+            buyWithTemplate: typeof args.buy_with_prompt_template === 'string' ? args.buy_with_prompt_template : '',
+        });
+        // Frame the message by what the user actually said: a derived pay amount
+        // came from "buy X dest", so explain the conversion; otherwise they typed
+        // the pay amount directly.
+        const needLine = derivedFromBuy
+            ? `Buying ${derivedFromBuy} ${destSymbol} needs about ${payAmount} ${paySymbol}, but they only have ${spendable} ${paySymbol} on this chain — not enough. ` +
+                `Tell them, in their language, that buying ${derivedFromBuy} ${destSymbol} would cost about ${payAmount} ${paySymbol}, which is more than their balance of ${spendable} ${paySymbol}, and ask them to buy a smaller amount or spend less — `
+            : `The user wants to spend ${payAmount} ${paySymbol} to buy ${destSymbol}, but they only have ${spendable} ${paySymbol} on this chain — not enough. ` +
+                `Tell them, in their language, that ${payAmount} ${paySymbol} exceeds their balance of ${spendable} ${paySymbol}, and ask them to pick a smaller amount — `;
+        return {
+            error: 'insufficient_pay_balance',
+            actionButtons,
+            _instructions: needLine +
+                'invite them to choose one of the options below (sized to their balance) or type the amount they want. ' +
+                'CRITICAL: clickable percentage buttons are rendered separately below your message — your text must NOT contain any "%", percentage values, or a list of amounts (no "25%", "50%", "75%", "100%"). ' +
+                'Do NOT invent numbers, and do NOT mention tool names, UI, buttons, or forms.',
+        };
+    }
+    /**
+     * Read the connected wallet's balance of the pay token. Returns the held
+     * amount + on-chain symbol, or `null` when balances can't be fetched / the
+     * token isn't held (zero balance or not held at all).
+     *
+     * For the NATIVE pay coin the returned balance is the SPENDABLE figure — the
+     * held balance minus a silently-estimated swap gas reserve (gasLimit
+     * 1_000_000 × gasPrice) — so the percent buttons, amount picker, and balance
+     * check stay within what the user can actually spend while still covering gas.
+     * The reserve is never surfaced; callers only ever expose the spendable
+     * number. ERC-20 pay tokens are returned at their raw held balance (gas is
+     * paid in the native coin, not the pay token).
+     */
+    async readPayBalance(walletAddress, payAddr, chain) {
+        if (!this.moralis)
+            return null;
+        const balancesRes = await this.moralis.getWalletTokenBalances({
+            address: walletAddress,
+            chain,
+            excludeSpam: true,
+            excludeUnverifiedContracts: true,
+        });
+        const balances = balancesRes.success ? (balancesRes.data?.result ?? []) : [];
+        this.dbg('readPayBalance', {
+            payAddr,
+            chain,
+            ok: balancesRes.success,
+            count: balances.length,
+            held: balances.map((t) => ({ sym: t.symbol, addr: t.token_address, bal: t.balance_formatted })),
+        });
+        const payLower = payAddr.toLowerCase();
+        const payBal = balances.find((t) => payLower === 'native' ? t.native_token === true : t.token_address?.toLowerCase() === payLower);
+        if (!payBal?.balance_formatted) {
+            this.dbg('readPayBalance: pay token NOT held → null', { payAddr });
+            return null;
+        }
+        const balanceNum = Number(payBal.balance_formatted);
+        if (!Number.isFinite(balanceNum) || balanceNum <= 0) {
+            this.dbg('readPayBalance: zero/invalid balance → null', { payAddr, balance: payBal.balance_formatted });
+            return null;
+        }
+        // Native pay coin: reduce to the spendable balance so we never quote/size a
+        // buy that would leave the user unable to pay gas.
+        if (payLower === 'native' && chain) {
+            const reserve = await (0, gasReserve_1.estimateNativeGasReserveWei)(chain, 'swap');
+            const spendable = (0, gasReserve_1.spendableNative)(balanceNum, reserve, chain);
+            this.dbg('readPayBalance: native spendable', { balanceNum, spendable });
+            if (spendable <= 0) {
+                this.dbg('readPayBalance: native spendable ≤ 0 → null', { balanceNum });
+                return null;
+            }
+            const spendableStr = this.trimAmount(spendable);
+            return { balanceFormatted: spendableStr, balanceNum: spendable, symbol: payBal.symbol };
+        }
+        this.dbg('readPayBalance: held', { payAddr, balance: payBal.balance_formatted, symbol: payBal.symbol });
+        return { balanceFormatted: payBal.balance_formatted, balanceNum, symbol: payBal.symbol };
+    }
+    /**
+     * 25/50/75/100% quick-spend buttons sized off a held balance. 100% spends the
+     * EXACT held string; the partial fractions are float-trimmed. The amount rides
+     * in the prompt; the label is a bare percent.
+     */
+    percentSpendButtons(input) {
+        const { balanceFormatted, balanceNum, paySymbol, destSymbol, buyWithTemplate } = input;
+        const fractions = [0.25, 0.5, 0.75, 1];
+        return fractions.map((f) => {
+            const amount = f === 1 ? this.cleanAmountString(balanceFormatted) : this.trimAmount(balanceNum * f);
+            // The percentage amount is the PAY amount → it rides with the pay token
+            // ({pay_amount}), never with the bought token.
+            return {
+                label: `${Math.round(f * 100)}%`,
+                prompt: this.buildBuyWithPrompt(buyWithTemplate, destSymbol, paySymbol, null, amount),
+            };
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Branch 1.5: amount picker (dest + pay known, no amount given)
+    // -------------------------------------------------------------------------
+    async buildAmountPicker(input) {
+        const { userContext, chain, destSymbol, payAddr, buyWithTemplate } = input;
+        const walletAddress = userContext.walletAddress;
+        const bal = await this.readPayBalance(walletAddress, payAddr, chain);
+        const paySymbol = input.paySymbol ?? bal?.symbol;
+        if (!bal || !paySymbol)
+            return null;
+        const actionButtons = this.percentSpendButtons({
+            balanceFormatted: bal.balanceFormatted,
+            balanceNum: bal.balanceNum,
+            paySymbol,
+            destSymbol,
+            buyWithTemplate,
+        });
+        const spendable = this.trimAmount(bal.balanceNum);
+        return {
+            actionButtons,
+            _instructions: `The user's spendable balance is ${spendable} ${paySymbol}. Reply briefly in the user's language: tell them their spendable ${paySymbol} balance and ask how much they want to spend to buy ${destSymbol}, inviting them to choose one of the options below or type the amount they want. CRITICAL: clickable percentage buttons are rendered separately below your message — your text must NOT contain any "%", percentage values, or a list of amounts (no "25%", "50%", "75%", "100%"). Just ask the question. Do NOT mention tool names, UI, buttons, or forms.`,
+        };
+    }
+    /**
+     * Trim IEEE-754 noise from a computed amount (≤8 significant digits) and
+     * ALWAYS return plain decimal notation — never exponential ("1.5e-7").
+     */
+    trimAmount(value) {
+        if (!Number.isFinite(value))
+            return '0';
+        return this.toPlainDecimal(parseFloat(value.toPrecision(8)));
+    }
+    /** Format a number as a plain decimal string, expanding any e-notation. */
+    toPlainDecimal(n) {
+        const s = String(n);
+        if (!/e/i.test(s))
+            return s;
+        const neg = n < 0;
+        const [mantissa, expPart] = Math.abs(n).toString().split('e');
+        const exp = Number(expPart);
+        const [intPart, fracPart = ''] = mantissa.split('.');
+        const digits = intPart + fracPart;
+        let out;
+        if (exp >= 0) {
+            const pointPos = intPart.length + exp;
+            out =
+                pointPos >= digits.length
+                    ? digits.padEnd(pointPos, '0')
+                    : `${digits.slice(0, pointPos)}.${digits.slice(pointPos)}`;
+        }
+        else {
+            out = `0.${'0'.repeat(-exp - intPart.length)}${digits}`;
+        }
+        if (out.includes('.'))
+            out = out.replace(/\.?0+$/, '');
+        return neg ? `-${out}` : out;
+    }
+    /**
+     * Sanitize an amount STRING from an external source (e.g. Moralis
+     * `balance_formatted`): expand e-notation to plain decimal; else pass through.
+     */
+    cleanAmountString(s) {
+        if (!/e/i.test(s))
+            return s;
+        const n = Number(s);
+        return Number.isFinite(n) ? this.toPlainDecimal(n) : s;
+    }
+    /**
+     * Build the trending-picker click-prompt ("buy {token}") from the
+     * LLM-supplied, already-localized template. The click-prompt is re-submitted
+     * as a fresh user turn, so keeping it in the user's language keeps that turn
+     * in the same language. Falls back to English when the LLM omits a template.
+     */
+    buildBuyPrompt(template, token) {
+        const tpl = template && template.includes('{token}') ? template : 'buy {token}';
+        return tpl
+            .replace(/\{token\}/g, token)
+            .replace(/\s+/g, ' ')
+            .trim();
+    }
+    /**
+     * Build the "buy X with Y" click-prompt from the LLM-supplied, already-
+     * localized template by substituting placeholders:
+     *   {token} → token bought    {pay} → payment token
+     *   {buy_amount} → quantity bought (next to {token})
+     *   {pay_amount} → quantity paid  (next to {pay})
+     * The localized verb and "with" preposition live INSIDE the template, so we
+     * only substitute concrete values. Only one side ever carries an amount; the
+     * unused amount placeholder is replaced with '' (no preposition is attached
+     * to it, so nothing dangles). Falls back to an English template when the LLM
+     * omits one.
+     */
+    buildBuyWithPrompt(template, token, pay, buyAmount, payAmount) {
+        const tpl = template && template.includes('{token}') && template.includes('{pay}')
+            ? template
+            : 'buy {buy_amount} {token} with {pay_amount} {pay}';
+        return tpl
+            .replace(/\{token\}/g, token)
+            .replace(/\{pay\}/g, pay)
+            .replace(/\{buy_amount\}/g, buyAmount ?? '')
+            .replace(/\{pay_amount\}/g, payAmount ?? '')
+            .replace(/\s+/g, ' ')
+            .trim();
+    }
+    // -------------------------------------------------------------------------
+    // Branch 0: trending picker (user wants to buy but named no token)
+    // -------------------------------------------------------------------------
+    async buildTrendingPicker(args, userContext) {
+        if (!this.pantograph) {
+            return {
+                error: 'trending_unavailable',
+                _instructions: 'Trending tokens are unavailable in this build (service not configured). Tell the user briefly and ask them to name a token to buy.',
+            };
+        }
+        const chain = this.requireChain(args, userContext) ?? undefined;
+        const requestedLimit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.floor(args.limit) : 6;
+        const limit = Math.max(1, Math.min(10, requestedLimit));
+        const res = await this.pantograph.getTrendingTokens({ chain, limit });
+        const list = res.success ? (res.data ?? []) : [];
+        if (list.length === 0) {
+            return {
+                error: 'no_trending_tokens',
+                _instructions: 'No trending tokens are available for this chain right now. Tell the user briefly and suggest they name a token directly.',
+            };
+        }
+        const tokens = list.filter((t) => t.symbol);
+        // Click-prompt is re-submitted as a fresh user turn → phrase it in the
+        // user's language using the LLM-supplied localized template.
+        const buyTemplate = typeof args.buy_prompt_template === 'string' ? args.buy_prompt_template : '';
+        const actionButtons = tokens.map((t) => {
+            const sym = t.symbol;
+            return { label: sym, prompt: this.buildBuyPrompt(buyTemplate, sym) };
+        });
+        const lines = tokens.map((t, i) => {
+            const name = t.name?.trim() || t.symbol;
+            const sym = t.symbol;
+            const priceLabel = typeof t.usdPrice === 'number' && t.usdPrice > 0 ? `$${this.formatPrice(t.usdPrice)}` : 'N/A';
+            const change = t.pricePercentChange?.['24h'];
+            const hasChange = typeof change === 'number' && Number.isFinite(change);
+            const arrow = hasChange ? (change > 0 ? '▲' : change < 0 ? '▼' : '▪') : '';
+            const changeLabel = hasChange ? ` (${arrow} ${this.formatPercent(change)}%)` : '';
+            return `${i + 1}. ${name} (${sym})\n${priceLabel}${changeLabel}`;
+        });
+        const listText = lines.join('\n-----\n') + `\n---\nIs there any token you want to buy?`;
+        return {
+            actionButtons,
+            _instructions: `The trending tokens are on chain id "${chain ?? 'the connected chain'}" — use the human-readable chain name. ` +
+                `Reply in the user's language. Start with a one-line header like "📈 Here is the list of tokens that are currently trending upwards on <chain name> chain", then output EXACTLY the following list, preserving the line breaks, ordering, prices, and percentages verbatim (translate only the wording, never the numbers). Do NOT add or remove tokens, and do NOT mention tool names, UI, or forms:\n\n${listText}`,
+        };
+    }
+    /**
+     * Format a 24h price-change percentage: ~6 significant digits, no trailing
+     * noise, and always plain decimal (never exponential for a tiny change).
+     */
+    formatPercent(value) {
+        if (!Number.isFinite(value))
+            return '0';
+        return this.toPlainDecimal(parseFloat(value.toPrecision(6)));
+    }
+    /** Compact price string: e.g. 0.00001234 → "0.00001234", 1234.5 → "1,234.50". */
+    formatPrice(price) {
+        if (price >= 1)
+            return price.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+        if (price >= 0.01)
+            return price.toFixed(4);
+        const str = price.toFixed(12);
+        const match = str.match(/^0\.0*([1-9]\d{0,3})/);
+        return match ? str.slice(0, (match[0].length || 0) + 0) : str;
+    }
+}
+exports.BuyTokenTool = BuyTokenTool;
+//# sourceMappingURL=BuyTokenTool.js.map