npm package: @lightspeed-cli/speed-cli
Description: Agentic command-line interface for multichain crypto: swap any token (0x), bridge assets (Squid), check balances, prices, volume, run DCA, estimate gas, track XP — plus manage permanent **.speed** agent identities on Base and trade them via SANS on OpenSe
Latest version: 0.1.14

# speed-cli

Agentic command-line interface for multichain crypto: swap any token (0x), bridge assets (Squid), check balances, prices, volume, run DCA, estimate gas, track XP — plus manage permanent **.speed** agent identities on Base and trade them via SANS on OpenSea.

All config and secrets live in `~/.speed`.

**Why speed-cli?**
- Swap or bridge any token across 6+ chains in a single command
- Register permanent onchain agent identities (`.speed` names as resolvable profiles)
- Trade identities via SANS on OpenSea (Base)
- Agent-friendly by design: `--json` and `-y` flags on every command

---

## 1. Install

**Global (recommended):**
```bash
npm install -g @lightspeed-cli/speed-cli
```

**One-off run:**
```bash
npx @lightspeed-cli/speed-cli <command>
```

---

## 2. First-time setup

```bash
speed setup
```

Interactive prompts will walk you through creating `~/.speed/.env`.

> **Get your API keys first** from the linked dashboards and forms below — have them ready before running `speed setup`.

| Variable | Purpose | Source |
|----------|---------|--------|
| `PRIVATE_KEY` | Wallet for swaps, bridges, identity (hex, with or without `0x`) | Your wallet export |
| `ALCHEMY_API_KEY` | RPC access (ETH, Base, OP, Arbitrum, Polygon, BNB) | [Alchemy](https://www.alchemy.com/) → Create app |
| `0X_API_KEY` | Swap quotes & fills | [0x Dashboard](https://dashboard.0x.org/) → Create app |
| `SQUID_INTEGRATOR_ID` | Cross-chain bridging | [Squid integrator form](https://squidrouter.typeform.com/integrator-id) |

> `.speed` identity defaults to the Base registry/factory. Override via `SPEED_REGISTRY_ADDRESS` and `SPEED_FACTORY_ADDRESS` in `.env`.

---

## 3. Verify setup

```bash
speed whoami
speed doctor              # full check
speed doctor -c base      # check a specific chain
```

If either fails, fix values in `~/.speed/.env` and retry.

---

## 4. Core commands

```bash
speed balance --json
speed price -c base
speed swap -c base --buy USDC -a 0.01 -y
speed bridge --from-chain base --to-chain ethereum -a 50 -y
```

Pass `--json` for machine-readable output. See all flags with `speed <command> --help`.

### Converting wrapped native to native (gas / unwrap)

Use `speed gas` to turn wrapped native (WETH, WPOL, WBNB) into native ETH, MATIC, or BNB for gas or spending. With no `--token`, the CLI **unwraps**: you give an amount and it withdraws that much from your wrapped balance on the chosen chain.

```bash
# Unwrap WETH → ETH on Base (default chain)
speed gas -c base -a 0.01 -y

# Unwrap on other chains (WPOL on Polygon, WBNB on BNB)
speed gas -c polygon -a 1.5 -y
speed gas -c bnb -a 0.1 -y
```

To **sell another token** (e.g. SPEED) for native instead of unwrapping, pass `--token speed` or a token address. The CLI then gets a 0x quote, runs the swap, and unwraps the received WETH to native.

```bash
speed gas -c base -t speed -a 1000 -y
```

Your wrapped native balance per chain appears in the **Wrapped** column of `speed balance`.

**Base Builder Code:** Every transaction on Base includes the CLI's [Builder Code](https://docs.base.org/base-chain/builder-codes/builder-codes) for attribution and rewards. To verify, run any Base transaction then check it on [base.dev](https://base.dev) or the [Builder Code Validation tool](https://builder-code-checker.vercel.app/).

---

## 5. .speed Agent Identities

Register a permanent onchain name (e.g. `alice.speed`) that resolves to any address and holds profile data. Costs ~**0.0025 ETH** on Base. Name must have at least 3 characters before `.speed`.

```bash
# Register
speed identity register alice.speed

# Point it to an address
speed identity set-resolve alice.speed 0xYourAddress

# Set profile
speed identity profile set alice.speed --username "Alice" --bio "AI agent" --url1 "https://..."

# Set a favorite token (use 0x0 to clear)
speed identity set-favorite-token alice.speed 0xTokenAddress

# Optional: set a fee so anyone can set the community favorite token (fee goes to you)
speed identity community set-fee alice.speed 0.0005
# Then anyone can run:
speed identity community set alice.speed 0xOtherToken

# View a profile
speed identity profile get alice.speed
```

All identity commands default to Base (chain 8453).

---

## 6. SANS — .speed Names as Tradeable Identities

[SANS](https://opensea.io/collection/speedcli-sans) (Speed Agent Name Service) makes `.speed` names tradeable identities on OpenSea (Base). Requires `OPENSEA_API_KEY` in `~/.speed/.env` for listing and offering ([get a key](https://docs.opensea.io/reference/api-keys)).

### Quick reference

```bash
# Discover listings
speed sans listings -l 30 --json

# Buy a name
speed sans buy god.speed -y

# List your name for sale
speed sans list myname.speed 0.1 -y

# Remove your listing
speed sans unlist myname.speed

# View offers on a name
speed sans offers --token-id myname.speed --json

# Make an offer (wraps ETH → WETH automatically)
speed sans offer cool.speed 0.005 -y

# Accept the best offer on a name you own
speed sans accept-offer myname.speed -y

# Cancel your offer
speed sans cancel-offer myname.speed
```

### Full command reference

| Command | Description |
|---------|-------------|
| `speed sans listings [-l N] [--json]` | Show .speed names for sale. Default limit 20, max 200. |
| `speed sans buy <name\|tokenId> [-y]` | Buy a listed name by name or token ID. |
| `speed sans list <name> <price ETH> [-y]` | List your .speed name for sale. Requires `OPENSEA_API_KEY`. |
| `speed sans unlist <name\|tokenId> [-y]` | Cancel your active listing (offchain first, then onchain fallback). |
| `speed sans offers [-l N] [--token-id <name\|tokenId>] [--json]` | List pending offers on SANS names. |
| `speed sans offer <name\|tokenId> <amountETH> [-y]` | Make a WETH offer; wraps ETH automatically. Requires `OPENSEA_API_KEY`. |
| `speed sans accept-offer <name\|tokenId> [--order-hash <hash>] [-y]` | Accept an offer on a name you own. |
| `speed sans cancel-offer <name\|tokenId> [--order-hash <hash>] [-y]` | Cancel your offer by name or order hash. |

`--json` on any command returns machine-readable output for agents and scripts. All SANS commands run on Base (chain 8453).

---

## 7. Local dev / contributing

```bash
git clone <repo-url>
cd Lightspeed-CLI
npm install
npm run build
node dist/cli.js --help

# Or link globally:
npm link
speed whoami
```

Copy or create `~/.speed/.env` with the variables from section 2 before running commands.


## For advanced tools and agentic skills clone Speed-Scripts 

git clone https://github.com/lightspeedfoundation/speed-scripts/

includes Speed-CLI functions:
bracket-any
compression-buy-any
crash-buy-any
grid-trade-any
hybrid-exit-any
ladder-buy-any
ladder-sell-any
limit-order-any
mean-revert-any
momentum-any
trailing-stoploss-any
twap-buy-any
twap-sell-any
value-average-any
function-builder-skill.md
scripts-reference.md

and more advanced skills added all the time.