> For the complete documentation index, see [llms.txt](https://docs.tokenbot.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tokenbot.com/home/03-how-it-works.md). # 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 ```bash 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` registers an exchange account with TokenBot so the automated engines can trade for you. These credentials are stored encrypted in AWS Secrets Manager. **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. ```bash tokenbot strategy add --name "My Main" --exchange-account-id ``` ### Step 4: Add Copiers and Link Them A **Copier** is an account that follows a Strategy. Create one and link it: ```bash tokenbot copier add --strategy --exchange-account-id --allocation 50 tokenbot link --strategy --copier ``` 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: ```bash 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. *** ## 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`), or — only if you register an account for the bots — encrypted in AWS Secrets Manager. | | Can I revoke access? | Yes. Delete the API keys on your exchange and they stop working instantly. | *** ## Next Steps Ready to set it up? ```bash npm install -g tokenbot && tokenbot init ``` Or learn about which exchanges we support: [See supported exchanges →](https://github.com/tokenbot-org/tokenbot-docs/blob/main/help-center/supported-exchanges/README.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tokenbot.com/home/03-how-it-works.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.