sequence-builder

What this skill does

# Sequence Builder CLI

CLI for Sequence Builder — designed for AI agents and automation. Create wallets, authenticate, manage projects, query blockchain data, and send ERC20 transfers from the command line.

All commands support `--json` for machine-readable output. Always use `--json` when parsing results programmatically.

## Prerequisites

- Node.js 18+
- A Sequence Builder account (created automatically on first login)

## Quick Start

```bash
# 1. Create a wallet
npx @0xsequence/builder-cli create-wallet --json

# 2. Login with the private key from step 1
npx @0xsequence/builder-cli login -k <private-key> --json

# 3. Create a project and get an access key
npx @0xsequence/builder-cli projects create "My Project" --json

# 4. Get wallet addresses (EOA + Sequence smart wallet)
npx @0xsequence/builder-cli wallet-info -k <private-key> -a <access-key> --json

# 5. Fund the Sequence wallet via the Trails link from step 4

# 6. Send an ERC20 transfer
npx @0xsequence/builder-cli transfer \
  -k <private-key> -a <access-key> \
  -t <token-address> -r <recipient> \
  -m <amount> -c <chain-id> --json
```

## Encrypted Key Storage

Set `SEQUENCE_PASSPHRASE` to auto-encrypt and store the private key locally. Once stored, you no longer need to pass `-k` on every command.

```bash
export SEQUENCE_PASSPHRASE="your-strong-secret"
npx @0xsequence/builder-cli create-wallet --json
# Private key is now encrypted in ~/.sequence-builder/config.json
# All subsequent commands will use the stored key automatically
```

## Understanding Wallet Addresses

This CLI uses **Sequence Smart Wallets** for transfers:

- **EOA Address** — Standard Ethereum address from your private key. Used for login and project ownership.
- **Sequence Wallet Address** — Smart contract wallet that can pay gas fees with ERC20 tokens (no native token needed). Used for transfers.

**Always send tokens to the Sequence Wallet Address** for use with the `transfer` command. Use `wallet-info` to see both addresses.

## Command Reference

### create-wallet

Generate a new EOA keypair.

```bash
npx @0xsequence/builder-cli create-wallet --json
```

JSON output:
```json
{
  "privateKey": "0x4c0883a...",
  "address": "0x89D9F8f...",
  "keyStored": true
}
```

### wallet-info

Show EOA and Sequence smart wallet addresses.

```bash
npx @0xsequence/builder-cli wallet-info -k <private-key> -a <access-key> --json
```

Options:
- `-k, --private-key <key>` — Wallet private key (optional if stored)
- `-a, --access-key <key>` — Project access key (required)

JSON output:
```json
{
  "eoaAddress": "0x742BDb3...",
  "sequenceWalletAddress": "0xA71506...",
  "fundingUrl": "https://demo.trails.build/..."
}
```

### login

Authenticate with Sequence Builder.

```bash
npx @0xsequence/builder-cli login -k <private-key> --json
```

Options:
- `-k, --private-key <key>` — Wallet private key (optional if stored)
- `-e, --email <email>` — Email to associate with the account
- `--env <environment>` — Environment: `prod` (default) or `dev`
- `--api-url <url>` — Custom API URL

JSON output:
```json
{
  "success": true,
  "address": "0x742BDb3...",
  "expiresAt": "2026-02-07T12:00:00Z"
}
```

### projects

Manage Sequence Builder projects. Requires login.

```bash
# List all projects
npx @0xsequence/builder-cli projects --json

# Create a new project
npx @0xsequence/builder-cli projects create "My Game" --json

# Create with specific chains
npx @0xsequence/builder-cli projects create "My Game" --chain-ids 137,8453 --json

# Get project details
npx @0xsequence/builder-cli projects get <project-id> --json
```

### apikeys

Manage API keys for a project. Requires login.

```bash
# List all API keys
npx @0xsequence/builder-cli apikeys <project-id> --json

# Get the default API key
npx @0xsequence/builder-cli apikeys default <project-id> --json
```

### transfer

