anchor-demo / options trader bot / epics

Epics and use cases

What the options trader bot does, written as two epics, each made of use cases told step by step: who acts, what they see, what can go wrong at each step and where that leads. Every requirement is carried by steps, and only the steps name code. The tests listed under a step were run under a tracer, and the code a step names is the code those tests ran.

OB-1 a requirementconnect() code, opens the line on GitHubUC-1.2 a step that carries it

2epics
11use cases
54steps
40alternate paths
37requirements: 18 from the sources, 19 open questions
71steps and paths run by 46 tests
0holes in the closed-loop kit's 19 use case checks

EPIC-1 · epic

Trade one day of SPY 0DTE opening-range breakouts

Actor
Trader
Trigger
the trader starts the bot before or during a trading day
Before
TWS or IB Gateway runs with the API on PORT; the account has live SPY and US options data
Succeeds when
each breakout of the day is traded within the trader's limits, its exits held at IB, and logged as one row
At worst
no order or position of the bot's is left behind, and every trade it made is in the log
Why
the original script's purpose: the 15-minute opening range breakout on SPY 0DTE options, sized to a small balance

How the trader acts: runs python zdt_autopilot.py, with --live for a live account, and presses Ctrl+C to stop

How they see the result: the console's tagged lines ([SIGNAL], [FILLED], [TRADE CLOSED]) and trade_execution_log.csv

Steps, each a use case below

  1. The trader starts the bot, and it connects to the right kind of account. UC-1: Start the bot on the right account
  2. The bot reads the opening range and prints the two triggers. UC-2: Read the opening range
  3. The bot watches SPY until it breaks out past a trigger. UC-3: Watch SPY for a breakout
  4. The bot buys today's out-of-the-money option, sized to the balance. UC-4: Enter a trade on the signal
  5. IB holds the stop and the target until one fills, or the bot flattens before the close. UC-5: Exit the trade
  6. The bot logs the trade and decides whether to take another. UC-6: Log the trade and decide whether to go on
  7. The bot stops and leaves nothing of its own working or held. UC-7: Stop and leave nothing behind

Alternate paths

UC-1 · use case · EPIC-1 step 1

Start the bot on the right account

Actor
Trader
Trigger
python zdt_autopilot.py, or with --live
Before
TWS or IB Gateway is running with the API on PORT
Succeeds when
connected; the banner says PAPER or LIVE with the account ID, and [ACCOUNT] shows the balance
At worst
on any refusal nothing is sent to IB and the bot exits
Why
a bot that can trade real money has to know which account it is on before anything else

How the trader acts: runs the script, adding --live only for a live account

How they see the result: the banner's PAPER or LIVE and account ID, the [ACCOUNT] line, or a [REFUSED] line

Steps

  1. The bot checks the exit rules are possible before anything else.
    2 tests
  2. It refuses a live port unless --live was given.
    2 tests
  3. It connects and reads the account IDs; an account that is not a paper account needs --live.
    2 tests
  4. It prints PAPER or LIVE with the account ID.
    2 tests
  5. It reads the account's USD TotalCashBalance and its own budget, STARTING_BUDGET_USD before its first trade or the log's last EndingBalance after; [ACCOUNT] and [BUDGET].
    3 tests

Alternate paths

UC-2 · use case · EPIC-1 step 2

Read the opening range

Actor
Trader
Trigger
the bot has connected and read the balance
Before
the account is connected
Succeeds when
[ORB ESTABLISHED] shows today's first bar's high and low, and [ORB TRIGGERS] the two prices that signal
At worst
no trigger is printed unless it came from today's first bar
Why
the whole strategy is measured from this one bar

How the trader acts: starts the bot any time before the close; nothing else to do

How they see the result: [WAIT], then [ORB ESTABLISHED] and [ORB TRIGGERS]

Steps

  1. The bot reads today's session hours from IB's liquid hours for SPY.
    3 tests
  2. It waits, printing [WAIT], until the session's first 15-minute bar has closed.
    1 test
  3. It asks IB for the last two days of 15-minute bars, with UTC times.
    1 test
  4. It takes the bar that starts at the session's open, and prints the range and the two triggers.
    2 tests

Alternate paths

UC-3 · use case · EPIC-1 step 3

Watch SPY for a breakout

