How TokenBot Works

TokenBot watches a Strategy account and replicates its trades onto your Copier accounts. Here's exactly how it happens — all from the tokenbot command line.

---

The Basic Flow

┌─────────────────────────────────────────────────────────────────┐
│                        YOUR TRADING                             │
│                                                                 │
│   1. A trade fires on      2. TokenBot          3. The trade    │
│      your Strategy      →     replicates     →     lands on     │
│      account                  it                   your Copiers  │
│                                                                 │
│   ┌─────────────┐         ┌─────────────┐      ┌───────────┐   │
│   │  STRATEGY   │    →    │  TokenBot   │  →   │  COPIER   │   │
│   │  (Binance)  │         │   backend   │      │  (Bybit)  │   │
│   │  Buy 1 BTC  │         │             │      ├───────────┤   │
│   └─────────────┘         └─────────────┘      │  COPIER   │   │
│                                                │   (OKX)   │   │
│                                                └───────────┘   │
└─────────────────────────────────────────────────────────────────┘

---

Step by Step

Step 1: Install the CLI and Create Your Identity

npm install -g tokenbot      # or: brew tap tokenbot-org/tokenbot && brew install tokenbot
tokenbot init

tokenbot init generates a secp256k1 keypair — your cryptographic identity. The private key is encrypted with a passphrase you choose and stored locally at ~/.tokenbot/config.json. Your public key is registered with TokenBot, and from then on every request the CLI makes is signed with your key. There are no passwords to leak.

Requires Node.js 22 or newer.

Step 2: Connect Your Exchanges

You create API keys on your exchanges (Binance, Bybit, OKX, etc.) and add them to TokenBot. You choose how those keys are stored:

• Local keys — tokenbot keys add encrypts the credentials on your own machine (~/.tokenbot/keys.json) and never sends them to the server. These power local commands like tokenbot balance.

• Server-side accounts — tokenbot exchange add sends the credentials to TokenBot, where they are stored encrypted at rest, so the automated engines can trade for you. The engines run on our servers on a schedule, so this is the only way they can place orders on your behalf.

Important: You control what API keys can do. For TokenBot, you only enable "trade" permissions. You do not enable "withdrawal" permissions. TokenBot can place trades but can never move your money out.

Step 3: Create a Strategy

A Strategy is the source of truth — the account whose trades get replicated.

tokenbot strategy add --name "My Main" --exchange-account-id <id>

Step 4: Add Copiers and Link Them

A Copier is an account that follows a Strategy. Create one and link it:

tokenbot copier add --strategy <id> --exchange-account-id <id> --allocation 50
tokenbot link --strategy <id> --copier <id>

Both steps are required: a new copier is created inactive and copies nothing until tokenbot link arms it.

When the Strategy buys ETH, each linked Copier buys ETH too — sized by its allocation. When the Strategy sells, the Copiers sell.

Step 5: Trade

That's it. Trade on your Strategy account as you always have, and TokenBot replicates to your Copiers automatically. Check on everything with:

tokenbot links list        # see every copier and the strategy it follows
tokenbot balance --all     # local balances across your exchanges

---

Trade Matching Options

A Copier's allocation controls how its trades are sized relative to the Strategy.

Same Size

Allocate so the Copier mirrors the exact trade size. If the Strategy buys 0.5 ETH, the Copier buys 0.5 ETH.

Proportional

Scale based on account size. If your Strategy account has $10,000 and your Copier has $5,000, set the allocation so the Copier trades half the size.

Fixed Percentage

Set --allocation (0–100) so each trade uses a fixed percentage of the Copier's balance.

---

What TokenBot Copies

Trade Type	Supported
Spot buys and sells	✅
Margin/leverage trades	✅
Perpetual futures	✅
Limit orders	✅
Market orders	✅
Stop-losses	✅
Take-profits	✅

---

Real-Time Under the Hood

TokenBot's automated engines run server-side and publish events over Redis; the GraphQL API fans those out to live subscribers over WebSockets (graphql-ws). If you build on the API, you can subscribe to streams like tradeSignal and orderbookUpdate for low-latency updates.

The scheduled engines run on a cadence:

• Trading engine — monitors positions and acts every ~15 minutes.

• Market-maker engine — runs a quoting cycle every ~5 minutes.

If you operate an engine directly, each ships an operator CLI — see Bot Operator CLIs →.

---

What If Something Goes Wrong?

Network issues

If TokenBot can't reach an exchange, it retries automatically. If a trade can't execute after retries, it's recorded so you can review it.

Insufficient balance

If a Copier account doesn't have enough funds, TokenBot skips that account for that trade. Other Copiers still execute.

Exchange maintenance

Exchanges sometimes go down for maintenance. The affected account simply skips that trade.

---

Security Recap

Question	Answer
How does TokenBot know it's me?	Every request is signed with your secp256k1 private key — no passwords.
Can TokenBot withdraw my money?	No. Your API keys don't have withdrawal permission.
Where are my exchange keys stored?	Locally encrypted on your machine (~/.tokenbot/keys.json) with keys add, or — only if you register an account for the bots with exchange add — encrypted at rest on our servers.
Can I revoke access?	Yes. Delete the API keys on your exchange and they stop working instantly.

---

Next Steps

Ready to set it up?

npm install -g tokenbot && tokenbot init

Or learn about which exchanges we support:

See supported exchanges →