Send an ERC20 token transfer using the Sequence smart wallet. Gas fees are paid with the same token being transferred — no native token needed.

```bash
npx @0xsequence/builder-cli transfer \
  -k <private-key> \
  -a <access-key> \
  -t <token-address> \
  -r <recipient-address> \
  -m <amount> \
  -c <chain-id> \
  --json
```

Options:
- `-k, --private-key <key>` — Wallet private key (optional if stored)
- `-a, --access-key <key>` — Project access key (required)
- `-t, --token <address>` — ERC20 token contract address (required)
- `-r, --recipient <address>` — Recipient address (required)
- `-m, --amount <amount>` — Amount in token units, e.g. `10.5` (required)
- `-c, --chain-id <chainId>` — Chain ID (required)

JSON output:
```json
{
  "success": true,
  "transactionHash": "0xabc123...",
  "from": "0xA71506...",
  "to": "0x123456...",
  "token": "0x833589...",
  "amount": "10.5",
  "symbol": "USDC",
  "chainId": 8453
}
```

### indexer

Query blockchain data using the Sequence Indexer.

```bash
# Get token balances
npx @0xsequence/builder-cli indexer balances <address> \
  -a <access-key> -c <chain-id> --include-metadata --json

# Get native token balance (ETH, MATIC, etc.)
npx @0xsequence/builder-cli indexer native-balance <address> \
  -a <access-key> -c <chain-id> --json

# Get transaction history
npx @0xsequence/builder-cli indexer history <address> \
  -a <access-key> -c <chain-id> --limit 20 --json

# Get token contract info
npx @0xsequence/builder-cli indexer token-info <contract-address> \
  -a <access-key> -c <chain-id> --json
```

## Supported Networks

| Network | Chain ID |
|---------|----------|
| Ethereum | 1 |
| Polygon | 137 |
| Base | 8453 |
| Arbitrum | 42161 |
| Optimism | 10 |
| BSC | 56 |
| Avalanche | 43114 |

Full list: https://status.sequence.info/

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 10 | Not logged in |
| 11 | Invalid private key |
| 20 | Insufficient funds |
| 30 | No projects found |
| 31 | Project not found |
| 40 | API error |

## Common Workflows

### Full setup from scratch

```bash
export SEQUENCE_PASSPHRASE="my-secret"
npx @0xsequence/builder-cli create-wallet --json
# Save the output — privateKey and address
npx @0xsequence/builder-cli login --json
npx @0xsequence/builder-cli projects create "My App" --json
# Note the accessKey from the output
npx @0xsequence/builder-cli wallet-info -a <access-key> --json
# Fund the sequenceWalletAddress via the fundingUrl
```

### Check balance then transfer

```bash
# Check balance first
npx @0xsequence/builder-cli indexer balances <your-sequence-wallet> \
  -a <access-key> -c 8453 --json

# Send transfer
npx @0xsequence/builder-cli transfer \
  -a <access-key> -t <token> -r <recipient> -m 10 -c 8453 --json
```

### Multi-chain balance check

```bash
# Check across multiple chains
npx @0xsequence/builder-cli indexer balances <address> -a <key> -c 1 --json
npx @0xsequence/builder-cli indexer balances <address> -a <key> -c 137 --json
npx @0xsequence/builder-cli indexer balances <address> -a <key> -c 8453 --json
```

## Configuration

Stored in `~/.sequence-builder/config.json`:
- JWT token for authentication
- Environment settings (prod/dev)
- Encrypted private key (when `SEQUENCE_PASSPHRASE` is set)

## Troubleshooting

**"Not logged in" error:** Run `login` first. JWT tokens expire — re-run login if expired.

**"Invalid private key" error:** Key must be a 64-character hex string (with or without `0x` prefix). If using stored key, verify `SEQUENCE_PASSPHRASE` is correct.

**"Insufficient balance" error:** Send tokens to the **Sequence Wallet Address** (not the EOA). Use `wallet-info` to get the correct address.

**Transfer fails:** Ensure the Sequence wallet has enough of the token being transferred. The same token is used to pay gas fees.