Actor
Trader
Trigger
the triggers are printed
Before
the opening range is known
Succeeds when
[SIGNAL] CALL or PUT with SPY's price
At worst
nothing is traded on a price that is not live
Why
a breakout past the range is the strategy's entry

How the trader acts: nothing: the bot watches by itself

How they see the result: a status line every second, then [SIGNAL]

Steps

  1. The bot asks for live data and waits for SPY's first live price.
    1 test
  2. Each second it reads SPY's last price and prints a status line.
    1 test
  3. It compares the price with the two triggers.
    2 tests
  4. SPY trades strictly above the CALL trigger or below the PUT trigger, and it prints [SIGNAL].
    2 tests

Alternate paths

UC-4 · use case · EPIC-1 step 4

Enter a trade on the signal

Actor
Trader
Trigger
[SIGNAL]
Before
a signal and the balance
Succeeds when
[FILLED] with the contracts held and their price
At worst
no order is sent for a contract IB does not know, at no live price, or beyond the balance
Why
the entry is where the money goes in

How the trader acts: nothing: the bot enters by itself

How they see the result: [CONTRACT], [ORDER] and [FILLED], or the [NO TRADE] or [NO FILL] reason

Steps

  1. The bot finds today's expiry in IB's option chain.
    1 test
  2. It picks the listed out-of-the-money strike nearest spot plus or minus 1.50 rounded to the dollar, a tie going to the nearer, and checks IB knows it; [CONTRACT].
    4 tests
  3. It reads the option's live bid and ask.
    1 test
  4. It sizes the order with the tier table from its budget, never from more than the account's cash; [ORDER].
    4 tests
  5. It buys with a limit at the ask and waits for the fill; [FILLED].
    1 test

Alternate paths

UC-5 · use case · EPIC-1 step 5

Exit the trade

Actor
Trader
Trigger
[FILLED]
Before
the bot holds the option
Succeeds when
the bot holds none of the option; the stop, the target or the flatten sold it
At worst
whatever happens, the stop and the target work at IB until the close
Why
the exit decides the trade, and a 0DTE option expires the same day

How the trader acts: nothing, or Ctrl+C to stop

How they see the result: [EXITS AT IB], a status line with the bid, then [TRADE CLOSED] with the reason

Steps

  1. The bot places the stop and the target at IB as one OCA pair, priced from the entry fill; [EXITS AT IB].
    1 test
  2. Each second while it holds the option it checks the connection and the clock, and prints the bid.
    1 test
  3. The stop or the target fills, and IB shrinks or cancels the other.
    2 tests

Alternate paths

UC-6 · use case · EPIC-1 step 6

Log the trade and decide whether to go on

Actor
Trader
Trigger
the bot holds none of the option
Before
the trade's fills
Succeeds when
one row with IB's net, and the bot is watching SPY again or stopped for the day
At worst
a closed trade always gets its row
Why
the log is the trader's record, and the breaker is the original's limit on a bad day

How the trader acts: nothing: the bot logs by itself

How they see the result: [TRADE CLOSED] with the net and the balance, the CSV row, then [REARMED] or [CIRCUIT BREAKER]

Steps

  1. The bot waits for IB's commission report on every fill.
    1 test
  2. It writes one row: time, direction, contracts, entry, exit, the net after IB's commissions, the ending balance.
    2 tests
  3. It counts the losses in a row.
    1 test
  4. It watches SPY again once SPY is back between the triggers.
    1 test

Alternate paths

UC-7 · use case · EPIC-1 step 7

Stop and leave nothing behind

Actor
Trader
Trigger
the flatten time, the breaker, an error, or Ctrl+C
Before
the orders this run placed
Succeeds when
no order of the bot's working, none of its options held, and the bot disconnected
At worst
the bot says what it could not close
Why
an unattended 0DTE position can expire, and anything else in the account is the trader's

How the trader acts: Ctrl+C, or nothing

How they see the result: [CLEANUP] lines, or none; [STILL OPEN] if something could not be closed

Steps

  1. On Ctrl+C, or when the day is done, the bot cancels each order it placed that is still working.
    1 test
  2. It sells at market what its own fills say it still holds.
    1 test
  3. It disconnects from TWS.
    2 tests
  4. It says what is still open, if anything is.
    1 test

Alternate paths

EPIC-2 · epic

Get the bot ready to trade real money

