@lightspeed-cli/speed-cli 0.1.3 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -21
- package/dist/cli.js +1 -1
- package/dist/commands/bridge.js +11 -27
- package/openclaw/skills/speed-token/SKILL.md +233 -240
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -17,27 +17,16 @@ npx @lightspeed-cli/speed-cli whoami
|
|
|
17
17
|
npx @lightspeed-cli/speed-cli balance --json
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
**First-time setup:** Run `speed setup` to configure `~/.speed/.env
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
2. **Build and publish** (scoped packages require `--access public`):
|
|
31
|
-
```bash
|
|
32
|
-
npm run build
|
|
33
|
-
npm publish --access public
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
3. **After publishing**, anyone can install and use the `speed` command:
|
|
37
|
-
```bash
|
|
38
|
-
npm install -g @lightspeed-cli/speed-cli
|
|
39
|
-
speed --help
|
|
40
|
-
```
|
|
20
|
+
**First-time setup:** Run `speed setup` to configure `~/.speed/.env`. You’ll need:
|
|
21
|
+
|
|
22
|
+
| What | Used for | Get it |
|
|
23
|
+
|------|----------|--------|
|
|
24
|
+
| **Alchemy API key** | RPC (Ethereum, Base, OP, Arbitrum, Polygon, BNB) | [alchemy.com](https://www.alchemy.com/) → Create app, copy API key |
|
|
25
|
+
| **0x API key** | Swaps (quote + execute) | [0x.org](https://0x.org/) → Dashboard, create app, API key |
|
|
26
|
+
| **Squid integrator ID** | Bridging across chains | [Squid integrator form](https://squidrouter.typeform.com/integrator-id) |
|
|
27
|
+
|
|
28
|
+
See `.env.example` for variable names, or run `speed setup --help`.
|
|
29
|
+
|
|
41
30
|
|
|
42
31
|
## Develop locally
|
|
43
32
|
|
package/dist/cli.js
CHANGED
|
@@ -28,7 +28,7 @@ const program = new Command();
|
|
|
28
28
|
program
|
|
29
29
|
.name("speed")
|
|
30
30
|
.description("Speed Token CLI: swap, bridge, balance, price, volume, dca, gas, history, xp, and more. Default token is Speed.")
|
|
31
|
-
.version("0.1.
|
|
31
|
+
.version("0.1.4")
|
|
32
32
|
.option("-y, --yes", "Skip confirmation for swap/bridge (safe for scripts)")
|
|
33
33
|
.option("--json", "Output machine-readable JSON to stdout (for scripts and OpenClaw)");
|
|
34
34
|
program.addCommand(whoamiCmd());
|
package/dist/commands/bridge.js
CHANGED
|
@@ -5,7 +5,7 @@ import { getSigner } from "../wallet.js";
|
|
|
5
5
|
import { getSquid } from "../lib/squid.js";
|
|
6
6
|
import { getEthUsdPriceNumber } from "../lib/oracle.js";
|
|
7
7
|
import { ethers } from "ethers";
|
|
8
|
-
import { EXPLORER_URLS,
|
|
8
|
+
import { EXPLORER_URLS, SPEED_TOKEN_ADDRESS, resolveChainId, getChainOptionsHint } from "../constants.js";
|
|
9
9
|
import { getDefaultChainInput } from "./config.js";
|
|
10
10
|
import { out, exitWithError, setJsonMode, isJsonMode, success, usageHint } from "../output.js";
|
|
11
11
|
import { addPendingBridge } from "../lib/pending-bridges.js";
|
|
@@ -22,24 +22,13 @@ function askConfirm(prompt) {
|
|
|
22
22
|
});
|
|
23
23
|
});
|
|
24
24
|
}
|
|
25
|
-
/** Resolve --from-token to Squid token address. speed → SPEED; native/eth/bnb/pol/matic → native sentinel. */
|
|
26
|
-
function resolveFromToken(opt, fromChainId) {
|
|
27
|
-
const s = (opt ?? "speed").trim().toLowerCase();
|
|
28
|
-
if (s === "speed")
|
|
29
|
-
return { address: SPEED_TOKEN_ADDRESS, isNative: false };
|
|
30
|
-
if (s === "native" || s === "eth" || s === "ether" || s === "bnb" || s === "pol" || s === "matic") {
|
|
31
|
-
return { address: NATIVE_ETH_0X, isNative: true };
|
|
32
|
-
}
|
|
33
|
-
return { address: SPEED_TOKEN_ADDRESS, isNative: false };
|
|
34
|
-
}
|
|
35
25
|
export function bridgeCmd() {
|
|
36
26
|
return new Command("bridge")
|
|
37
|
-
.description("Bridge Speed
|
|
27
|
+
.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).")
|
|
38
28
|
.option("--from-chain <id|name>", "Source chain (ID or name, e.g. base or 8453)", "8453")
|
|
39
29
|
.option("--to-chain <id|name>", "Destination chain (ID or name, e.g. ethereum or 1)")
|
|
40
|
-
.option("
|
|
41
|
-
.option("-
|
|
42
|
-
.option("--to-token <address>", "Destination token address (default: same as from-token on to-chain; use for Speed → Speed)")
|
|
30
|
+
.option("-a, --amount <amount>", "Amount of SPEED to bridge (e.g. 0.1, 1000)")
|
|
31
|
+
.option("--to-token <address>", "Destination token (default: Speed on to-chain)")
|
|
43
32
|
.action(async function (opts) {
|
|
44
33
|
setJsonMode(this.parent?.opts().json ?? false);
|
|
45
34
|
const yes = this.parent?.opts().yes ?? false;
|
|
@@ -55,10 +44,7 @@ export function bridgeCmd() {
|
|
|
55
44
|
exitWithError("--amount is required. Example: speed bridge --from-chain base --to-chain ethereum -a 1000", "MISSING_ARGS");
|
|
56
45
|
}
|
|
57
46
|
const amount = parseTokenAmountToWei(opts.amount.trim());
|
|
58
|
-
const
|
|
59
|
-
const toToken = opts.toToken?.trim() ?? (isNative ? NATIVE_ETH_0X : SPEED_TOKEN_ADDRESS);
|
|
60
|
-
const nativeSymbol = NATIVE_SYMBOL[fromChainId] ?? "ETH";
|
|
61
|
-
const assetLabel = isNative ? nativeSymbol : "SPEED";
|
|
47
|
+
const toToken = opts.toToken?.trim() ?? SPEED_TOKEN_ADDRESS;
|
|
62
48
|
try {
|
|
63
49
|
const signer = getSigner(fromChainId);
|
|
64
50
|
const fromAddress = await signer.getAddress();
|
|
@@ -69,7 +55,7 @@ export function bridgeCmd() {
|
|
|
69
55
|
const { route, requestId } = await squid.getRoute({
|
|
70
56
|
fromAddress,
|
|
71
57
|
fromChain: String(fromChainId),
|
|
72
|
-
fromToken,
|
|
58
|
+
fromToken: SPEED_TOKEN_ADDRESS,
|
|
73
59
|
fromAmount: amount,
|
|
74
60
|
toChain: String(toChainId),
|
|
75
61
|
toToken,
|
|
@@ -90,8 +76,8 @@ export function bridgeCmd() {
|
|
|
90
76
|
catch (_) { }
|
|
91
77
|
if (!yes && !isJsonMode()) {
|
|
92
78
|
const amountHuman = parseFloat(ethers.formatEther(amount)).toLocaleString(undefined, { maximumFractionDigits: 6 });
|
|
93
|
-
out(`Bridge ${amountHuman}
|
|
94
|
-
out(`Estimated gas: ${gasEth}
|
|
79
|
+
out(`Bridge ${amountHuman} SPEED from chain ${fromChainId} to chain ${toChainId}`);
|
|
80
|
+
out(`Estimated gas: ${gasEth} ETH (~$${gasUsd})`);
|
|
95
81
|
const ok = await askConfirm("Proceed? [y/N] ");
|
|
96
82
|
if (!ok) {
|
|
97
83
|
out("Aborted.");
|
|
@@ -100,7 +86,7 @@ export function bridgeCmd() {
|
|
|
100
86
|
}
|
|
101
87
|
const txRequest = route.transactionRequest;
|
|
102
88
|
const target = txRequest?.target;
|
|
103
|
-
if (target
|
|
89
|
+
if (target) {
|
|
104
90
|
const approveSpinner = isJsonMode() ? null : ora("Approving...").start();
|
|
105
91
|
const token = new ethers.Contract(SPEED_TOKEN_ADDRESS, ERC20_ABI, signer);
|
|
106
92
|
const txApprove = await token.approve(target, amount);
|
|
@@ -131,10 +117,8 @@ export function bridgeCmd() {
|
|
|
131
117
|
});
|
|
132
118
|
try {
|
|
133
119
|
const amountNum = parseFloat(ethers.formatEther(amount));
|
|
134
|
-
const
|
|
135
|
-
|
|
136
|
-
: amountNum * (await getSpeedUsdPriceNumber(fromChainId));
|
|
137
|
-
recordXpAction("bridge", usd);
|
|
120
|
+
const speedUsd = await getSpeedUsdPriceNumber(fromChainId);
|
|
121
|
+
recordXpAction("bridge", amountNum * speedUsd);
|
|
138
122
|
}
|
|
139
123
|
catch (_) { }
|
|
140
124
|
const explorer = EXPLORER_URLS[fromChainId];
|
|
@@ -1,240 +1,233 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: speed-token
|
|
3
|
-
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.
|
|
4
|
-
permissions:
|
|
5
|
-
- network:outbound
|
|
6
|
-
triggers:
|
|
7
|
-
- "speed"
|
|
8
|
-
- "speed token"
|
|
9
|
-
- "speed swap"
|
|
10
|
-
- "speed bridge"
|
|
11
|
-
- "speed balance"
|
|
12
|
-
- "speed quote"
|
|
13
|
-
- "speed price"
|
|
14
|
-
- "speed gas"
|
|
15
|
-
- "speed send"
|
|
16
|
-
- "speed approve"
|
|
17
|
-
- "speed allowance"
|
|
18
|
-
- "speed revoke"
|
|
19
|
-
- "speed history"
|
|
20
|
-
- "speed pending"
|
|
21
|
-
- "speed status"
|
|
22
|
-
- "speed doctor"
|
|
23
|
-
- "speed whoami"
|
|
24
|
-
- "speed config"
|
|
25
|
-
- "speed setup"
|
|
26
|
-
- "speed estimate"
|
|
27
|
-
- "speed volume"
|
|
28
|
-
- "speed dca"
|
|
29
|
-
- "speed xp"
|
|
30
|
-
---
|
|
31
|
-
|
|
32
|
-
# Speed Token CLI — OpenClaw skill
|
|
33
|
-
|
|
34
|
-
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.
|
|
35
|
-
|
|
36
|
-
**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.
|
|
37
|
-
|
|
38
|
-
**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).
|
|
39
|
-
|
|
40
|
-
**Amounts:** Use **token units** (e.g. `-a 0.002`, `-a 1000`), not wei. Commands that take `-a` accept human-readable amounts.
|
|
41
|
-
|
|
42
|
-
**Speed token (default):** Address `0xB01CF1bE9568f09449382a47Cd5bF58e2A9D5922`. Volume, DCA, and gas default to Speed; use `--token <address|speed>` to use another token.
|
|
43
|
-
|
|
44
|
-
**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`.
|
|
45
|
-
|
|
46
|
-
**Shell note:** Examples use `||` (Bash). On PowerShell use `;` instead of `||` to chain commands.
|
|
47
|
-
|
|
48
|
-
**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).
|
|
49
|
-
|
|
50
|
-
---
|
|
51
|
-
|
|
52
|
-
## Trade like a pro (agent best practices)
|
|
53
|
-
|
|
54
|
-
- **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).
|
|
55
|
-
- **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.
|
|
56
|
-
- **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`.
|
|
57
|
-
- **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`.
|
|
58
|
-
- **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.
|
|
59
|
-
- **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.
|
|
60
|
-
- **
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
- **
|
|
110
|
-
`speed
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
- **
|
|
115
|
-
`speed
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
- **
|
|
120
|
-
`speed
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
- **
|
|
125
|
-
`speed
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
`speed
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
-
|
|
177
|
-
`speed
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
`speed
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
10. **Check if CLI is configured**
|
|
235
|
-
Run: `speed doctor --json` or `speed whoami --json`. If error, tell user to run `speed setup` in the terminal (interactive).
|
|
236
|
-
|
|
237
|
-
11. **User wants to sell Speed for ETH (or “sell all”)**
|
|
238
|
-
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).
|
|
239
|
-
|
|
240
|
-
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? }`.
|
|
1
|
+
---
|
|
2
|
+
name: speed-token
|
|
3
|
+
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.
|
|
4
|
+
permissions:
|
|
5
|
+
- network:outbound
|
|
6
|
+
triggers:
|
|
7
|
+
- "speed"
|
|
8
|
+
- "speed token"
|
|
9
|
+
- "speed swap"
|
|
10
|
+
- "speed bridge"
|
|
11
|
+
- "speed balance"
|
|
12
|
+
- "speed quote"
|
|
13
|
+
- "speed price"
|
|
14
|
+
- "speed gas"
|
|
15
|
+
- "speed send"
|
|
16
|
+
- "speed approve"
|
|
17
|
+
- "speed allowance"
|
|
18
|
+
- "speed revoke"
|
|
19
|
+
- "speed history"
|
|
20
|
+
- "speed pending"
|
|
21
|
+
- "speed status"
|
|
22
|
+
- "speed doctor"
|
|
23
|
+
- "speed whoami"
|
|
24
|
+
- "speed config"
|
|
25
|
+
- "speed setup"
|
|
26
|
+
- "speed estimate"
|
|
27
|
+
- "speed volume"
|
|
28
|
+
- "speed dca"
|
|
29
|
+
- "speed xp"
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
# Speed Token CLI — OpenClaw skill
|
|
33
|
+
|
|
34
|
+
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.
|
|
35
|
+
|
|
36
|
+
**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.
|
|
37
|
+
|
|
38
|
+
**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).
|
|
39
|
+
|
|
40
|
+
**Amounts:** Use **token units** (e.g. `-a 0.002`, `-a 1000`), not wei. Commands that take `-a` accept human-readable amounts.
|
|
41
|
+
|
|
42
|
+
**Speed token (default):** Address `0xB01CF1bE9568f09449382a47Cd5bF58e2A9D5922`. Volume, DCA, and gas default to Speed; use `--token <address|speed>` to use another token.
|
|
43
|
+
|
|
44
|
+
**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`.
|
|
45
|
+
|
|
46
|
+
**Shell note:** Examples use `||` (Bash). On PowerShell use `;` instead of `||` to chain commands.
|
|
47
|
+
|
|
48
|
+
**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).
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Trade like a pro (agent best practices)
|
|
53
|
+
|
|
54
|
+
- **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).
|
|
55
|
+
- **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.
|
|
56
|
+
- **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`.
|
|
57
|
+
- **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`.
|
|
58
|
+
- **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.
|
|
59
|
+
- **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.
|
|
60
|
+
- **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.
|
|
61
|
+
- **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.
|
|
62
|
+
- **Never sell and buy the same token:** CLI validates and returns SAME_TOKEN; use `--sell eth` when you want to buy Speed with ETH.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## XP and leveling (level up)
|
|
67
|
+
|
|
68
|
+
Actions that grant **XP** (stored in `~/.speed/xp.json`):
|
|
69
|
+
|
|
70
|
+
| Action | Base XP | When it’s recorded |
|
|
71
|
+
|------------|--------|---------------------|
|
|
72
|
+
| **swap** | 10 | Each swap (buy or sell) |
|
|
73
|
+
| **bridge** | 25 | Each bridge tx |
|
|
74
|
+
| **volumeOp** | 3 | Each volume buy or sell op |
|
|
75
|
+
| **dcaBuy** | 8 | Each DCA buy |
|
|
76
|
+
| **gasRefuel** | 3 | Each gas (token→native) tx |
|
|
77
|
+
|
|
78
|
+
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.
|
|
79
|
+
|
|
80
|
+
- **Check progress:** `speed xp --json` → `totalXP`, `level`, `title`, `streak`, `progress` (e.g. `current`, `needed`, `fraction`), `stats` (count and totalUSD per action), `recentHistory`.
|
|
81
|
+
- **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).
|
|
82
|
+
- **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.
|
|
83
|
+
- **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.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Global options (before command)
|
|
88
|
+
|
|
89
|
+
- `--json` — **Always use.** JSON to stdout; errors as `{ error, code }`.
|
|
90
|
+
- `-y, --yes` — Skip confirmation (required for swap, bridge, and gas in non-interactive use).
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Commands reference
|
|
95
|
+
|
|
96
|
+
### Identity & setup
|
|
97
|
+
|
|
98
|
+
- **whoami** — Print wallet address (from PRIVATE_KEY). No args.
|
|
99
|
+
`speed whoami --json`
|
|
100
|
+
If this fails, user must run `speed setup` (interactive; do not run from bot).
|
|
101
|
+
|
|
102
|
+
- **setup** — Interactive; writes secrets to `~/.speed/.env`. **Do not invoke from bots.** Direct user to run `speed setup` if whoami or doctor fails.
|
|
103
|
+
|
|
104
|
+
- **doctor** — Validate env, API keys, RPC, oracles, Speed balance.
|
|
105
|
+
`speed doctor --json` or `speed doctor -c base --json`
|
|
106
|
+
|
|
107
|
+
### Balance & price
|
|
108
|
+
|
|
109
|
+
- **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.
|
|
110
|
+
`speed balance --json`
|
|
111
|
+
`speed balance -c base --json`
|
|
112
|
+
`speed balance -c base -t <token-address> --json` (repeat `-t` for multiple)
|
|
113
|
+
|
|
114
|
+
- **price** — Speed/ETH, Speed/USD, native USD (oracle).
|
|
115
|
+
`speed price -c base --json`
|
|
116
|
+
|
|
117
|
+
### Swap (one-shot: quote → approve if needed → swap)
|
|
118
|
+
|
|
119
|
+
- **swap** — Single command to execute a swap. Approve is automatic when needed. Use `-y` or `--go` to skip confirmation.
|
|
120
|
+
`speed swap -c base --buy <token-address> -a 0.002 -y --json`
|
|
121
|
+
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>`.
|
|
122
|
+
**Preview only (no tx):** `speed swap --dry-run -c base --buy <addr> -a 0.002 --json`
|
|
123
|
+
|
|
124
|
+
- **quote** — Preview swap (no transaction). Default sell is native ETH. Use `--sell eth` or `--sell native` like swap.
|
|
125
|
+
`speed quote -c base --sell eth --buy speed -a 0.002 --json`
|
|
126
|
+
Optional: `--sell <address|speed|eth|native>`, `--buy <address|speed>`.
|
|
127
|
+
|
|
128
|
+
**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.
|
|
129
|
+
|
|
130
|
+
**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.
|
|
131
|
+
|
|
132
|
+
### Bridge
|
|
133
|
+
|
|
134
|
+
- **bridge** — Bridge Speed across chains (Squid). Use `-y` to skip confirmation.
|
|
135
|
+
`speed bridge --from-chain base --to-chain ethereum -a 100 -y --json`
|
|
136
|
+
Optional: `--to-token <address>` (default Speed on destination).
|
|
137
|
+
|
|
138
|
+
### Volume & DCA (automated buy/sell)
|
|
139
|
+
|
|
140
|
+
- **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.
|
|
141
|
+
`speed volume -c base -a 0.001 --ops 20 --delay 2 --delay-jitter 0.5 --sell-frequency 0.2 -y --json`
|
|
142
|
+
Optional: `--token`, `--amount-min`, `--amount-max`, `--amount-drift`, `--sell-partial-chance`, `--dry-run`.
|
|
143
|
+
|
|
144
|
+
- **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).
|
|
145
|
+
`speed dca -c base -a 0.001 --interval 5m --count 10 -y --json`
|
|
146
|
+
Optional: `--token`, `--interval-jitter <fraction>`, `--dry-run`. Omit `--count` to run until stopped.
|
|
147
|
+
|
|
148
|
+
### Gas (token → native)
|
|
149
|
+
|
|
150
|
+
- **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.
|
|
151
|
+
`speed gas -c base -a 10000 -y --json`
|
|
152
|
+
|
|
153
|
+
### Send & allowances
|
|
154
|
+
|
|
155
|
+
- **send** — Plain ERC-20 transfer of Speed.
|
|
156
|
+
`speed send -c base -t <recipient-address> -a 100 -y --json`
|
|
157
|
+
|
|
158
|
+
- **approve** — Set token allowance for a spender (e.g. for scripting). Amount in token units or `max`.
|
|
159
|
+
`speed approve -c base --token <token-address> --spender <spender-address> -a 1000 --json` or `-a max --json`
|
|
160
|
+
|
|
161
|
+
- **allowance** — Read current allowance.
|
|
162
|
+
`speed allowance -c base --token <token-address> --spender <spender-address> --json`
|
|
163
|
+
|
|
164
|
+
- **revoke** — Set allowance to 0.
|
|
165
|
+
`speed revoke -c base --token <token-address> --spender <spender-address> -y --json`
|
|
166
|
+
|
|
167
|
+
### History & status
|
|
168
|
+
|
|
169
|
+
- **history** — Recent transfers (Alchemy). Omit `-c` for all chains.
|
|
170
|
+
`speed history --json` or `speed history -c base -n 20 --json`
|
|
171
|
+
|
|
172
|
+
- **pending** — In-flight bridges + pending txs.
|
|
173
|
+
`speed pending --json` or `speed pending --no-txs --json` (bridges only)
|
|
174
|
+
|
|
175
|
+
- **status** — Tx confirmation; for bridge use Squid status.
|
|
176
|
+
On-chain: `speed status --tx <tx-hash> -c base --json`
|
|
177
|
+
Bridge: `speed status --tx <tx-hash> --request-id <id> --quote-id <id> --json`
|
|
178
|
+
|
|
179
|
+
### XP (progress for bots)
|
|
180
|
+
|
|
181
|
+
- **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`.
|
|
182
|
+
`speed xp --json`
|
|
183
|
+
Optional: `--no-title` to omit the silly level title.
|
|
184
|
+
|
|
185
|
+
### Estimate & config
|
|
186
|
+
|
|
187
|
+
- **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`).
|
|
188
|
+
Swap: `speed estimate -c base --sell eth --buy speed -a 0.002 --json`
|
|
189
|
+
Bridge: `speed estimate -c base --to-chain ethereum --bridge --json`
|
|
190
|
+
|
|
191
|
+
- **config** — Read/write `~/.speed/config.json` (no secrets).
|
|
192
|
+
Set: `speed config set default-chain 8453 --json`
|
|
193
|
+
Get: `speed config get --json` or `speed config get default-chain --json`
|
|
194
|
+
Keys: `default-chain`, `default-slippage`, `output-format` (human|json).
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## Recommended flows for bots
|
|
199
|
+
|
|
200
|
+
1. **User wants to swap**
|
|
201
|
+
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.
|
|
202
|
+
|
|
203
|
+
2. **User wants to bridge**
|
|
204
|
+
Run: `speed bridge --from-chain <id|name> --to-chain <id|name> -a <amount> -y --json`.
|
|
205
|
+
|
|
206
|
+
3. **User wants balance**
|
|
207
|
+
Run: `speed balance --json` (all chains) or `speed balance -c <chain> --json`.
|
|
208
|
+
|
|
209
|
+
4. **User wants price**
|
|
210
|
+
Run: `speed price -c <chain> --json`.
|
|
211
|
+
|
|
212
|
+
5. **User wants to fund gas (token → native)**
|
|
213
|
+
Run: `speed gas -c <chain> -a <token-amount> -y --json`. Default token is Speed; add `--token <address|speed>` for another token.
|
|
214
|
+
|
|
215
|
+
6. **User wants volume (automated buys + sells)**
|
|
216
|
+
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`.
|
|
217
|
+
|
|
218
|
+
7. **User wants DCA (interval buys only)**
|
|
219
|
+
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.
|
|
220
|
+
|
|
221
|
+
8. **User wants to see XP / progress**
|
|
222
|
+
Run: `speed xp --json`. Returns totalXP, level, title, streak, lastActivity, progress to next level, stats (count + totalUSD per action type), recent history.
|
|
223
|
+
|
|
224
|
+
9. **User wants gas estimate before swap/bridge**
|
|
225
|
+
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.
|
|
226
|
+
|
|
227
|
+
10. **Check if CLI is configured**
|
|
228
|
+
Run: `speed doctor --json` or `speed whoami --json`. If error, tell user to run `speed setup` in the terminal (interactive).
|
|
229
|
+
|
|
230
|
+
11. **User wants to sell Speed for ETH (or “sell all”)**
|
|
231
|
+
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).
|
|
232
|
+
|
|
233
|
+
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
CHANGED