@lightspeed-cli/speed-cli 0.1.2 → 0.1.4

package/.env.example

@@ -0,0 +1,11 @@
+# Required: wallet (hex, with or without 0x prefix)
+PRIVATE_KEY=
+
+# 0x Swap API (https://dashboard.0x.org/)
+0X_API_KEY=
+
+# Squid Router (https://docs.squidrouter.com)
+SQUID_INTEGRATOR_ID=
+
+# RPC + history (https://dashboard.alchemy.com/)
+ALCHEMY_API_KEY=

package/README.md

@@ -17,27 +17,16 @@ 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.
+**First-time setup:** Run `speed setup` to configure `~/.speed/.env`. You’ll need:
 
-## Publish this package to npm
+| What | Used for | Get it |
+|------|----------|--------|
+| **Alchemy API key** | RPC (Ethereum, Base, OP, Arbitrum, Polygon, BNB) | [alchemy.com](https://www.alchemy.com/) → Create app, copy API key |
+| **0x API key** | Swaps (quote + execute) | [0x.org](https://0x.org/) → Dashboard, create app, API key |
+| **Squid integrator ID** | Bridging across chains | [Squid integrator form](https://squidrouter.typeform.com/integrator-id) |
 
-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.
+See `.env.example` for variable names, or run `speed setup --help`.
 
-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
 
@@ -49,3 +38,4 @@ node dist/cli.js --help
 npm link
 speed whoami
 ```
+**Shell note:** Examples use `||` for "or" (Bash). On PowerShell use `;` instead of `||` to chain commands.

package/dist/cli.js

@@ -28,7 +28,7 @@ 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.2")
+    .version("0.1.4")
     .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());

package/dist/commands/balance.js

@@ -25,7 +25,7 @@ async function getBalancesForChain(chainId, address, extraTokenAddresses) {
             address: SPEED_TOKEN_ADDRESS,
             symbol: speedSymbol,
             balance: ethers.formatUnits(speedBal, speedDecimals),
-            decimals: speedDecimals,
+            decimals: Number(speedDecimals),
         },
     ];
     const extraAddrs = extraTokenAddresses
@@ -38,7 +38,7 @@ async function getBalancesForChain(chainId, address, extraTokenAddresses) {
             token.symbol().catch(() => "???"),
             token.balanceOf(address),
         ]);
-        return { address: a, symbol: sym, balance: ethers.formatUnits(bal, dec), decimals: dec };
+        return { address: a, symbol: sym, balance: ethers.formatUnits(bal, dec), decimals: Number(dec) };
     }));
     for (let i = 0; i < extraResults.length; i++) {
         const result = extraResults[i];

package/dist/commands/bridge.js

@@ -136,6 +136,9 @@ export function bridgeCmd() {
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes("429")) {
+                exitWithError(`Squid API rate limit. Wait a minute and try again, or bridge one chain at a time.${usageHint("bridge")}`, "BRIDGE_ERROR");
+            }
             exitWithError(`${msg}.${usageHint("bridge")}`, "BRIDGE_ERROR");
         }
     });

package/dist/commands/config.js

@@ -55,13 +55,15 @@ export function configCmd() {
         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)
+            const validKeys = ["default-chain", "default-slippage", "output-format"];
+            if (!validKeys.includes(key)) {
                 exitWithError(`Unknown key: ${key}. Valid keys: default-chain, default-slippage, output-format. Example: speed config get default-chain`, "INVALID_KEY");
+            }
+            const v = key === "default-chain" ? config.defaultChain : key === "default-slippage" ? config.defaultSlippage : config.outputFormat;
             if (isJsonMode())
-                out({ [key]: v });
+                out({ [key]: v ?? null });
             else
-                out(String(v));
+                out(v !== undefined && v !== null ? String(v) : "(not set)");
         }
         else {
             if (isJsonMode())

package/dist/commands/estimate.js

@@ -4,7 +4,7 @@ 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 { resolveChainId, getChainOptionsHint, SPEED_TOKEN_ADDRESS, NATIVE_ETH_0X } from "../constants.js";
 import { getDefaultChainInput } from "./config.js";
 import { out, exitWithError, setJsonMode, isJsonMode, usageHint } from "../output.js";
 export function estimateCmd() {
@@ -30,9 +30,23 @@ export function estimateCmd() {
                 gasLimit = 350000n;
             }
             else if (opts.buy && opts.amount) {
-                const sellToken = opts.sell?.trim() ?? "0xB01CF1bE9568f09449382a47Cd5bF58e2A9D5922";
+                const toToken = (v, d) => {
+                    if (!v)
+                        return d;
+                    const t = v.trim().toLowerCase();
+                    if (t === "speed")
+                        return SPEED_TOKEN_ADDRESS;
+                    if (t === "eth" || t === "ether" || t === "native")
+                        return NATIVE_ETH_0X;
+                    return v.trim();
+                };
+                const sellToken = toToken(opts.sell, NATIVE_ETH_0X);
+                const buyToken = toToken(opts.buy, SPEED_TOKEN_ADDRESS);
+                if (sellToken.toLowerCase() === buyToken.toLowerCase()) {
+                    exitWithError("Sell and buy tokens must be different. To buy Speed with ETH use --sell eth.", "SAME_TOKEN");
+                }
                 const amountWei = parseTokenAmountToWei(opts.amount.trim());
-                const quote = await get0xQuote(chainId, sellToken, opts.buy.trim(), amountWei, taker);
+                const quote = await get0xQuote(chainId, sellToken, buyToken, amountWei, taker);
                 if (quote.gas)
                     gasLimit = BigInt(quote.gas);
             }
@@ -41,7 +55,8 @@ export function estimateCmd() {
             const gasWei = gasLimit * gasPrice;
             const gasEth = ethers.formatEther(gasWei);
             const ethUsd = await getEthUsdPriceNumber(chainId);
-            const gasUsd = (parseFloat(gasEth) * ethUsd).toFixed(2);
+            const gasUsdNum = parseFloat(gasEth) * ethUsd;
+            const gasUsd = gasUsdNum > 0 && gasUsdNum < 0.01 ? gasUsdNum.toFixed(4) : gasUsdNum.toFixed(2);
             if (isJsonMode()) {
                 out({ gasEth, gasUsd, gasLimit: gasLimit.toString(), gasPrice: gasPrice.toString() });
             }

package/dist/commands/gas.js

@@ -122,6 +122,9 @@ export function gasCmd() {
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes("OVERFLOW") || msg.includes("overflow")) {
+                exitWithError(`Amount may be too large for this route (aggregator overflow). Try a smaller amount (e.g. 100 or 300).${usageHint("gas")}`, "GAS_ERROR");
+            }
             exitWithError(`${msg}.${usageHint("gas")}`, "GAS_ERROR");
         }
     });

package/dist/commands/quote.js

@@ -3,15 +3,25 @@ import ora from "ora";
 import { getAddress } from "../wallet.js";
 import { get0xQuote } from "../lib/zerox.js";
 import { parseTokenAmountToWei } from "../lib/parse-amount.js";
-import { resolveChainId, getChainOptionsHint } from "../constants.js";
+import { resolveChainId, getChainOptionsHint, SPEED_TOKEN_ADDRESS, NATIVE_ETH_0X } from "../constants.js";
 import { getDefaultChainInput } from "./config.js";
 import { out, exitWithError, setJsonMode, isJsonMode, usageHint } from "../output.js";
+function toToken(v, defaultVal) {
+    if (!v)
+        return defaultVal;
+    const t = v.trim().toLowerCase();
+    if (t === "speed")
+        return SPEED_TOKEN_ADDRESS;
+    if (t === "eth" || t === "ether" || t === "native")
+        return NATIVE_ETH_0X;
+    return v.trim();
+}
 export function quoteCmd() {
     return new Command("quote")
         .description("Preview swap (no tx). To execute, use: speed swap --buy <addr> -a <amount> (approve is automatic)")
         .option("-c, --chain <id|name>", "Chain ID or name", "8453")
-        .option("--sell <address>", "Sell token address (default: Speed)")
-        .option("--buy <address>", "Buy token address")
+        .option("--sell <address>", "Sell token: address or 'speed'|'eth'|'native' (default: native ETH). To buy Speed with ETH use --sell eth.")
+        .option("--buy <address>", "Buy token: address or 'speed'")
         .option("-a, --amount <amount>", "Sell amount in token units (e.g. 0.002, 10000)")
         .action(async function (opts) {
         setJsonMode(this.parent?.opts().json ?? false);
@@ -22,8 +32,11 @@ export function quoteCmd() {
         if (!opts.buy || !opts.amount) {
             exitWithError("--buy and --amount are required", "MISSING_ARGS");
         }
-        const sellToken = opts.sell?.trim() ?? "0xB01CF1bE9568f09449382a47Cd5bF58e2A9D5922";
-        const buyToken = opts.buy.trim();
+        const sellToken = toToken(opts.sell, NATIVE_ETH_0X);
+        const buyToken = toToken(opts.buy, SPEED_TOKEN_ADDRESS);
+        if (sellToken.toLowerCase() === buyToken.toLowerCase()) {
+            exitWithError(`Sell and buy tokens must be different. To buy Speed with ETH use --sell eth (or --sell ${NATIVE_ETH_0X}).${usageHint("quote")}`, "SAME_TOKEN");
+        }
         const amount = parseTokenAmountToWei(opts.amount.trim());
         try {
             const spinner = isJsonMode() ? null : ora("Fetching quote...").start();

package/dist/commands/swap.js

@@ -45,10 +45,10 @@ export function swapCmd() {
     return new Command("swap")
         .description("One-shot swap: get quote → confirm → approve (if needed) → execute. No need to run quote or approve separately.")
         .option("-c, --chain <id|name>", "Chain ID or name (e.g. 8453, base)", "8453")
-        .option("--sell <address>", "Sell token (default: Speed)")
-        .option("--buy <address>", "Buy token (default: Speed)")
+        .option("--sell <address>", "Sell token: address, or 'speed'|'eth'|'native' (default: native ETH). To buy Speed with ETH use default or --sell eth.")
+        .option("--buy <address>", "Buy token: address or 'speed' (default: Speed)")
         .option("-a, --amount <amount>", "Sell amount in token units (e.g. 0.002, 10000, or 0.002 eth / 100 speed)")
-        .option("--go", "Skip confirmation and execute swap")
+        .option("--go", "Skip confirmation (alias for -y/--yes for swap)")
         .option("--dry-run", "Only fetch and print quote; no approval or swap tx")
         .action(async function (opts) {
         setJsonMode(this.parent?.opts().json ?? false);
@@ -74,7 +74,7 @@ export function swapCmd() {
         const sellToken = toToken(opts.sell, NATIVE_ETH_0X);
         const buyToken = toToken(opts.buy, SPEED_TOKEN_ADDRESS);
         if (sellToken.toLowerCase() === buyToken.toLowerCase()) {
-            exitWithError("Sell and buy token must be different. Use --sell and/or --buy to specify.", "SAME_TOKEN");
+            exitWithError(`Sell and buy tokens must be different. To buy Speed with ETH use default or --sell eth (or --sell ${NATIVE_ETH_0X}).${usageHint("swap")}`, "SAME_TOKEN");
         }
         const amount = parseTokenAmountToWei(opts.amount.trim());
         try {

package/dist/commands/volume.js

@@ -6,7 +6,7 @@ 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 { resolveChainId, getChainOptionsHint, resolveTokenAddress, NATIVE_ETH_0X, EXPLORER_URLS, CHAIN_NAMES, } from "../constants.js";
 import { getDefaultChainInput } from "./config.js";
 import { out, exitWithError, setJsonMode, isJsonMode, success, usageHint } from "../output.js";
 const ERC20_BALANCE_ABI = ["function balanceOf(address owner) view returns (uint256)"];
@@ -36,6 +36,15 @@ function jitteredDelaySeconds(centerSec, jitterFraction) {
 function sleepMs(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/** Turn RPC "insufficient funds" into a short, actionable message. */
+function formatInsufficientFundsMessage(chainId, rawMessage) {
+    const chainName = CHAIN_NAMES[chainId] ?? String(chainId);
+    const haveMatch = rawMessage.match(/have\s+(\d+)/);
+    const wantMatch = rawMessage.match(/want\s+(\d+)/);
+    const haveEth = haveMatch ? ethers.formatEther(haveMatch[1]) : "?";
+    const wantEth = wantMatch ? ethers.formatEther(wantMatch[1]) : "?";
+    return `Insufficient native balance on ${chainName}: have ~${haveEth} ETH, need ~${wantEth} ETH for this op. Run \`speed gas -c ${chainId} -a <amount> -y\` to refuel.`;
+}
 export function volumeCmd() {
     return new Command("volume")
         .description("Human-like volume: interleaved buys and sells (native ETH ↔ token). Default token is Speed; use --token for others.")
@@ -175,6 +184,9 @@ export function volumeCmd() {
                     if (spinner)
                         spinner.fail(`Op ${op}/${ops} sell failed`);
                     const msg = e instanceof Error ? e.message : String(e);
+                    if (msg.toLowerCase().includes("insufficient funds")) {
+                        exitWithError(formatInsufficientFundsMessage(chainId, msg), "INSUFFICIENT_FUNDS");
+                    }
                     failures.push({ op, phase: "sell", error: msg });
                     if (!isJsonMode())
                         out(`  → ${msg.slice(0, 80)}${msg.length > 80 ? "…" : ""}`);
@@ -202,6 +214,9 @@ export function volumeCmd() {
                     if (spinner)
                         spinner.fail(`Op ${op}/${ops} buy failed`);
                     const msg = e instanceof Error ? e.message : String(e);
+                    if (msg.toLowerCase().includes("insufficient funds")) {
+                        exitWithError(formatInsufficientFundsMessage(chainId, msg), "INSUFFICIENT_FUNDS");
+                    }
                     failures.push({ op, phase: "buy", error: msg });
                     if (!isJsonMode())
                         out(`  → ${msg.slice(0, 80)}${msg.length > 80 ? "…" : ""}`);

package/openclaw/skills/speed-token/SKILL.md

@@ -1,189 +1,233 @@
----
-name: speed-token
-description: The Best Full trading and bridging CLI for agents (and humans) via OpenClaw, swap, bridge, balance, price, quote, gas, send, approve, allowance, revoke, history, pending, status, estimate, doctor, whoami, config, volume, dca, xp. Use --json for machine-readable output. Powered by Lightspeed multi-chain.
-permissions:
-  - network:outbound
-triggers:
-  - "speed"
-  - "speed token"
-  - "speed swap"
-  - "speed bridge"
-  - "speed balance"
-  - "speed quote"
-  - "speed price"
-  - "speed gas"
-  - "speed send"
-  - "speed approve"
-  - "speed allowance"
-  - "speed revoke"
-  - "speed history"
-  - "speed pending"
-  - "speed status"
-  - "speed doctor"
-  - "speed whoami"
-  - "speed config"
-  - "speed setup"
-  - "speed estimate"
-  - "speed volume"
-  - "speed dca"
-  - "speed xp"
----
-
-# Speed Token CLI — OpenClaw skill
-
-Use the **speed** CLI via bash. **Always pass `--json`** so output is machine-readable. Use **`-y`** or **`--yes`** to skip confirmation when executing swap/bridge (required for non-interactive use).
-
-**Invocation:** From the project directory run `node dist/cli.js <command> [options] --json`, or if `speed` is on PATH: `speed <command> [options] --json`. From another directory, use the full path to `dist/cli.js` or ensure `speed` is on PATH.
-
-**Chains:** Every `--chain`, `--from-chain`, `--to-chain` accepts **chain ID** (e.g. `8453`) or **name** (e.g. `base`, `ethereum`, `op`, `arb`, `polygon`, `bnb`). Supported: 1 (ethereum), 8453 (base), 10 (optimism), 42161 (arbitrum), 137 (polygon), 56 (bnb).
-
-**Amounts:** Use **token units** (e.g. `-a 0.002`, `-a 1000`), not wei. Commands that take `-a` accept human-readable amounts.
-
-**Speed token (default):** Address `0xB01CF1bE9568f09449382a47Cd5bF58e2A9D5922`. Volume, DCA, and gas default to Speed; use `--token <address|speed>` to use another token.
-
-**Errors in --json mode:** CLI prints `{"error":"...", "code":"..."}` to stdout and exits 1. Parse and surface the `error` string to the user.
-
----
-
-## Global options (before command)
-
-- `--json` — **Always use.** JSON to stdout; errors as `{ error, code }`.
-- `-y, --yes` — Skip confirmation (required for swap, bridge, and gas in non-interactive use).
-
----
-
-## Commands reference
-
-### Identity & setup
-
-- **whoami** — Print wallet address (from PRIVATE_KEY). No args.  
-  `speed whoami --json`  
-  If this fails, user must run `speed setup` (interactive; do not run from bot).
-
-- **setup** — Interactive; writes secrets to `~/.speed/.env`. **Do not invoke from bots.** Direct user to run `speed setup` if whoami or doctor fails.
-
-- **doctor** — Validate env, API keys, RPC, oracles, Speed balance.  
-  `speed doctor --json` or `speed doctor -c base --json`
-
-### Balance & price
-
-- **balance** — Speed + native + optional extra tokens. Omit `-c` for all chains.  
-  `speed balance --json`  
-  `speed balance -c base --json`  
-  `speed balance -c base -t <token-address> --json` (repeat `-t` for multiple)
-
-- **price** — Speed/ETH, Speed/USD, native USD (oracle).  
-  `speed price -c base --json`
-
-### Swap (one-shot: quote → approve if needed → swap)
-
-- **swap** — Single command to execute a swap. Approve is automatic when needed. Use `-y` to skip confirmation.  
-  `speed swap -c base --buy <token-address> -a 0.002 -y --json`  
-  Optional: `--sell <address>` (default Speed).  
-  **Preview only (no tx):** `speed swap --dry-run -c base --buy <addr> -a 0.002 --json`
-
-- **quote** — Preview swap (no transaction).  
-  `speed quote -c base --buy <token-address> -a 0.002 --json`  
-  Optional: `--sell <address>`.
-
-**Do not** tell users to run approve then quote then swap; **swap alone** does it. Use **quote** or **swap --dry-run** only when the user wants a preview.
-
-### Bridge
-
-- **bridge** — Bridge Speed across chains (Squid). Use `-y` to skip confirmation.  
-  `speed bridge --from-chain base --to-chain ethereum -a 100 -y --json`  
-  Optional: `--to-token <address>` (default Speed on destination).
-
-### Volume & DCA (automated buy/sell)
-
-- **volume** — Human-like volume: interleaved buys and sells (ETH ↔ token) with random-walk amounts, jittered delays, optional partial sells. Default token is Speed; use `--token <address|speed>` for another token. Continues on revert; failures are reported in summary.  
-  `speed volume -c base -a 0.001 --ops 20 --delay 2 --delay-jitter 0.5 --sell-frequency 0.2 --json`  
-  Optional: `--token`, `--amount-min`, `--amount-max`, `--amount-drift`, `--sell-partial-chance`, `--dry-run`.
-
-- **dca** — DCA: buy token with ETH on a fixed time interval. Default token is Speed; use `--token <address|speed>` for another token. Runs until `--count` buys or until stopped (Ctrl+C).  
-  `speed dca -c base -a 0.001 --interval 5m --count 10 --json`  
-  Optional: `--token`, `--interval-jitter <fraction>`, `--dry-run`. Omit `--count` to run until stopped.
-
-### Gas (token → native)
-
-- **gas** — Swap token for native (ETH/MATIC/BNB) to fund gas. Default token is Speed; use `--token <address|speed>` for another token. Use `-y` for non-interactive.  
-  `speed gas -c base -a 10000 -y --json`
-
-### Send & allowances
-
-- **send** — Plain ERC-20 transfer of Speed.  
-  `speed send -c base -t <recipient-address> -a 100 -y --json`
-
-- **approve** — Set token allowance for a spender (e.g. for scripting). Amount in token units or `max`.  
-  `speed approve -c base --token <token-address> --spender <spender-address> -a 1000 --json` or `-a max --json`
-
-- **allowance** — Read current allowance.  
-  `speed allowance -c base --token <token-address> --spender <spender-address> --json`
-
-- **revoke** — Set allowance to 0.  
-  `speed revoke -c base --token <token-address> --spender <spender-address> -y --json`
-
-### History & status
-
-- **history** — Recent transfers (Alchemy). Omit `-c` for all chains.  
-  `speed history --json` or `speed history -c base -n 20 --json`
-
-- **pending** — In-flight bridges + pending txs.  
-  `speed pending --json` or `speed pending --no-txs --json` (bridges only)
-
-- **status** — Tx confirmation; for bridge use Squid status.  
-  On-chain: `speed status --tx <tx-hash> -c base --json`  
-  Bridge: `speed status --tx <tx-hash> --request-id <id> --quote-id <id> --json`
-
-### XP (progress for bots)
-
-- **xp** — Show level, streak, and stats (swaps, bridges, volume ops, DCA buys, gas refuels). Bots call this to see how they're doing. Stored in `~/.speed/xp.json`.  
-  `speed xp --json`  
-  Optional: `--no-title` to omit the silly level title.
-
-### Estimate & config
-
-- **estimate** — Gas cost (ETH + USD) for swap or bridge. Amount in token units (same as swap).  
-  Swap: `speed estimate -c base --buy <addr> -a 0.002 --json`  
-  Bridge: `speed estimate -c base --to-chain ethereum --bridge --json`
-
-- **config** — Read/write `~/.speed/config.json` (no secrets).  
-  Set: `speed config set default-chain 8453 --json`  
-  Get: `speed config get --json` or `speed config get default-chain --json`  
-  Keys: `default-chain`, `default-slippage`, `output-format` (human|json).
-
----
-
-## Recommended flows for bots
-
-1. **User wants to swap**  
-   Run: `speed swap -c <chain> --buy <token> -a <amount> -y --json`. If user wants a preview first, run `speed swap --dry-run ... --json` then same without `--dry-run` and without `-y` only if you need to ask for confirmation.
-
-2. **User wants to bridge**  
-   Run: `speed bridge --from-chain <id|name> --to-chain <id|name> -a <amount> -y --json`.
-
-3. **User wants balance**  
-   Run: `speed balance --json` (all chains) or `speed balance -c <chain> --json`.
-
-4. **User wants price**  
-   Run: `speed price -c <chain> --json`.
-
-5. **User wants to fund gas (token → native)**  
-   Run: `speed gas -c <chain> -a <token-amount> -y --json`. Default token is Speed; add `--token <address|speed>` for another token.
-
-6. **User wants volume (automated buys + sells)**  
-   Run: `speed volume -c <chain> -a <eth-per-buy> --ops <n> --delay <sec> --sell-frequency <0..1> --json`. Default token is Speed; add `--token <address|speed>` for another token. Failures do not stop the run; summary includes failed count.
-
-7. **User wants DCA (interval buys only)**  
-   Run: `speed dca -c <chain> -a <eth-per-buy> --interval <sec|5m|1h|1d> --count <n> --json`, or omit `--count` to run until stopped. Default token is Speed; add `--token <address|speed>` for another token.
-
-8. **User wants to see XP / progress**  
-   Run: `speed xp --json`. Returns totalXP, level, title, streak, lastActivity, progress to next level, stats (count + totalUSD per action type), recent history.
-
-9. **User wants gas estimate before swap/bridge**  
-   Run: `speed estimate -c <chain> --buy <addr> -a <token-amount> --json` (swap) or `speed estimate -c <chain> --to-chain <id|name> --bridge --json` (bridge). Use same `-a` as the swap for comparable cost.
-
-10. **Check if CLI is configured**  
-   Run: `speed doctor --json` or `speed whoami --json`. If error, tell user to run `speed setup` in the terminal (interactive).
-
-11. **Parse JSON:** On success, one JSON object per command. On failure, `{ error, code }`; show `error` to the user. Common success shapes: whoami `{ address }`, balance `{ address?, chains }`, swap/bridge/gas/send/approve `{ txHash, explorerLink? }`, quote `{ buyAmountWei?, ... }`, price `{ speedPerEth?, ... }`, xp `{ totalXP, level, streak, ... }`, estimate `{ gasCostEth?, gasCostUsd?, ... }`.
+---
+name: speed-token
+description: The Best Full trading and bridging CLI for agents (and humans) via OpenClaw, swap, bridge, balance, price, quote, gas, send, approve, allowance, revoke, history, pending, status, estimate, doctor, whoami, config, volume, dca, xp. Use --json for machine-readable output. Powered by Lightspeed multi-chain.
+permissions:
+  - network:outbound
+triggers:
+  - "speed"
+  - "speed token"
+  - "speed swap"
+  - "speed bridge"
+  - "speed balance"
+  - "speed quote"
+  - "speed price"
+  - "speed gas"
+  - "speed send"
+  - "speed approve"
+  - "speed allowance"
+  - "speed revoke"
+  - "speed history"
+  - "speed pending"
+  - "speed status"
+  - "speed doctor"
+  - "speed whoami"
+  - "speed config"
+  - "speed setup"
+  - "speed estimate"
+  - "speed volume"
+  - "speed dca"
+  - "speed xp"
+---
+
+# Speed Token CLI — OpenClaw skill
+
+Use the **speed** CLI via bash. **Always pass `--json`** so output is machine-readable. Use **`-y`** or **`--yes`** to skip confirmation when executing swap, bridge, or gas (required for non-interactive use). For swap you can also use **`--go`** as an alias.
+
+**Invocation:** From the project directory run `node dist/cli.js <command> [options] --json` (or put global options first: `node dist/cli.js --json -y <command> [options]`). If `speed` is on PATH: `speed <command> [options] --json`. From another directory, use the full path to `dist/cli.js` or ensure `speed` is on PATH.
+
+**Chains:** Every `--chain`, `--from-chain`, `--to-chain` accepts **chain ID** (e.g. `8453`) or **name** (e.g. `base`, `ethereum`, `op`, `arb`, `polygon`, `bnb`). Supported: 1 (ethereum), 8453 (base), 10 (optimism), 42161 (arbitrum), 137 (polygon), 56 (bnb).
+
+**Amounts:** Use **token units** (e.g. `-a 0.002`, `-a 1000`), not wei. Commands that take `-a` accept human-readable amounts.
+
+**Speed token (default):** Address `0xB01CF1bE9568f09449382a47Cd5bF58e2A9D5922`. Volume, DCA, and gas default to Speed; use `--token <address|speed>` to use another token.
+
+**Errors in --json mode:** CLI prints `{"error":"...", "code":"..."}` to stdout and exits 1. Parse and surface the `error` string to the user. Common codes: `INSUFFICIENT_FUNDS`, `SAME_TOKEN`, `QUOTE_ERROR`, `MISSING_ARGS`, `INVALID_CHAIN`.
+
+**Shell note:** Examples use `||` (Bash). On PowerShell use `;` instead of `||` to chain commands.
+
+**Pitfalls:** (1) Volume/DCA need enough native balance (~0.001+ ETH per buy); otherwise INSUFFICIENT_FUNDS. (2) Very small DCA/swap amounts can revert (slippage/minimum); use ~0.001 ETH or more. (3) To sell "all" Speed, read balance first and pass that amount to swap (round down slightly).
+
+---
+
+## Trade like a pro (agent best practices)
+
+- **Before any trade:** Run `speed balance -c <chain> --json` and optionally `speed price -c <chain> --json` so you know native balance, token balance, and prices. Ensure sell token balance ≥ amount (or for buy-with-ETH, native balance ≥ amount + gas).
+- **Preview first when it matters:** Use `speed quote -c <chain> --sell <x> --buy <y> -a <amount> --json` or `speed swap --dry-run ... --json` before large or one-off swaps. Use `speed estimate -c <chain> --sell eth --buy speed -a <amount> --json` to see gas cost.
+- **Buy Speed with ETH:** Default is already sell ETH / buy Speed. Use `speed swap -c <chain> -a <eth-amount> -y --json` (no need to pass --sell/--buy). Or explicitly `--sell eth` or `--sell native`.
+- **Sell Speed for ETH (or “sell all”):** (1) `speed balance -c <chain> --json` → parse Speed token `balance` for that chain. (2) Round down slightly (e.g. 2 decimals). (3) `speed swap -c <chain> --sell speed --buy eth -a <amount> -y --json`.
+- **Volume:** Use `-a 0.0008` or `0.001` per buy for reliability. Ensure native balance covers (ops × amount + gas). Use `--ops` to control how many buy/sell cycles. Failures are reported in summary; run continues.
+- **DCA:** Use at least `-a 0.001` per buy. Use `--count` so the run ends (e.g. `--count 5`). Space intervals (e.g. `--interval 30s`) to avoid nonce/rate issues.
+- **Bridges:** Squid can rate-limit (429). Space bridge calls (e.g. one chain at a time, wait between). On 429, message suggests waiting and retrying.
+- **Gas (token → native):** If you see OVERFLOW, use a smaller amount (e.g. `-a 100` or `-a 300`). Large token amounts can overflow the aggregator path.
+- **Never sell and buy the same token:** CLI validates and returns SAME_TOKEN; use `--sell eth` when you want to buy Speed with ETH.
+
+---
+
+## XP and leveling (level up)
+
+Actions that grant **XP** (stored in `~/.speed/xp.json`):
+
+| Action      | Base XP | When it’s recorded |
+|------------|--------|---------------------|
+| **swap**   | 10     | Each swap (buy or sell) |
+| **bridge** | 25     | Each bridge tx      |
+| **volumeOp** | 3    | Each volume buy or sell op |
+| **dcaBuy** | 8      | Each DCA buy        |
+| **gasRefuel** | 3   | Each gas (token→native) tx |
+
+XP per action is scaled by **USD value** of the trade (log scale; higher USD = more XP) and by **daily streak** (up to 1.5× for consecutive days of activity). Small USD actions still grant at least a small amount of XP.
+
+- **Check progress:** `speed xp --json` → `totalXP`, `level`, `title`, `streak`, `progress` (e.g. `current`, `needed`, `fraction`), `stats` (count and totalUSD per action), `recentHistory`.
+- **Level thresholds:** Level 1 → 2 at **500** total XP; level 2 → 3 at **500 + 1319** total XP; each next level needs more (formula: 500 × level^1.4).
+- **To level up:** Prefer a mix of (1) **volume** (many `volumeOp`s per run: `speed volume -c base -a 0.001 --ops 20 -y --json`), (2) **swaps** (each gives XP; larger USD = more XP), (3) **bridges** (high base XP), (4) **DCA** (`dcaBuy` per buy). Keep the streak by doing at least one action per day.
+- **Efficient XP grind:** Run volume with moderate `--ops` (e.g. 15–25) and `-a 0.0008`–`0.001`; then do a few swaps (buy and sell). Use `speed xp --json` to see how close you are to the next level.
+
+---
+
+## Global options (before command)
+
+- `--json` — **Always use.** JSON to stdout; errors as `{ error, code }`.
+- `-y, --yes` — Skip confirmation (required for swap, bridge, and gas in non-interactive use).
+
+---
+
+## Commands reference
+
+### Identity & setup
+
+- **whoami** — Print wallet address (from PRIVATE_KEY). No args.  
+  `speed whoami --json`  
+  If this fails, user must run `speed setup` (interactive; do not run from bot).
+
+- **setup** — Interactive; writes secrets to `~/.speed/.env`. **Do not invoke from bots.** Direct user to run `speed setup` if whoami or doctor fails.
+
+- **doctor** — Validate env, API keys, RPC, oracles, Speed balance.  
+  `speed doctor --json` or `speed doctor -c base --json`
+
+### Balance & price
+
+- **balance** — Speed + native + optional extra tokens. Omit `-c` for all chains; use `-c base` or `-c 8453` for one chain. JSON: `chains[].chainId`, `chains[].nativeBalance` (string), `chains[].tokens[].symbol`, `tokens[].balance` (string, in token units). Use the Speed token `balance` for a chain when you need to sell that amount.  
+  `speed balance --json`  
+  `speed balance -c base --json`  
+  `speed balance -c base -t <token-address> --json` (repeat `-t` for multiple)
+
+- **price** — Speed/ETH, Speed/USD, native USD (oracle).  
+  `speed price -c base --json`
+
+### Swap (one-shot: quote → approve if needed → swap)
+
+- **swap** — Single command to execute a swap. Approve is automatic when needed. Use `-y` or `--go` to skip confirmation.  
+  `speed swap -c base --buy <token-address> -a 0.002 -y --json`  
+  To **buy Speed with native ETH**: default is sell ETH / buy Speed; or set `--sell eth` or `--sell native`. Optional: `--sell <address|speed|eth|native>`, `--buy <address|speed>`.  
+  **Preview only (no tx):** `speed swap --dry-run -c base --buy <addr> -a 0.002 --json`
+
+- **quote** — Preview swap (no transaction). Default sell is native ETH. Use `--sell eth` or `--sell native` like swap.  
+  `speed quote -c base --sell eth --buy speed -a 0.002 --json`  
+  Optional: `--sell <address|speed|eth|native>`, `--buy <address|speed>`.
+
+**Sell Speed for ETH:** `speed swap -c <chain> --sell speed --buy eth -a <amount> -y --json`. Get `<amount>` from `speed balance -c <chain> --json` (parse Speed token `balance` for that chain). Round down slightly (e.g. 2 decimals) to avoid dust/slippage.
+
+**Do not** tell users to run approve then quote then swap; **swap alone** does it. Use **quote** or **swap --dry-run** only when the user wants a preview.
+
+### Bridge
+
+- **bridge** — Bridge Speed across chains (Squid). Use `-y` to skip confirmation.  
+  `speed bridge --from-chain base --to-chain ethereum -a 100 -y --json`  
+  Optional: `--to-token <address>` (default Speed on destination).
+
+### Volume & DCA (automated buy/sell)
+
+- **volume** — Human-like volume: interleaved buys and sells (ETH ↔ token) with random-walk amounts, jittered delays, optional partial sells. Default token is Speed; use `--token <address|speed>` for another token. **Requires enough native balance:** need at least ~0.001 ETH per buy + gas; otherwise first op can exit with `INSUFFICIENT_FUNDS`. Some ops may revert (slippage); run continues; summary has `buys`, `sells`, `failed`, `totalOps`. Use `-a 0.0008` or higher for reliability.  
+  `speed volume -c base -a 0.001 --ops 20 --delay 2 --delay-jitter 0.5 --sell-frequency 0.2 -y --json`  
+  Optional: `--token`, `--amount-min`, `--amount-max`, `--amount-drift`, `--sell-partial-chance`, `--dry-run`.
+
+- **dca** — DCA: buy token with ETH on a fixed time interval. Default token is Speed; use `--token <address|speed>` for another token. **Minimum amount:** very small amounts (e.g. 0.0004–0.0005 ETH) often revert with "slippage, liquidity, or minimum amount"; use at least ~0.001 ETH per buy. `--interval` accepts seconds or `20s`, `5m`, `1h`, `1d`. Runs until `--count` buys or until stopped (Ctrl+C).  
+  `speed dca -c base -a 0.001 --interval 5m --count 10 -y --json`  
+  Optional: `--token`, `--interval-jitter <fraction>`, `--dry-run`. Omit `--count` to run until stopped.
+
+### Gas (token → native)
+
+- **gas** — Swap token for native (ETH/MATIC/BNB) to fund gas. Default token is Speed; use `--token <address|speed>` for another token. Use `-y` for non-interactive.  
+  `speed gas -c base -a 10000 -y --json`
+
+### Send & allowances
+
+- **send** — Plain ERC-20 transfer of Speed.  
+  `speed send -c base -t <recipient-address> -a 100 -y --json`
+
+- **approve** — Set token allowance for a spender (e.g. for scripting). Amount in token units or `max`.  
+  `speed approve -c base --token <token-address> --spender <spender-address> -a 1000 --json` or `-a max --json`
+
+- **allowance** — Read current allowance.  
+  `speed allowance -c base --token <token-address> --spender <spender-address> --json`
+
+- **revoke** — Set allowance to 0.  
+  `speed revoke -c base --token <token-address> --spender <spender-address> -y --json`
+
+### History & status
+
+- **history** — Recent transfers (Alchemy). Omit `-c` for all chains.  
+  `speed history --json` or `speed history -c base -n 20 --json`
+
+- **pending** — In-flight bridges + pending txs.  
+  `speed pending --json` or `speed pending --no-txs --json` (bridges only)
+
+- **status** — Tx confirmation; for bridge use Squid status.  
+  On-chain: `speed status --tx <tx-hash> -c base --json`  
+  Bridge: `speed status --tx <tx-hash> --request-id <id> --quote-id <id> --json`
+
+### XP (progress for bots)
+
+- **xp** — Show level, streak, and stats (swaps, bridges, volume ops, DCA buys, gas refuels). Bots call this to see how they're doing. Stored in `~/.speed/xp.json`.  
+  `speed xp --json`  
+  Optional: `--no-title` to omit the silly level title.
+
+### Estimate & config
+
+- **estimate** — Gas cost (ETH + USD) for swap or bridge. Amount in token units (same as swap). Same `--sell`/`--buy` tokens as swap (e.g. `--sell eth --buy speed`).  
+  Swap: `speed estimate -c base --sell eth --buy speed -a 0.002 --json`  
+  Bridge: `speed estimate -c base --to-chain ethereum --bridge --json`
+
+- **config** — Read/write `~/.speed/config.json` (no secrets).  
+  Set: `speed config set default-chain 8453 --json`  
+  Get: `speed config get --json` or `speed config get default-chain --json`  
+  Keys: `default-chain`, `default-slippage`, `output-format` (human|json).
+
+---
+
+## Recommended flows for bots
+
+1. **User wants to swap**  
+   Run: `speed swap -c <chain> --buy <token> -a <amount> -y --json`. If user wants a preview first, run `speed swap --dry-run ... --json` then same without `--dry-run` and without `-y` only if you need to ask for confirmation.
+
+2. **User wants to bridge**  
+   Run: `speed bridge --from-chain <id|name> --to-chain <id|name> -a <amount> -y --json`.
+
+3. **User wants balance**  
+   Run: `speed balance --json` (all chains) or `speed balance -c <chain> --json`.
+
+4. **User wants price**  
+   Run: `speed price -c <chain> --json`.
+
+5. **User wants to fund gas (token → native)**  
+   Run: `speed gas -c <chain> -a <token-amount> -y --json`. Default token is Speed; add `--token <address|speed>` for another token.
+
+6. **User wants volume (automated buys + sells)**  
+   Run: `speed volume -c <chain> -a <eth-per-buy> --ops <n> -y --json`. Use at least ~0.0008 ETH per buy. Failures do not stop the run; summary has `buys`, `sells`, `failed`, `totalOps`. Optional: `--delay`, `--sell-frequency`, `--token`.
+
+7. **User wants DCA (interval buys only)**  
+   Run: `speed dca -c <chain> -a <eth-per-buy> --interval <20s|5m|1h|1d> --count <n> -y --json`. Use at least ~0.001 ETH per buy to avoid slippage reverts. Omit `--count` to run until stopped. Default token is Speed; add `--token <address|speed>` for another token.
+
+8. **User wants to see XP / progress**  
+   Run: `speed xp --json`. Returns totalXP, level, title, streak, lastActivity, progress to next level, stats (count + totalUSD per action type), recent history.
+
+9. **User wants gas estimate before swap/bridge**  
+   Run: `speed estimate -c <chain> --buy <addr> -a <token-amount> --json` (swap) or `speed estimate -c <chain> --to-chain <id|name> --bridge --json` (bridge). Use same `-a` as the swap for comparable cost.
+
+10. **Check if CLI is configured**  
+   Run: `speed doctor --json` or `speed whoami --json`. If error, tell user to run `speed setup` in the terminal (interactive).
+
+11. **User wants to sell Speed for ETH (or “sell all”)**  
+   Run: `speed balance -c <chain> --json`, parse the chain’s Speed token `balance` (string, token units). Then run: `speed swap -c <chain> --sell speed --buy eth -a <amount> -y --json` with that amount (round down slightly to avoid dust).
+
+12. **Parse JSON:** On success, one JSON object per command. On failure, `{ error, code }`; show `error` to the user. Common success shapes: whoami `{ address }`, balance `{ address?, chains: [{ chainId, nativeBalance, tokens: [{ symbol, balance }] }] }`, swap/bridge/gas/send/approve `{ txHash, explorerLink? }`, quote `{ sellAmount, buyAmount, ... }`, price `{ speedPerNative, nativeUsd, ... }`, xp `{ totalXP, level, streak, stats: { swaps, volumeOps, dcaBuys, ... }, recentHistory }`, estimate `{ gasEth, gasUsd, ... }`, volume `{ summary: { buys, sells, failed, totalOps }, results, failures? }`.

package/package.json

@@ -1,47 +1,50 @@
-{
-  "name": "@lightspeed-cli/speed-cli",
-  "version": "0.1.2",
-  "description": "Speed Token CLI: swap, bridge, balance, price, volume, DCA, gas, XP. Uses 0x and Squid; config in ~/.speed.",
-  "type": "module",
-  "bin": {
-    "speed": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "openclaw"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/cli.js",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "speed",
-    "token",
-    "cli",
-    "swap",
-    "bridge",
-    "0x",
-    "squid",
-    "ethereum",
-    "base"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "@0xsquid/sdk": "^2.2.0",
-    "@0xsquid/squid-types": "^0.1.215",
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "dotenv": "^16.4.5",
-    "ethers": "^6.13.0",
-    "ora": "^8.0.1"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "typescript": "^5.3.0"
-  }
-}
+{
+  "name": "@lightspeed-cli/speed-cli",
+  "version": "0.1.4",
+  "description": "Speed Token CLI: swap, bridge, balance, price, volume, DCA, gas, XP. Uses 0x and Squid; config in ~/.speed.",
+  "type": "module",
+  "bin": {
+    "speed": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "openclaw",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsc --watch",
+    "test": "npm run build && node --test tests/constants.test.js tests/parse-amount.test.js tests/xp.test.js tests/oracle.test.js tests/cli-options.test.js",
+    "test:json": "npm run build && node tests/run-json.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "speed",
+    "token",
+    "cli",
+    "swap",
+    "bridge",
+    "0x",
+    "squid",
+    "ethereum",
+    "base"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@0xsquid/sdk": "^2.2.0",
+    "@0xsquid/squid-types": "^0.1.215",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "dotenv": "^16.4.5",
+    "ethers": "^6.13.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  }
+}