Actor
Trader
Trigger
the trader has the bot and wants it trading
Before
the bot as shipped: signals only
Succeeds when
the bot trades the trader's own exit rules on the live account, after a clean check and a paper run
At worst
no real order is sent before the trader adds --live
Why
the original arrived without its exits, and the bot cannot be run against a broker here

How the trader acts: edits STOP_LOSS_PCT and TAKE_PROFIT_PCT, runs on paper, adds --live

How they see the result: the test results, the light loop's report, the paper day's console and CSV

Steps, each a use case below

  1. The developer checks the bot without a broker. UC-8: Check the bot without a broker
  2. The trader sets the exit rules. UC-9: Set the exit rules
  3. The trader runs a day on the paper account and reads the log. UC-10: Run a day on the paper account
  4. The trader goes live. UC-11: Go live

Alternate paths

UC-8 · use case · EPIC-2 step 1

Check the bot without a broker

Actor
Developer
Trigger
the developer has changed the bot
Before
Python 3.10 or newer and pytest; ib_async's source for the API check
Succeeds when
every test passes, every planted defect is caught, and the light loop proves no fault
At worst
nothing reaches TWS or an account
Why
a trading bot's mistakes cost money, and the bot cannot be run against IB here

How the developer acts: runs py -m pytest tests, py tests/plant_check.py and the light loop

How they see the result: the pytest summary, the plant table, spec_check/REPORT.md

Steps

  1. The developer runs the tests: whole simulated trading days against an in-memory TWS; all pass.
  2. The API check reads ib_async's own source and finds every call, keyword and field the bot uses.
  3. The plant run breaks one guarded behaviour at a time in a copy, and a test fails each time.
  4. The light loop runs every repro against SPEC.md, and proves no fault.

Alternate paths

UC-9 · use case · EPIC-2 step 2

Set the exit rules

Actor
Trader
Trigger
the trader has decided a stop and a target
Before
the bot runs signals only
Succeeds when
the banner no longer says SIGNALS ONLY, and signals become orders
At worst
an impossible value stops the bot before it connects
Why
the original's exit rules were never received, and only the trader can choose them

How the trader acts: sets STOP_LOSS_PCT and TAKE_PROFIT_PCT near the top of the file

How they see the result: the banner without [SIGNALS ONLY], or [REFUSED]

Steps

  1. The trader sets STOP_LOSS_PCT and TAKE_PROFIT_PCT; TIME_STOP_PCT still does nothing.
    1 test
  2. The bot checks both values when it starts.
    1 test
  3. The banner drops SIGNALS ONLY, and a signal now sends an order.
    1 test

Alternate paths

UC-10 · use case · EPIC-2 step 3

Run a day on the paper account

Actor
Trader
Trigger
the trader wants to see the bot trade before any money is at stake
Before
TWS logged in to the paper account
Succeeds when
a day's console and trade_execution_log.csv, from IB's own fills and commissions
At worst
nothing touches a live account
Why
the tests cannot show how IB itself fills, prices and reports; a paper day is that check

How the trader acts: logs TWS in to paper on port 7497 and runs python zdt_autopilot.py

How they see the result: the console and the CSV

Steps

  1. The trader logs TWS in to the paper account with the API on port 7497.
    OB-1done by a person or by IB
  2. The trader runs the bot without --live; the banner says PAPER.
    1 test
  3. The bot trades the day as in EPIC-1.
    1 test
  4. The trader reads the console and trade_execution_log.csv.
    1 test

Alternate paths

UC-11 · use case · EPIC-2 step 4

Go live

Actor
Trader
Trigger
a clean paper day
Before
the exit rules set, TWS logged in to the live account
Succeeds when
the banner says LIVE with the account ID, and the bot trades the day
At worst
without --live, nothing is sent
Why
real money is the point, and only the trader can choose it

How the trader acts: logs TWS in to the live account and runs python zdt_autopilot.py --live

How they see the result: the banner's LIVE and account ID

Steps

  1. The trader logs TWS in to the live account, API on port 7496.
    OB-1done by a person or by IB
  2. The trader runs python zdt_autopilot.py --live.
    1 test
  3. The banner says LIVE with the account ID, and the bot trades the day.
    1 test

Alternate paths

Requirements

Each one is carried by the steps listed under it; none names code. The steps name the code.

From the sources

Open questions for the owner

Nobody wrote these down: finishing the bot needed them. Each is the bot's current answer, waiting for the owner's yes or a different one.