@lightspeed-cli/speed-cli 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# speed-cli
+
+CLI for Speed Token: swap (0x), bridge (Squid), balance, price, volume, DCA, gas, XP. Config and secrets in `~/.speed`.
+
+## Install (use the `speed` command)
+
+**Global install (recommended):**
+```bash
+npm install -g @lightspeed-cli/speed-cli
+speed whoami
+speed balance --json
+```
+
+**Or run without installing:**
+```bash
+npx @lightspeed-cli/speed-cli whoami
+npx @lightspeed-cli/speed-cli balance --json
+```
+
+**First-time setup:** Run `speed setup` to configure `~/.speed/.env` (private key, 0x API key, etc.). See `.env.example` for required vars.
+
+## Publish this package to npm
+
+1. **Log in to npm** (one-time):
+   ```bash
+   npm login
+   ```
+   Use your npm account; create one at [npmjs.com](https://www.npmjs.com/signup) if needed.
+
+2. **Build and publish** (scoped packages require `--access public`):
+   ```bash
+   npm run build
+   npm publish --access public
+   ```
+
+3. **After publishing**, anyone can install and use the `speed` command:
+   ```bash
+   npm install -g @lightspeed-cli/speed-cli
+   speed --help
+   ```
+
+## Develop locally
+
+```bash
+npm install
+npm run build
+node dist/cli.js --help
+# or link globally to test the "speed" command:
+npm link
+speed whoami
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { loadEnv } from "./env.js";
+loadEnv();
+import { Command } from "commander";
+import { whoamiCmd } from "./commands/whoami.js";
+import { balanceCmd } from "./commands/balance.js";
+import { quoteCmd } from "./commands/quote.js";
+import { swapCmd } from "./commands/swap.js";
+import { volumeCmd } from "./commands/volume.js";
+import { dcaCmd } from "./commands/dca.js";
+import { revokeCmd } from "./commands/revoke.js";
+import { bridgeCmd } from "./commands/bridge.js";
+import { statusCmd } from "./commands/status.js";
+import { estimateCmd } from "./commands/estimate.js";
+import { priceCmd } from "./commands/price.js";
+import { doctorCmd } from "./commands/doctor.js";
+import { configCmd } from "./commands/config.js";
+import { sendCmd } from "./commands/send.js";
+import { allowanceCmd } from "./commands/allowance.js";
+import { approveCmd } from "./commands/approve.js";
+import { gasCmd } from "./commands/gas.js";
+import { historyCmd } from "./commands/history.js";
+import { pendingCmd } from "./commands/pending.js";
+import { setupCmd } from "./commands/setup.js";
+import { xpCmd } from "./commands/xp.js";
+const program = new Command();
+program
+    .name("speed")
+    .description("Speed Token CLI: swap, bridge, balance, price, volume, dca, gas, history, xp, and more. Default token is Speed.")
+    .version("0.1.0")
+    .option("-y, --yes", "Skip confirmation for swap/bridge (safe for scripts)")
+    .option("--json", "Output machine-readable JSON to stdout (for scripts and OpenClaw)");
+program.addCommand(whoamiCmd());
+program.addCommand(setupCmd());
+program.addCommand(doctorCmd());
+program.addCommand(balanceCmd());
+program.addCommand(quoteCmd());
+program.addCommand(swapCmd());
+program.addCommand(volumeCmd());
+program.addCommand(dcaCmd());
+program.addCommand(revokeCmd());
+program.addCommand(bridgeCmd());
+program.addCommand(statusCmd());
+program.addCommand(estimateCmd());
+program.addCommand(priceCmd());
+program.addCommand(sendCmd());
+program.addCommand(allowanceCmd());
+program.addCommand(approveCmd());
+program.addCommand(gasCmd());
+program.addCommand(historyCmd());
+program.addCommand(pendingCmd());
+program.addCommand(xpCmd());
+program.addCommand(configCmd());
+program.parse();

package/dist/commands/allowance.d.ts

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

package/dist/commands/allowance.js

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import { ethers } from "ethers";
+import { getSigner } from "../wallet.js";
+import { resolveChainId, getChainOptionsHint } from "../constants.js";
+import { getDefaultChainInput } from "./config.js";
+import { out, exitWithError, setJsonMode, isJsonMode, usageHint } from "../output.js";
+const ERC20_ABI = ["function allowance(address owner, address spender) view returns (uint256)"];
+export function allowanceCmd() {
+    return new Command("allowance")
+        .description("Check current allowance for a spender (0x AllowanceHolder or Squid)")
+        .option("-c, --chain <id|name>", "Chain ID or name", "8453")
+        .requiredOption("--token <address>", "Token contract address")
+        .requiredOption("--spender <address>", "Spender address")
+        .action(async function (opts) {
+        setJsonMode(this.parent?.opts().json ?? false);
+        const chainId = resolveChainId(opts.chain ?? getDefaultChainInput());
+        if (chainId === null) {
+            exitWithError(`Unknown or unsupported chain: ${opts.chain}. Use: ${getChainOptionsHint()}`, "INVALID_CHAIN");
+        }
+        try {
+            const signer = getSigner(chainId);
+            const owner = await signer.getAddress();
+            const token = new ethers.Contract(opts.token.trim(), ERC20_ABI, signer.provider);
+            const raw = await token.allowance(owner, opts.spender.trim());
+            if (isJsonMode()) {
+                out({ allowance: raw.toString(), owner, spender: opts.spender, token: opts.token });
+            }
+            else {
+                out(`Allowance: ${raw.toString()}`);
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            exitWithError(`${msg}.${usageHint("allowance")}`, "ALLOWANCE_ERROR");
+        }
+    });
+}

package/dist/commands/approve.d.ts

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

package/dist/commands/approve.js

@@ -0,0 +1,41 @@
+import { Command } from "commander";
+import { ethers } from "ethers";
+import { getSigner } from "../wallet.js";
+import { parseTokenAmountToWei } from "../lib/parse-amount.js";
+import { resolveChainId, getChainOptionsHint } from "../constants.js";
+import { getDefaultChainInput } from "./config.js";
+import { out, exitWithError, setJsonMode, isJsonMode, success, usageHint } from "../output.js";
+const ERC20_ABI = ["function approve(address spender, uint256 amount) returns (bool)"];
+export function approveCmd() {
+    return new Command("approve")
+        .description("Manually set allowance for a spender (for scripting)")
+        .option("-c, --chain <id|name>", "Chain ID or name", "8453")
+        .requiredOption("--token <address>", "Token contract address")
+        .requiredOption("--spender <address>", "Spender address")
+        .requiredOption("-a, --amount <amount|max>", "Amount in token units or 'max' for unlimited")
+        .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()}. Example: speed approve -c base --token <addr> --spender <addr> -a <amount|max>`, "INVALID_CHAIN");
+        }
+        const amountRaw = opts.amount.trim();
+        const amount = amountRaw.toLowerCase() === "max" ? ethers.MaxUint256 : BigInt(parseTokenAmountToWei(amountRaw));
+        try {
+            const signer = getSigner(chainId);
+            const token = new ethers.Contract(opts.token.trim(), ERC20_ABI, signer);
+            const tx = await token.approve(opts.spender.trim(), amount);
+            await tx.wait();
+            if (isJsonMode()) {
+                out({ txHash: tx.hash, token: opts.token, spender: opts.spender });
+            }
+            else {
+                success(`Approved. Tx: ${tx.hash}`);
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            exitWithError(`${msg}.${usageHint("approve")}`, "APPROVE_ERROR");
+        }
+    });
+}

