@lightspeed-cli/speed-cli 0.1.0

package/dist/commands/dca.js

@@ -0,0 +1,175 @@
+import { Command } from "commander";
+import { ethers } from "ethers";
+import ora from "ora";
+import { getSigner } from "../wallet.js";
+import { executeSwap } from "../lib/swap-execute.js";
+import { getEthUsdPriceNumber } from "../lib/oracle.js";
+import { recordXpAction } from "../lib/xp.js";
+import { parseTokenAmountToWei } from "../lib/parse-amount.js";
+import { resolveChainId, getChainOptionsHint, resolveTokenAddress, NATIVE_ETH_0X, EXPLORER_URLS, } from "../constants.js";
+import { getDefaultChainInput } from "./config.js";
+import { out, exitWithError, setJsonMode, isJsonMode, success, usageHint } from "../output.js";
+/** Minimum ETH (wei) per buy so 0x doesn't get dust or revert. 0.0001 ETH */
+const MIN_BUY_WEI = 10n ** 14n;
+/**
+ * Parse interval to seconds. Accepts:
+ * - Number: "300" → 300
+ * - Suffix: "5m", "1h", "1d" (case-insensitive)
+ */
+function parseIntervalSeconds(input) {
+    const s = input.trim().toLowerCase();
+    const match = s.match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)?$/);
+    if (!match) {
+        throw new Error(`Invalid interval "${input}". Use seconds (e.g. 300) or 5m, 1h, 1d`);
+    }
+    const num = parseFloat(match[1]);
+    const unit = match[2] ?? "s";
+    const multipliers = { s: 1, m: 60, h: 3600, d: 86400 };
+    const sec = Math.round(num * multipliers[unit]);
+    if (sec < 1)
+        throw new Error("Interval must be at least 1 second.");
+    return sec;
+}
+function jitteredDelaySeconds(centerSec, jitterFraction) {
+    if (jitterFraction <= 0)
+        return centerSec;
+    const jitter = (2 * Math.random() - 1) * jitterFraction;
+    const sec = centerSec * (1 + jitter);
+    return Math.max(1, Math.round(sec));
+}
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function dcaCmd() {
+    return new Command("dca")
+        .description("DCA (dollar-cost average): buy token with ETH on a fixed time interval. Default token is Speed; use --token for others.")
+        .option("-c, --chain <id|name>", "Chain ID or name", "8453")
+        .option("-t, --token <address|speed>", "Token to buy with ETH (default: Speed)", "")
+        .option("-a, --amount <amount>", "ETH per buy in token units (e.g. 0.001, 0.1)", "")
+        .option("--interval <seconds|5m|1h|1d>", "Time between buys (seconds or 5m, 1h, 1d)", "300")
+        .option("--interval-jitter <fraction>", "Random ± on interval (e.g. 0.2 = ±20%)", "0")
+        .option("--count <n>", "Number of buys to do (default: run until stopped)", "")
+        .option("--dry-run", "Do not send any transactions")
+        .action(async function (opts) {
+        setJsonMode(this.parent?.opts().json ?? false);
+        const chainId = resolveChainId(opts.chain ?? getDefaultChainInput());
+        if (chainId === null) {
+            exitWithError(`Unknown chain "${opts.chain}". Use one of: ${getChainOptionsHint()}.${usageHint("dca")}`, "INVALID_CHAIN");
+        }
+        if (!opts.amount?.trim()) {
+            exitWithError("--amount is required. Example: speed dca -c base -a 0.001 --interval 5m", "MISSING_ARGS");
+        }
+        const tokenAddress = resolveTokenAddress(opts.token);
+        const amountWei = parseTokenAmountToWei(opts.amount.trim());
+        if (BigInt(amountWei) < MIN_BUY_WEI) {
+            exitWithError(`Amount must be at least ${ethers.formatEther(MIN_BUY_WEI.toString())} ETH.` + usageHint("dca"), "INVALID_AMOUNT");
+        }
+        let intervalSec;
+        try {
+            intervalSec = parseIntervalSeconds(opts.interval ?? "300");
+        }
+        catch (e) {
+            exitWithError((e instanceof Error ? e.message : String(e)) + usageHint("dca"), "INVALID_INTERVAL");
+        }
+        const intervalJitter = parseFloat(opts.intervalJitter ?? "0");
+        const countOpt = opts.count?.trim();
+        const count = countOpt ? parseInt(countOpt, 10) : null;
+        if (countOpt !== undefined && countOpt !== "") {
+            if (count === null || !Number.isInteger(count) || count < 1) {
+                exitWithError("--count must be an integer >= 1." + usageHint("dca"), "INVALID_COUNT");
+            }
+        }
+        if (opts.dryRun) {
+            if (isJsonMode()) {
+                out({
+                    dryRun: true,
+                    chainId,
+                    amountWei,
+                    intervalSec,
+                    intervalJitter,
+                    count: count ?? "until stopped",
+                });
+            }
+            else {
+                out(`Dry run: buy ${ethers.formatEther(amountWei)} ETH → SPEED every ~${intervalSec}s${intervalJitter ? ` ±${intervalJitter * 100}%` : ""}`);
+                out(count != null ? `Planned buys: ${count}` : "Run until you stop (Ctrl+C).");
+                out("Re-run without --dry-run to execute.");
+            }
+            return;
+        }
+        const signer = getSigner(chainId);
+        let ethUsd = 0;
+        try {
+            ethUsd = await getEthUsdPriceNumber(chainId);
+        }
+        catch (_) { }
+        const results = [];
+        const failures = [];
+        let buyNumber = 0;
+        const runUntilStopped = count == null;
+        if (!isJsonMode()) {
+            out(`DCA: buying ${ethers.formatEther(amountWei)} ETH → SPEED every ~${intervalSec}s${intervalJitter ? ` (±${intervalJitter * 100}% jitter)` : ""} on chain ${chainId}.`);
+            if (runUntilStopped)
+                out("Running until you stop (Ctrl+C).");
+            else
+                out(`Will perform ${count} buy(s).`);
+        }
+        const runOne = async () => {
+            buyNumber++;
+            const spinner = isJsonMode() ? null : ora(`DCA buy ${buyNumber}${runUntilStopped ? "" : `/${count}`}...`).start();
+            try {
+                const { txHash } = await executeSwap(chainId, signer, NATIVE_ETH_0X, tokenAddress, amountWei);
+                if (spinner)
+                    spinner.succeed(`Buy ${buyNumber} confirmed`);
+                results.push({ buy: buyNumber, txHash, amountWei });
+                try {
+                    const usd = parseFloat(ethers.formatEther(amountWei)) * ethUsd;
+                    recordXpAction("dcaBuy", usd);
+                }
+                catch (_) { }
+                return true;
+            }
+            catch (e) {
+                if (spinner)
+                    spinner.fail(`Buy ${buyNumber} failed`);
+                const msg = e instanceof Error ? e.message : String(e);
+                failures.push({ buy: buyNumber, error: msg });
+                if (!isJsonMode())
+                    out(`  → ${msg.slice(0, 80)}${msg.length > 80 ? "…" : ""}`);
+                return false;
+            }
+        };
+        // First buy immediately (or after a short delay so user sees the message)
+        await runOne();
+        const explorer = EXPLORER_URLS[chainId];
+        while (true) {
+            if (count != null && buyNumber >= count)
+                break;
+            const waitSec = jitteredDelaySeconds(intervalSec, intervalJitter);
+            await sleepMs(waitSec * 1000);
+            if (count != null && buyNumber >= count)
+                break;
+            await runOne();
+        }
+        if (isJsonMode()) {
+            out({
+                summary: { buys: results.length, failed: failures.length, totalAttempts: buyNumber },
+                results: results.map((r) => ({
+                    ...r,
+                    explorerLink: explorer ? `${explorer}/tx/${r.txHash}` : r.txHash,
+                })),
+                failures: failures.length ? failures : undefined,
+            });
+        }
+        else {
+            success(`DCA complete: ${results.length} buys${failures.length ? `, ${failures.length} failed` : ""} (${buyNumber} attempts)`);
+            results.forEach((r) => {
+                const link = explorer ? `${explorer}/tx/${r.txHash}` : r.txHash;
+                out(`  buy ${r.buy}: ${link}`);
+            });
+            if (failures.length) {
+                out(`Failed: ${failures.map((f) => `buy ${f.buy}`).join(", ")}`);
+            }
+        }
+    });
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function doctorCmd(): Command;

package/dist/commands/doctor.js

@@ -0,0 +1,113 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { getAddress, getPrivateKeyForValidation } from "../wallet.js";
+import { getRpcUrl } from "../rpc.js";
+import { getEthUsdPrice } from "../lib/oracle.js";
+import { SPEED_TOKEN_ADDRESS, SUPPORTED_CHAIN_IDS, CHAIN_NAMES, resolveChainId, getChainOptionsHint } from "../constants.js";
+import { getDefaultChainInput } from "./config.js";
+import { ethers } from "ethers";
+import { out, exitWithError, setJsonMode, isJsonMode, success, usageHint } from "../output.js";
+const check = chalk.green("✓");
+const cross = chalk.red("✗");
+const ERC20_ABI = ["function balanceOf(address) view returns (uint256)"];
+export function doctorCmd() {
+    return new Command("doctor")
+        .description("Validate env: PRIVATE_KEY, API keys, RPC, oracle, Speed balance")
+        .option("-c, --chain <id|name>", "Default chain to check balance", "8453")
+        .action(async function (opts) {
+        setJsonMode(this.parent?.opts().json ?? false);
+        const defaultChainResolved = resolveChainId(opts.chain ?? getDefaultChainInput());
+        if (defaultChainResolved === null) {
+            exitWithError(`Unknown chain "${opts.chain}". Use one of: ${getChainOptionsHint()}.${usageHint("doctor")}`, "INVALID_CHAIN");
+        }
+        const defaultChain = defaultChainResolved;
+        const checks = {};
+        let ok = true;
+        let walletAddress = null;
+        try {
+            getPrivateKeyForValidation();
+            walletAddress = getAddress();
+            checks.PRIVATE_KEY = true;
+        }
+        catch {
+            checks.PRIVATE_KEY = false;
+            ok = false;
+        }
+        checks["0X_API_KEY"] = !!(process.env["0X_API_KEY"] ?? process.env["OX_API_KEY"])?.trim();
+        checks.SQUID_INTEGRATOR_ID = !!process.env.SQUID_INTEGRATOR_ID?.trim();
+        checks.ALCHEMY_API_KEY = !!process.env.ALCHEMY_API_KEY?.trim();
+        const rpcResults = await Promise.allSettled(SUPPORTED_CHAIN_IDS.map(async (chainId) => {
+            const url = getRpcUrl(chainId);
+            const provider = new ethers.JsonRpcProvider(url);
+            await provider.getBlockNumber();
+            return chainId;
+        }));
+        for (let i = 0; i < SUPPORTED_CHAIN_IDS.length; i++) {
+            const passed = rpcResults[i].status === "fulfilled";
+            checks[`RPC_${SUPPORTED_CHAIN_IDS[i]}`] = passed;
+            if (!passed)
+                ok = false;
+        }
+        const oracleResults = await Promise.allSettled(SUPPORTED_CHAIN_IDS.map((chainId) => getEthUsdPrice(chainId)));
+        for (let i = 0; i < SUPPORTED_CHAIN_IDS.length; i++) {
+            const passed = oracleResults[i].status === "fulfilled";
+            checks[`ORACLE_${SUPPORTED_CHAIN_IDS[i]}`] = passed;
+            if (!passed)
+                ok = false;
+        }
+        try {
+            if (!walletAddress) {
+                checks[`SPEED_BALANCE_${defaultChain}`] = false;
+                ok = false;
+            }
+            else {
+                const provider = new ethers.JsonRpcProvider(getRpcUrl(defaultChain));
+                const token = new ethers.Contract(SPEED_TOKEN_ADDRESS, ERC20_ABI, provider);
+                const bal = await token.balanceOf(walletAddress);
+                checks[`SPEED_BALANCE_${defaultChain}`] = ethers.formatUnits(bal, 18);
+            }
+        }
+        catch {
+            checks[`SPEED_BALANCE_${defaultChain}`] = false;
+            ok = false;
+        }
+        if (isJsonMode()) {
+            out({ ok, checks });
+        }
+        else {
+            out(chalk.bold("Env"));
+            out(`  PRIVATE_KEY         ${checks.PRIVATE_KEY === true ? check : cross}`);
+            out(`  0X_API_KEY          ${checks["0X_API_KEY"] ? check : cross}`);
+            out(`  SQUID_INTEGRATOR_ID ${checks.SQUID_INTEGRATOR_ID ? check : cross}`);
+            out(`  ALCHEMY_API_KEY     ${checks.ALCHEMY_API_KEY ? check : cross}`);
+            out("");
+            out(chalk.bold("RPC"));
+            for (const chainId of SUPPORTED_CHAIN_IDS) {
+                const name = (CHAIN_NAMES[chainId] ?? String(chainId)).padEnd(10);
+                out(`  ${name} (${chainId})  ${checks[`RPC_${chainId}`] === true ? check : cross}`);
+            }
+            out("");
+            out(chalk.bold("Oracle"));
+            for (const chainId of SUPPORTED_CHAIN_IDS) {
+                const name = (CHAIN_NAMES[chainId] ?? String(chainId)).padEnd(10);
+                out(`  ${name} (${chainId})  ${checks[`ORACLE_${chainId}`] === true ? check : cross}`);
+            }
+            out("");
+            out(chalk.bold("Balance"));
+            const balKey = `SPEED_BALANCE_${defaultChain}`;
+            const balVal = checks[balKey];
+            const chainName = CHAIN_NAMES[defaultChain] ?? String(defaultChain);
+            if (balVal === false) {
+                out(`  ${chainName} (${defaultChain})  ${cross}`);
+            }
+            else {
+                out(`  ${chainName} (${defaultChain})  ${String(balVal)} SPEED`);
+            }
+            out("");
+            if (ok)
+                success("All checks passed.");
+            else
+                process.exit(1);
+        }
+    });
+}

package/dist/commands/estimate.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function estimateCmd(): Command;

package/dist/commands/estimate.js

@@ -0,0 +1,57 @@
+import { Command } from "commander";
+import { ethers } from "ethers";
+import { getSigner } from "../wallet.js";
+import { get0xQuote } from "../lib/zerox.js";
+import { parseTokenAmountToWei } from "../lib/parse-amount.js";
+import { getEthUsdPriceNumber } from "../lib/oracle.js";
+import { resolveChainId, getChainOptionsHint } from "../constants.js";
+import { getDefaultChainInput } from "./config.js";
+import { out, exitWithError, setJsonMode, isJsonMode, usageHint } from "../output.js";
+export function estimateCmd() {
+    return new Command("estimate")
+        .description("Dry-run swap or bridge; gas cost in ETH and USD (USD from oracle)")
+        .option("-c, --chain <id|name>", "Chain ID or name", "8453")
+        .option("--sell <address>", "Sell token (default: Speed)")
+        .option("--buy <address>", "Buy token")
+        .option("-a, --amount <amount>", "Sell amount in token units (e.g. 0.002, 1000)")
+        .option("--bridge", "Estimate bridge instead of swap (requires --to-chain)")
+        .option("--to-chain <id|name>", "Destination chain for bridge")
+        .action(async function (opts) {
+        setJsonMode(this.parent?.opts().json ?? false);
+        const chainId = resolveChainId(opts.chain ?? getDefaultChainInput());
+        if (chainId === null) {
+            exitWithError(`Unknown chain "${opts.chain}". Use one of: ${getChainOptionsHint()}.${usageHint("estimate")}`, "INVALID_CHAIN");
+        }
+        try {
+            const signer = getSigner(chainId);
+            const taker = await signer.getAddress();
+            let gasLimit = 200000n;
+            if (opts.bridge && opts.toChain) {
+                gasLimit = 350000n;
+            }
+            else if (opts.buy && opts.amount) {
+                const sellToken = opts.sell?.trim() ?? "0xB01CF1bE9568f09449382a47Cd5bF58e2A9D5922";
+                const amountWei = parseTokenAmountToWei(opts.amount.trim());
+                const quote = await get0xQuote(chainId, sellToken, opts.buy.trim(), amountWei, taker);
+                if (quote.gas)
+                    gasLimit = BigInt(quote.gas);
+            }
+            const feeData = await signer.provider.getFeeData();
+            const gasPrice = feeData.gasPrice ?? 0n;
+            const gasWei = gasLimit * gasPrice;
+            const gasEth = ethers.formatEther(gasWei);
+            const ethUsd = await getEthUsdPriceNumber(chainId);
+            const gasUsd = (parseFloat(gasEth) * ethUsd).toFixed(2);
+            if (isJsonMode()) {
+                out({ gasEth, gasUsd, gasLimit: gasLimit.toString(), gasPrice: gasPrice.toString() });
+            }
+            else {
+                out(`Estimated gas: ${gasEth} ETH (~$${gasUsd})`);
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            exitWithError(`${msg}.${usageHint("estimate")}`, "ESTIMATE_ERROR");
+        }
+    });
+}

package/dist/commands/gas.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function gasCmd(): Command;

package/dist/commands/gas.js

@@ -0,0 +1,128 @@
+import { Command } from "commander";
+import { createInterface } from "readline";
+import ora from "ora";
+import { ethers } from "ethers";
+import { getSigner } from "../wallet.js";
+import { get0xQuote } from "../lib/zerox.js";
+import { getEthUsdPriceNumber, getSpeedUsdPriceNumber } from "../lib/oracle.js";
+import { recordXpAction } from "../lib/xp.js";
+import { EXPLORER_URLS, resolveTokenAddress, SPEED_TOKEN_ADDRESS, WRAPPED_NATIVE_ADDRESS, NATIVE_SYMBOL, resolveChainId, getChainOptionsHint, } from "../constants.js";
+import { getDefaultChainInput } from "./config.js";
+import { out, exitWithError, setJsonMode, isJsonMode, success, usageHint } from "../output.js";
+import { parseTokenAmountToWei } from "../lib/parse-amount.js";
+const ERC20_ABI = ["function approve(address spender, uint256 amount) returns (bool)"];
+const WETH_ABI = ["function withdraw(uint256 wad)"];
+function askConfirm(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(/^y|yes$/i.test(answer.trim()));
+        });
+    });
+}
+export function gasCmd() {
+    return new Command("gas")
+        .description("Swap token → native (ETH/MATIC/BNB) to fund gas. Default token is Speed; use --token for others.")
+        .option("-c, --chain <id|name>", "Chain ID or name", "8453")
+        .option("-t, --token <address|speed>", "Token to sell for native (default: Speed)", "")
+        .option("-a, --amount <amount>", "Amount of token to sell (e.g. 0.1, 10000)")
+        .action(async function (opts) {
+        setJsonMode(this.parent?.opts().json ?? false);
+        const yes = this.parent?.opts().yes ?? false;
+        const chainId = resolveChainId(opts.chain ?? getDefaultChainInput());
+        if (chainId === null) {
+            exitWithError(`Unknown chain "${opts.chain}". Use one of: ${getChainOptionsHint()}.${usageHint("gas")}`, "INVALID_CHAIN");
+        }
+        const wrappedNative = WRAPPED_NATIVE_ADDRESS[chainId];
+        if (!wrappedNative) {
+            exitWithError(`No wrapped native address for chain ${chainId}`, "UNSUPPORTED_CHAIN");
+        }
+        if (!opts.amount?.trim()) {
+            exitWithError("--amount is required. Example: speed gas -c base -a 0.1", "MISSING_ARGS");
+        }
+        const tokenAddress = resolveTokenAddress(opts.token);
+        const amount = parseTokenAmountToWei(opts.amount.trim());
+        const nativeSymbol = NATIVE_SYMBOL[chainId] ?? "ETH";
+        try {
+            const signer = getSigner(chainId);
+            const taker = await signer.getAddress();
+            const spinner = isJsonMode() ? null : ora("Fetching quote (token → native)...").start();
+            const quote = await get0xQuote(chainId, tokenAddress, wrappedNative, amount, taker);
+            if (spinner)
+                spinner.succeed("Quote received");
+            if (!quote.transaction?.to || !quote.transaction?.data) {
+                exitWithError("No transaction in quote (0x returned no fill). Try a different amount or chain." + usageHint("gas"), "QUOTE_ERROR");
+            }
+            let gasEth = "0";
+            let gasUsd = "0";
+            try {
+                const gasLimit = quote.gas ? BigInt(quote.gas) : 200000n;
+                const feeData = await signer.provider.getFeeData();
+                const gasPrice = feeData.gasPrice ?? 0n;
+                gasEth = ethers.formatEther(gasLimit * gasPrice);
+                const ethUsd = await getEthUsdPriceNumber(chainId);
+                gasUsd = (parseFloat(gasEth) * ethUsd).toFixed(2);
+            }
+            catch (_) { }
+            if (!yes && !isJsonMode()) {
+                const sellHuman = ethers.formatEther(amount);
+                const receiveHuman = ethers.formatEther(quote.buyAmount);
+                out(`Sell ${parseFloat(sellHuman).toLocaleString(undefined, { maximumFractionDigits: 6 })} SPEED for ~${parseFloat(receiveHuman).toLocaleString(undefined, { maximumFractionDigits: 6 })} ${nativeSymbol} on chain ${chainId}`);
+                out(`Estimated gas: ${gasEth} ETH (~$${gasUsd})`);
+                const ok = await askConfirm("Proceed? [y/N] ");
+                if (!ok) {
+                    out("Aborted.");
+                    process.exit(0);
+                }
+            }
+            if (quote.issues?.allowance?.spender) {
+                const approveSpinner = isJsonMode() ? null : ora("Approving...").start();
+                const token = new ethers.Contract(tokenAddress, ERC20_ABI, signer);
+                const txApprove = await token.approve(quote.allowanceTarget ?? quote.issues.allowance.spender, amount);
+                await txApprove.wait();
+                if (approveSpinner)
+                    approveSpinner.succeed("Approved");
+            }
+            const execSpinner = isJsonMode() ? null : ora("Executing swap...").start();
+            const tx = await signer.sendTransaction({
+                to: quote.transaction.to,
+                data: quote.transaction.data,
+                value: quote.transaction.value ? BigInt(quote.transaction.value) : 0n,
+                gasLimit: quote.gas ? BigInt(quote.gas) : undefined,
+            });
+            await tx.wait();
+            if (execSpinner)
+                execSpinner.succeed("Swap confirmed");
+            const unwrapSpinner = isJsonMode() ? null : ora("Unwrapping to native...").start();
+            const weth = new ethers.Contract(wrappedNative, WETH_ABI, signer);
+            const txUnwrap = await weth.withdraw(quote.buyAmount);
+            await txUnwrap.wait();
+            if (unwrapSpinner)
+                unwrapSpinner.succeed(`Received native ${nativeSymbol}`);
+            try {
+                const amountNum = parseFloat(ethers.formatEther(amount));
+                const speedUsd = tokenAddress.toLowerCase() === SPEED_TOKEN_ADDRESS.toLowerCase()
+                    ? await getSpeedUsdPriceNumber(chainId)
+                    : 0;
+                recordXpAction("gasRefuel", amountNum * speedUsd);
+            }
+            catch (_) { }
+            const explorer = EXPLORER_URLS[chainId];
+            const link = explorer ? `${explorer}/tx/${tx.hash}` : tx.hash;
+            if (isJsonMode()) {
+                out({ swapTxHash: tx.hash, unwrapTxHash: txUnwrap.hash, explorerLink: link, nativeReceived: quote.buyAmount });
+            }
+            else {
+                success(`Swap: ${tx.hash}`);
+                out(`Unwrap: ${txUnwrap.hash}`);
+                if (explorer)
+                    out(link);
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            exitWithError(`${msg}.${usageHint("gas")}`, "GAS_ERROR");
+        }
+    });
+}

package/dist/commands/history.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function historyCmd(): Command;

package/dist/commands/history.js

@@ -0,0 +1,91 @@
+import { Command } from "commander";
+import { getAddress } from "../wallet.js";
+import { getTransfers } from "../lib/alchemy-history.js";
+import { EXPLORER_URLS, SUPPORTED_CHAIN_IDS, CHAIN_NAMES, resolveChainId, getChainOptionsHint } from "../constants.js";
+import { out, exitWithError, setJsonMode, isJsonMode, usageHint } from "../output.js";
+import { ethers } from "ethers";
+function formatTimeStamp(ts) {
+    if (!ts)
+        return "—";
+    const d = new Date(ts);
+    if (Number.isNaN(d.getTime()))
+        return ts;
+    return d.toISOString().replace("T", " ").slice(0, 19);
+}
+/** Format value for display. Native (external/internal) may be wei; ERC20 is usually human. */
+function formatValue(valueStr, category) {
+    const n = parseFloat(valueStr);
+    if (Number.isNaN(n))
+        return valueStr;
+    if (n === 0)
+        return "0";
+    const isNative = category === "external" || category === "internal";
+    if (isNative && n >= 1e12) {
+        try {
+            const wei = BigInt(valueStr.split(".")[0] ?? valueStr);
+            return ethers.formatEther(wei);
+        }
+        catch {
+            // fall through to number format
+        }
+    }
+    if (n >= 1000)
+        return n.toLocaleString(undefined, { maximumFractionDigits: 2 });
+    if (n >= 1)
+        return n.toLocaleString(undefined, { maximumFractionDigits: 4 });
+    if (n >= 0.0001)
+        return n.toLocaleString(undefined, { maximumFractionDigits: 6 });
+    if (n > 0)
+        return n.toExponential(2);
+    return valueStr;
+}
+export function historyCmd() {
+    return new Command("history")
+        .description("List recent transactions for your wallet")
+        .option("-c, --chain <id|name>", "Chain ID or name (omit for all supported chains)")
+        .option("-n, --limit <number>", "Max transactions to show per chain", "20")
+        .action(async function (opts) {
+        setJsonMode(this.parent?.opts().json ?? false);
+        const limit = Math.min(parseInt(opts.limit ?? "20", 10) || 20, 100);
+        const resolvedChain = opts.chain !== undefined ? resolveChainId(opts.chain) : null;
+        const chainsToQuery = opts.chain !== undefined
+            ? resolvedChain !== null
+                ? [resolvedChain]
+                : []
+            : [...SUPPORTED_CHAIN_IDS];
+        if (opts.chain !== undefined && chainsToQuery.length === 0) {
+            exitWithError(`Unknown chain "${opts.chain}". Use one of: ${getChainOptionsHint()}.${usageHint("history")}`, "INVALID_CHAIN");
+        }
+        const address = getAddress();
+        const results = await Promise.allSettled(chainsToQuery.map((chainId) => getTransfers(chainId, address, { limit })));
+        const all = results.map((r, i) => {
+            const chainId = chainsToQuery[i];
+            const chainName = CHAIN_NAMES[chainId] ?? String(chainId);
+            if (r.status === "fulfilled") {
+                return { chainId, chainName, transactions: r.value.transfers };
+            }
+            if (!isJsonMode())
+                out(`Warning: ${chainId} (${chainName}): ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
+            return { chainId, chainName, transactions: [] };
+        });
+        if (isJsonMode()) {
+            out({ address, chains: all });
+            return;
+        }
+        const explorerUrls = EXPLORER_URLS;
+        const addressLower = address.toLowerCase();
+        for (const { chainId, chainName, transactions } of all) {
+            out(`${chainName} (${chainId}) — ${transactions.length} tx(s)`);
+            for (const tx of transactions.slice(0, limit)) {
+                const direction = tx.to?.toLowerCase() === addressLower ? "↑ in " : "↓ out";
+                const symbol = tx.symbol || (tx.category === "external" || tx.category === "internal" ? "ETH" : tx.category?.toUpperCase() ?? "—");
+                const value = formatValue(tx.value, tx.category);
+                const time = formatTimeStamp(tx.timeStamp);
+                const link = explorerUrls[chainId] ? `${explorerUrls[chainId]}/tx/${tx.hash}` : tx.hash;
+                out(`  ${direction} ${value} ${symbol}  ${tx.hash.slice(0, 10)}…  ${time}`);
+                out(`    ${link}`);
+            }
+            out("");
+        }
+    });
+}

package/dist/commands/pending.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function pendingCmd(): Command;