@lightspeed-cli/speed-cli 0.1.0 → 0.1.1

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

@@ -0,0 +1,189 @@
+---
+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?, ... }`.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@lightspeed-cli/speed-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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"
+    "dist",
+    "openclaw"
   ],
   "scripts": {
     "build": "tsc",