How to write a specification for a trading bot

The single largest driver of cost and disappointment in a bot project is an imprecise specification. The good news is that a sufficient one is two or three pages, and the act of writing it is the most valuable unpaid work you can do.

The questions a spec has to answer

Universe. Which instruments, and how is the list determined? A fixed list, or a rule — top N by turnover, above a liquidity threshold, excluding recent listings? How often is it recomputed?

Entry. The exact condition. Not the idea. Every parameter named with a default and an allowed range. What disqualifies a signal that otherwise matches. What happens if two signals fire on the same instrument, or on correlated ones, in the same bar.

Sizing. How is quantity computed? From the stop distance, from equity, from a fixed notional? What is the maximum? What happens when the computed size is below the venue minimum — skip, or round up? (The correct answer is skip.)

Entry mechanics. Market or limit? If limit, at what offset, and how long does it live? What if it partially fills? What if it does not fill at all?

Exits. Stop level, computed how. Targets — one or several, and what fraction each. Trailing, and from what point. Time-based exit? What takes precedence when two exit conditions trigger together?

Risk limits. Max concurrent positions. Max exposure total and per group. Daily loss limit — realised only, or including unrealised? Drawdown stop. What happens when a limit is hit: stop new entries, or flatten?

Operations. What must you be alerted about? What can you change without a redeploy? Who can start and stop it? What does the bot do on restart if a position is already open?

The edge cases that get missed

This list exists because each item has cost someone real money:

• A position is already open when the bot starts. Adopt it, close it, or refuse to start?
• The venue rejects the stop after the entry filled. Retry, close the position, or alert?
• An exit signal fires while the entry order is still resting.
• The instrument is delisted or halted while you hold it.
• Funding settles mid-position — does it count toward the daily loss limit?
• Two strategies want opposite positions on the same symbol.
• The signal fires during a data gap you have not noticed yet.
• Equity changed enough between signal and order that the size is now wrong.

Write the acceptance criteria too

How will both sides know the bot is correct? Not “it makes money” — that is not a software criterion. Testable statements:

1. Given this historical bar sequence, the bot produces exactly these signals.
2. On a forced partial fill, the remainder is cancelled and the bracket matches the filled quantity.
3. On a forced disconnect with an open position, the bot reconciles before placing anything new.
4. When the daily loss limit is breached, no new entries occur until the next session.
5. The kill switch flattens all positions within N seconds.

These become the testnet drill list. They are also the thing that makes a dispute resolvable, which benefits both sides.

What not to put in

• Implementation choices. Which language, which library, which database. Say what it must do; let the developer decide how, unless you have a real constraint.
• Expected returns. Not a software requirement, and it cannot be accepted against. See why nobody honest guarantees profit.
• Aspirational features. “And later maybe machine learning.” Either it is in scope or it is not; half-specified future features distort the architecture and the price.

The shortcut, if you are stuck

Write down what you do manually, in order, as if instructing someone to do it for you while you are away for a month. Then go through it and mark every place you wrote a word like “strong”, “good”, “usually” or “if it looks right”.

Each of those marks is a decision you have been making without noticing. Turning them into numbers is the specification, and it is also the part that improves how you trade whether or not you build the bot.