Lesson 3 of the course "Build your own arbitrage bot". You have chosen a type in lesson 2. Today you learn how the bot is organized and you get a one-page design.
Why stages?
Imagine you look for a lost key in a big house. You would not search every drawer with a magnifying glass. First you glance quickly at the table, the hook by the door and the coat pocket. Only if you find nothing there do you start opening drawers.
A bot works the same way. There are many markets and the prices change many times a second. Checking every possibility in full detail is too slow, so the bot first runs a fast, rough check on everything and then a slow, careful check on the few promising cases.
The stages
Stage 1: the screen. Look at only two numbers per market, the best bid and the best ask (lesson 1). This is very fast. The stage answers: "Does anything look interesting?" The output is a short list of candidates.
Stage 2: the fill simulation. For each candidate, look at the whole order book and walk through it as if you were buying and selling. A price quoted as "100.10" is only valid for a small amount. If you want to trade a thousand coins, you eat many offers, and your average price gets worse. This stage answers: "If I trade this now, how much money passes through, and what is the profit after fees?"
Stage 3: execution. Send the orders. In this course the bot works in paper mode: it pretends to trade and writes the result in a notebook (a ledger). You never risk money, but you learn exactly what a real bot would see.
Risk checks run through all three stages: a limit on how much money one trade may use, a stop when the paper balance falls too far, a pause when data looks broken.
prices -> stage 1 (screen) -> candidates -> stage 2 (walk the book) -> trade list -> stage 3 (execute / paper)
^
risk checks everywhere
Where each lesson fits
| Lessons | Stage |
|---|---|
| 4 | Stage 1, comparing best prices across venues |
| 5 to 8 | Stage 1 for cycles: rates as a graph and the algorithms that find cycles |
| 9 and 10 | Stage 2, order book and the real profit |
| 11 | Why stages 1 and 2 disagree with reality |
| 12 | Stage 3 in paper mode, plus risk limits |
A tiny numeric example of why stage 2 exists
The head-on design would be one function that finds a gap and immediately buys and sells. It is short, and it is how most first bots start. The example below shows what that design misses, and that is the reason to split the bot into stages.
Stage 1 sees: best ask 100.00 on exchange A, best bid 100.30 on exchange B. A gap of 0.30.
Stage 2 opens the books. On A, the ask side holds 2 coins at 100.00, then 3 coins at 100.20. On B, the bid side holds 1 coin at 100.30, then 5 coins at 99.90.
You want to trade 3 coins. On A you pay 2 × 100.00 + 1 × 100.20 = 300.20. On B you receive 1 × 100.30 + 2 × 99.90 = 300.10. You lose 0.10, even though stage 1 promised +0.30 per coin. Lessons 9 and 10 teach this walk.
What the bot's files look like
A simple layout is enough:
config.py: all numbers you may want to change (fees, minimum profit, trade size).prices.py: gets the best bid and ask, and later the order book.screen.py: stage 1.simulate.py: stage 2.paper.py: stage 3 and the ledger.risk.py: the limits.main.py: connects them in a loop.
You do not write all this today. You ask for a design and read it.
Let an AI agent draft the design
A vague request:
Design an arbitrage bot.
A request that gives structure and asks for something checkable:
I am building a paper-trading arbitrage bot in Python, type: cyclic arbitrage on one exchange (use the type I wrote in idea.md). It has three stages: a fast screen on best bid and ask, a fill simulation that walks the order book, and a paper executor with a ledger. Write DESIGN.md, one page: the files, what each file does in two sentences, which data goes between them, and the risk limits. Do not write any code yet. All numbers go in config.py.
Then review the page like an editor. Ask yourself: can I explain each file in one sentence? Does the order of stages match the picture above? If the agent invented a stage or file you do not understand, ask it to remove it.
Your exercise
- Ask the agent for DESIGN.md with the request above.
- Mark one file in the design that you could delete and the bot would still work (for example, a dashboard). Mark one you could not.
- Take the three-coin example above and write down the expected result of stage 2 on paper: 300.20 paid, 300.10 received, net −0.10. In lesson 9 you will check that your code gives the same number.
What comes next
Lesson 4 builds stage 1 for real: it compares the best prices of five exchanges and counts how many gaps survive the fees.