sequence-builder

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

# 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.

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.

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

JSON output:

{
  "privateKey": "0x4c0883a...",
  "address": "0x89D9F8f...",
  "keyStored": true
}

wallet-info

Show EOA and Sequence smart wallet addresses.

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:

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

login

Authenticate with Sequence Builder.

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:

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

projects

Manage Sequence Builder projects. Requires login.

# 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.

# 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.

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:

{
  "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.

# 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

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

# 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

# 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.