package/dist/commands/balance.d.ts

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

package/dist/commands/balance.js

@@ -0,0 +1,100 @@
+import { Command } from "commander";
+import { ethers } from "ethers";
+import { getAddress } from "../wallet.js";
+import { getRpcUrl } from "../rpc.js";
+import { SPEED_TOKEN_ADDRESS, SUPPORTED_CHAIN_IDS, NATIVE_SYMBOL, CHAIN_NAMES, resolveChainId, getChainOptionsHint, } from "../constants.js";
+import { out, exitWithError, setJsonMode, isJsonMode, usageHint } from "../output.js";
+import chalk from "chalk";
+const ERC20_ABI = [
+    "function balanceOf(address owner) view returns (uint256)",
+    "function decimals() view returns (uint8)",
+    "function symbol() view returns (string)",
+];
+async function getBalancesForChain(chainId, address, extraTokenAddresses) {
+    const provider = new ethers.JsonRpcProvider(getRpcUrl(chainId));
+    const nativeSymbol = NATIVE_SYMBOL[chainId] ?? "ETH";
+    const speed = new ethers.Contract(SPEED_TOKEN_ADDRESS, ERC20_ABI, provider);
+    const [nativeBal, speedDecimals, speedSymbol, speedBal] = await Promise.all([
+        provider.getBalance(address),
+        speed.decimals(),
+        speed.symbol().catch(() => "SPEED"),
+        speed.balanceOf(address),
+    ]);
+    const tokens = [
+        {
+            address: SPEED_TOKEN_ADDRESS,
+            symbol: speedSymbol,
+            balance: ethers.formatUnits(speedBal, speedDecimals),
+            decimals: speedDecimals,
+        },
+    ];
+    const extraAddrs = extraTokenAddresses
+        .map((a) => a.trim())
+        .filter((a) => a && a.toLowerCase() !== SPEED_TOKEN_ADDRESS.toLowerCase());
+    const extraResults = await Promise.allSettled(extraAddrs.map(async (a) => {
+        const token = new ethers.Contract(a, ERC20_ABI, provider);
+        const [dec, sym, bal] = await Promise.all([
+            token.decimals(),
+            token.symbol().catch(() => "???"),
+            token.balanceOf(address),
+        ]);
+        return { address: a, symbol: sym, balance: ethers.formatUnits(bal, dec), decimals: dec };
+    }));
+    for (let i = 0; i < extraResults.length; i++) {
+        const result = extraResults[i];
+        if (result.status === "fulfilled")
+            tokens.push(result.value);
+        else
+            tokens.push({ address: extraAddrs[i], symbol: "???", balance: "0", decimals: 18 });
+    }
+    return {
+        chainId,
+        nativeSymbol,
+        nativeBalance: ethers.formatEther(nativeBal),
+        tokens,
+    };
+}
+export function balanceCmd() {
+    return new Command("balance")
+        .description("Show Speed + native token + optional other tokens. No --chain = all chains; --chain = that chain only.")
+        .option("-c, --chain <id|name>", "Chain ID or name (e.g. 8453, base). Omit to show all chains.")
+        .option("-t, --token <address>", "Extra token address (can be repeated)", (v, prev) => [...(prev ?? []), v], [])
+        .action(async function (opts) {
+        setJsonMode(this.parent?.opts().json ?? false);
+        const extraTokens = Array.isArray(opts.token) ? opts.token : opts.token ? [opts.token] : [];
+        let chainsToQuery = [...SUPPORTED_CHAIN_IDS];
+        if (opts.chain !== undefined) {
+            const resolved = resolveChainId(opts.chain);
+            if (resolved === null) {
+                exitWithError(`Unknown chain "${opts.chain}". Use one of: ${getChainOptionsHint()}.${usageHint("balance")}`, "INVALID_CHAIN");
+            }
+            chainsToQuery = [resolved];
+        }
+        try {
+            const address = getAddress();
+            const results = await Promise.all(chainsToQuery.map((chainId) => getBalancesForChain(chainId, address, extraTokens)));
+            if (isJsonMode()) {
+                out({ address, chains: results });
+                return;
+            }
+            const chainCol = 14;
+            const numCol = 14;
+            out(chalk.bold("Chain".padEnd(chainCol) + "Native".padEnd(numCol) + "Speed".padEnd(numCol) + "Tokens"));
+            out("-".repeat(chainCol + numCol * 2 + 8));
+            for (const chain of results) {
+                const name = (CHAIN_NAMES[chain.chainId] ?? String(chain.chainId)).padEnd(chainCol);
+                const native = `${chain.nativeBalance} ${chain.nativeSymbol}`.padEnd(numCol);
+                const speed = (chain.tokens.find((t) => t.address.toLowerCase() === SPEED_TOKEN_ADDRESS.toLowerCase())?.balance ?? "0").padEnd(numCol);
+                const others = chain.tokens
+                    .filter((t) => t.address.toLowerCase() !== SPEED_TOKEN_ADDRESS.toLowerCase())
+                    .map((t) => `${t.symbol}: ${t.balance}`)
+                    .join(", ");
+                out(name + native + speed + (others || "—"));
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            exitWithError(`${msg}.${usageHint("balance")}`, "BALANCE_ERROR");
+        }
+    });
+}

package/dist/commands/bridge.d.ts

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

package/dist/commands/bridge.js

@@ -0,0 +1,142 @@
+import { Command } from "commander";
+import { createInterface } from "readline";
+import ora from "ora";
+import { getSigner } from "../wallet.js";
+import { getSquid } from "../lib/squid.js";
+import { getEthUsdPriceNumber } from "../lib/oracle.js";
+import { ethers } from "ethers";
+import { EXPLORER_URLS, SPEED_TOKEN_ADDRESS, resolveChainId, getChainOptionsHint } from "../constants.js";
+import { getDefaultChainInput } from "./config.js";
+import { out, exitWithError, setJsonMode, isJsonMode, success, usageHint } from "../output.js";
+import { addPendingBridge } from "../lib/pending-bridges.js";
+import { getSpeedUsdPriceNumber } from "../lib/oracle.js";
+import { recordXpAction } from "../lib/xp.js";
+import { parseTokenAmountToWei } from "../lib/parse-amount.js";
+const ERC20_ABI = ["function approve(address spender, uint256 amount) returns (bool)"];
+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 bridgeCmd() {
+    return new Command("bridge")
+        .description("Bridge Speed to Ethereum, Base, OP, Arbitrum, BNB, or Polygon via Squid. Chain can be ID (e.g. 8453) or name (e.g. base, ethereum).")
+        .option("--from-chain <id|name>", "Source chain (ID or name, e.g. base or 8453)", "8453")
+        .option("--to-chain <id|name>", "Destination chain (ID or name, e.g. ethereum or 1)")
+        .option("-a, --amount <amount>", "Amount of SPEED to bridge (e.g. 0.1, 1000)")
+        .option("--to-token <address>", "Destination token (default: Speed on to-chain)")
+        .action(async function (opts) {
+        setJsonMode(this.parent?.opts().json ?? false);
+        const yes = this.parent?.opts().yes ?? false;
+        const fromChainId = resolveChainId(opts.fromChain ?? getDefaultChainInput());
+        const toChainId = opts.toChain ? resolveChainId(opts.toChain) : null;
+        if (fromChainId === null) {
+            exitWithError(`Unknown from-chain "${opts.fromChain}" (use chain ID or name). Use one of: ${getChainOptionsHint()}.${usageHint("bridge")}`, "INVALID_CHAIN");
+        }
+        if (toChainId === null) {
+            exitWithError(`--to-chain is required (chain ID or name). Use one of: ${getChainOptionsHint()}. Example: speed bridge --from-chain base --to-chain ethereum -a 1000`, "INVALID_CHAIN");
+        }
+        if (!opts.amount?.trim()) {
+            exitWithError("--amount is required. Example: speed bridge --from-chain base --to-chain ethereum -a 1000", "MISSING_ARGS");
+        }
+        const amount = parseTokenAmountToWei(opts.amount.trim());
+        const toToken = opts.toToken?.trim() ?? SPEED_TOKEN_ADDRESS;
+        try {
+            const signer = getSigner(fromChainId);
+            const fromAddress = await signer.getAddress();
+            const spinner = isJsonMode() ? null : ora("Initializing Squid...").start();
+            const squid = await getSquid();
+            if (spinner)
+                spinner.text = "Fetching route...";
+            const { route, requestId } = await squid.getRoute({
+                fromAddress,
+                fromChain: String(fromChainId),
+                fromToken: SPEED_TOKEN_ADDRESS,
+                fromAmount: amount,
+                toChain: String(toChainId),
+                toToken,
+                toAddress: fromAddress,
+            });
+            if (spinner)
+                spinner.succeed("Route received");
+            let gasEth = "0";
+            let gasUsd = "0";
+            try {
+                const ethUsd = await getEthUsdPriceNumber(fromChainId);
+                const feeData = await signer.provider.getFeeData();
+                const gasLimit = 300000n;
+                const gasPrice = feeData.gasPrice ?? 0n;
+                gasEth = ethers.formatEther(gasLimit * gasPrice);
+                gasUsd = (parseFloat(gasEth) * ethUsd).toFixed(2);
+            }
+            catch (_) { }
+            if (!yes && !isJsonMode()) {
+                const amountHuman = parseFloat(ethers.formatEther(amount)).toLocaleString(undefined, { maximumFractionDigits: 6 });
+                out(`Bridge ${amountHuman} SPEED from chain ${fromChainId} to chain ${toChainId}`);
+                out(`Estimated gas: ${gasEth} ETH (~$${gasUsd})`);
+                const ok = await askConfirm("Proceed? [y/N] ");
+                if (!ok) {
+                    out("Aborted.");
+                    process.exit(0);
+                }
+            }
+            const txRequest = route.transactionRequest;
+            const target = txRequest?.target;
+            if (target) {
+                const approveSpinner = isJsonMode() ? null : ora("Approving...").start();
+                const token = new ethers.Contract(SPEED_TOKEN_ADDRESS, ERC20_ABI, signer);
+                const txApprove = await token.approve(target, amount);
+                await txApprove.wait();
+                if (approveSpinner)
+                    approveSpinner.succeed("Approved");
+            }
+            const execSpinner = isJsonMode() ? null : ora("Executing bridge...").start();
+            const txResponse = await squid.executeRoute({ signer: signer, route });
+            const txHash = typeof txResponse === "object" && txResponse !== null && "hash" in txResponse
+                ? txResponse.hash
+                : txResponse?.transactionHash ?? "unknown";
+            if (txResponse && typeof txResponse === "object" && "wait" in txResponse && typeof txResponse.wait === "function") {
+                await txResponse.wait();
+            }
+            if (execSpinner)
+                execSpinner.succeed("Bridge tx sent");
+            const quoteId = route?.params?.quoteId ??
+                route?.quoteId ??
+                "";
+            addPendingBridge({
+                requestId,
+                quoteId,
+                txHash,
+                fromChain: fromChainId,
+                toChain: toChainId,
+                startedAt: new Date().toISOString(),
+            });
+            try {
+                const amountNum = parseFloat(ethers.formatEther(amount));
+                const speedUsd = await getSpeedUsdPriceNumber(fromChainId);
+                recordXpAction("bridge", amountNum * speedUsd);
+            }
+            catch (_) { }
+            const explorer = EXPLORER_URLS[fromChainId];
+            const link = explorer ? `${explorer}/tx/${txHash}` : txHash;
+            const axelarScan = `https://axelarscan.io/gmp/${txHash}`;
+            if (isJsonMode()) {
+                out({ txHash, explorerLink: link, axelarScan, requestId });
+            }
+            else {
+                success(`Tx: ${txHash}`);
+                if (explorer)
+                    out(link);
+                out(`Bridge status: ${axelarScan}`);
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            exitWithError(`${msg}.${usageHint("bridge")}`, "BRIDGE_ERROR");
+        }
+    });
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+interface Config {
+    defaultChain?: number;
+    defaultSlippage?: number;
+    outputFormat?: "human" | "json";
+}
+export declare function configCmd(): Command;
+export declare function getConfig(): Config;
+/** Default chain when user omits -c/--chain (from config or 8453). */
+export declare function getDefaultChainInput(): string;
+export {};

package/dist/commands/config.js

@@ -0,0 +1,83 @@
+import { Command } from "commander";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { out, exitWithError, setJsonMode, isJsonMode } from "../output.js";
+import { getSpeedConfigDir } from "../env.js";
+const CONFIG_PATH = join(getSpeedConfigDir(), "config.json");
+function loadConfig() {
+    try {
+        if (existsSync(CONFIG_PATH)) {
+            const raw = readFileSync(CONFIG_PATH, "utf-8");
+            return JSON.parse(raw);
+        }
+    }
+    catch (_) { }
+    return {};
+}
+function saveConfig(config) {
+    mkdirSync(getSpeedConfigDir(), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+export function configCmd() {
+    const cmd = new Command("config")
+        .description("Read/write preferences in ~/.speed/config.json (no secrets)");
+    cmd
+        .command("set <key> <value>")
+        .description("Set default-chain, default-slippage, or output-format")
+        .action(function (key, value) {
+        setJsonMode(this.parent?.parent?.opts().json ?? false);
+        const config = loadConfig();
+        if (key === "default-chain") {
+            config.defaultChain = parseInt(value, 10);
+        }
+        else if (key === "default-slippage") {
+            config.defaultSlippage = parseFloat(value);
+        }
+        else if (key === "output-format") {
+            if (value !== "human" && value !== "json") {
+                exitWithError("output-format must be 'human' or 'json'. Example: speed config set output-format json", "INVALID_VALUE");
+            }
+            config.outputFormat = value;
+        }
+        else {
+            exitWithError(`Unknown key: ${key}. Valid keys: default-chain, default-slippage, output-format. Example: speed config set default-chain 8453`, "INVALID_KEY");
+        }
+        saveConfig(config);
+        if (!isJsonMode())
+            out(`Set ${key} = ${value}`);
+        else
+            out({ [key]: value });
+    });
+    cmd
+        .command("get [key]")
+        .description("Get one key or all config")
+        .action(function (key) {
+        setJsonMode(this.parent?.parent?.opts().json ?? false);
+        const config = loadConfig();
+        if (key) {
+            const v = key === "default-chain" ? config.defaultChain : key === "default-slippage" ? config.defaultSlippage : key === "output-format" ? config.outputFormat : undefined;
+            if (v === undefined)
+                exitWithError(`Unknown key: ${key}. Valid keys: default-chain, default-slippage, output-format. Example: speed config get default-chain`, "INVALID_KEY");
+            if (isJsonMode())
+                out({ [key]: v });
+            else
+                out(String(v));
+        }
+        else {
+            if (isJsonMode())
+                out(config);
+            else
+                for (const [k, v] of Object.entries(config))
+                    out(`${k}: ${v}`);
+        }
+    });
+    return cmd;
+}
+export function getConfig() {
+    return loadConfig();
+}
+/** Default chain when user omits -c/--chain (from config or 8453). */
+export function getDefaultChainInput() {
+    const c = loadConfig().defaultChain;
+    return c != null ? String(c) : "8453";
+}

package/dist/commands/dca.d.ts

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