How the engine works

This page is the technical description of Archon’s engine, for readers who want to know exactly what runs against their account. The code is platform/archon/engine.py (the planner, pure and without I/O) and platform/archon/app/trader.py (one cycle against Hyperliquid). Hosted and self-hosted accounts run the same two files.

The idea in one paragraph

The engine is a target-position planner. Each cycle it reads the account from Hyperliquid, reads the rule’s stance for each market from the same evaluation the platform shows, and computes the orders that move the account toward what the rule holds. It does not remember orders. Orders are immediate-or-cancel, so by the next cycle each one has filled, partly filled or died, and the next plan starts again from what Hyperliquid says is held. The venue is the state.

One cycle

1. Market metadata. Size precision and the market list are refreshed from Hyperliquid at most once an hour.
2. The account. Equity and open positions, read from Hyperliquid’s public info endpoint. For a unified account equity comes from the spot USDC balance; for a standard account, from the perpetuals account.
3. Mid prices for every market.
4. Transfers since the last cycle, from the account’s non-funding ledger: deposits, withdrawals, internal and sub-account transfers, spot USDC transfers on unified accounts, spot/perp class transfers on standard accounts, and vault deposits and withdrawals. Their net is passed to the planner so the halt’s peak moves with them.
5. The rule’s stance per market, from the strategy’s latest evaluation: long or flat, the reason, and the time of the candle it was decided on.
6. Plan. The pure function described below returns a list of orders, the updated book, and notes.
7. Send. Each order goes to Hyperliquid as an immediate-or-cancel limit. The result of each is written as a note in plain words.

Inputs to the planner

Input	What it is
Settings.markets	The markets the rule trades. Positions in any other market are ignored entirely
Settings.slots	How many equal slots the account is divided into. 0 means one per market
Settings.capital_usd	A cap on the equity sized from. 0 means the whole account
Settings.halt_drawdown_pct	The halt threshold, 30 by default. 0 disables it
Settings.stop_entries	Pause: exits run, nothing opens
Settings.close_all	Flatten and open nothing
Signal per market	long, ready (enough history and a fresh candle) and a reason
View	Equity and positions as Hyperliquid reports them
Book	What must survive a restart: the halt’s peak and, if halted, when and at what drawdown

The order of decisions

The planner decides in a fixed order. Earlier steps take precedence over later ones.

1. Peak and halt. The peak becomes max(previous peak + net transfers, equity). If the account is not already halted and equity / peak - 1 is at or below minus the halt threshold, the book records a halt.
2. Shorts. A short in a traded market is closed with a reduce-only buy. The rules only ever hold longs, so a short there was not opened by them.
3. Halt or close-all. If either applies, every long in a traded market is sold, reduce-only, and the plan ends there. Nothing opens.
4. Exits. A held long whose market is ready and flat is sold. A held long with no fresh signal is kept, with a note.
5. Pause. If new positions are paused, the plan ends here.
6. Entries. Markets that are ready, long and not held are filled into free slots in name order, each at min(budget / slots, cash left), where budget is equity or the capital cap, whichever is smaller, and cash left is the budget minus the value of held positions. If a position would be under the venue minimum of 10 USDC, the planner stops and writes UNDERSIZED.

Sizing

A new position takes one slot, sized from equity at the moment it opens, and keeps that size until the rule exits it. Positions are never topped up or trimmed while held. Because each entry is limited by the cash left, the sum of positions never exceeds the account at 1x: gross exposure is at most 1x, or the Turbo level you chose.

This is the same construction as the research’s portfolio.slot_curve. The engine’s tests drive a simulated account over the frozen candle capture and require the planner to reproduce slot_curve exactly at 2, 4 and 6 slots over 4,794 bars.

With one slot per market, each position is equity / 32 for the frozen rule’s 32 markets. Hyperliquid refuses orders under 10 USDC, so that needs an account of at least 320 USDC. Fewer slots need less.

The halt

• Measured from a persisted peak. The peak is stored in the account’s book after every cycle, so a restart cannot lower it.
• Adjusted for transfers. A deposit raises the peak by the amount deposited and a withdrawal lowers it by the amount withdrawn, so moving money is never read as a gain or a loss.
• Sticky. Once halted, the engine sells what it manages and opens nothing until a person re-arms it. Re-arming sets the peak to the equity at that moment and clears the halt.
• First. The halt is decided before anything else in the cycle, including exits and pauses.

Readiness and stale data

Each market’s signal carries the time of the candle it was decided on. If that candle is more than 2.5 candle-lengths old (10 hours on 4-hour candles), the signal is not ready. A market without a ready signal is held as it is: an open position stays open and a flat market does not open. That market does not block the others, the halt, or close-all.

A market with too little history to evaluate has no signal at all, and is treated the same way.

Orders

• Immediate-or-cancel limits priced 1% through the mid, so each order fills at the best available prices up to that limit, or dies. Nothing is left resting on the book.
• Entries are sized in USDC and converted to coins at the mid, rounded down to the market’s size precision. If rounding takes it under the venue minimum, it is skipped with a note.
• Exits are sized in coins, the full position, and sent reduce-only, so an exit can never open a position the other way.
• Leverage is set to cross on a market before every entry, at 1x or the Turbo level you chose, whatever it was before.
• Builder code. On mainnet only, and only after the account owner has approved Archon’s builder for at least the configured fee, orders carry Archon’s builder code. Otherwise none is attached and the fee is zero.

Restarts

Nothing the engine needs to continue is held only in memory:

• What is held comes from Hyperliquid each cycle.
• What the rule wants comes from the evaluation of closed candles.
• The halt’s peak and halt state come from the stored book.
• The point up to which transfers have been counted is stored with it.

So a restart neither sells a trend the rule still holds nor swaps which markets fill the slots. A cycle that dies halfway leaves nothing to clean up: the next one reads the venue and carries on.

What the engine does not do

• It does not go short, exceed the leverage you chose, or rebalance a held position.
• It does not touch positions in markets outside its rule.
• It does not place resting orders, stop orders or take-profit orders.
• It does not move money: no withdrawals, transfers or deposits.
• It does not act between cycles. If the engine is not running, nothing watches the account.

Messages

Every note the planner and the order sender can write is listed, with its cause and what to do, in Troubleshooting.