Documentation

Trading with agents

An agent is one strategy, run as an isolated experiment, with its own money and its own limits. Code owns every number and every exit; a strategy only ever proposes.

• 1. What an agent is
• 2. The strategy directory
• 3. The order gate
• 4. The exit loop
• 5. Isolation by lots
• 6. Autonomy and approvals
• 7. The agent lifecycle
• 8. Disarm and Flatten all
• 9. Models and spend
• 10. TradingAgents and the Python runtime
• 11. Honest limits
• 12. Checklists

1. What an agent is

You create an agent in a wizard, and these are the decisions it asks for. Every one of them is a limit the rest of the system enforces.

Strategy and parameters

One entry from the directory below, with typed, ranged parameters and presets.

Book

paper — the local paper account, fed by live Robinhood quotes — or live, the Robinhood Agentic account you selected. Both books exist at once and every order carries its own.

Allocation

The agent's capital: the most it may have in positions at once. It never touches the rest of the account. Its free cash is the allocation minus its open lots at cost, and the gate refuses an entry that would exceed it.

Universe

The names it may buy — it can always sell what it holds. Fixed symbols (up to 50), your local watchlist, a watchlist in your Robinhood account read on every run, or the scanner: the most-gapped names of Robinhood's daily-gainers scan that pass your gap, price and volume filters.

Model

The provider, an optional model override, the deep/quick pair for TradingAgents, a base URL for a compatible server, and the agent's own daily and monthly spend caps on top of the app-wide ones.

Cadence and window

Every N seconds, every N-minute bar, daily at a time, or a list of times — inside a session window in Eastern time, with an optional flatten before the close. Nothing is planned outside the window; open lots stay protected by the exit loop regardless.

Risk

Max position as a percentage of the allocation (25 % by default), max open positions (4), orders per day (20), a daily loss limit in dollars (0 = off), max drawdown as a percentage of the allocation (0 = off), a PDT opt-out, and a run timeout (900 seconds). Every entry is checked against these at the gate; exits are never capped. A breach pauses the agent, and its open lots stay protected until you flatten or resume it.

Autonomy

auto executes inside the caps without asking, live included. propose queues every entry in Approvals for your tap. Protective exits never wait for approval either way.

Every plan, step, order, fill, exit and pause is a row on the agent's page. Its card shows a status light, the book, the allocation, today's and total P&L, open lots and the last event.

2. The strategy directory

Whatever the strategy, it returns a plan: intents (enter with a size and code-owned levels, exit a lot or every lot of a symbol, or hold), notes, a per-symbol status for its page, and memory for its next run. The levels belong to the lot from the fill onwards; a later run may tighten them, and the exit loop is what enforces them.

3. The order gate

The gate is the only code in TICKERSMITH allowed to place an order. Every order — an agent's or yours — becomes a proposal it evaluates, in this order:

1. Armed — the kill switch is off. Agents only; exits pass while disarmed.
2. Schema, account and book — the order is well formed and belongs somewhere.
3. Allowlist — for an agent buy, the symbol is inside its resolved universe.
4. Held quantity — for an agent sell, these are its own lots.
5. Cash floor — the buy does not spend into the money you keep aside.
6. Session and breaker.
7. App-wide orders per day, position percentage and drawdown.
8. The agent's own capital, position percentage, open positions, orders per day and daily loss.
9. Global orders per day and daily loss.
10. In-flight duplicate — this order is not already on its way.
11. Limit sanity — a limit price is not more than 5 % from the quote.
12. Extended hours and the PDT guard.

An agent breaching its daily loss limit is paused. Breaching the global daily loss limit disarms the gate, halting every agent. The app-wide caps live in Settings → Order gate.

A refusal is never silent: it is a row in the gate log with its reason, and it appears on the agent's timeline.

4. The exit loop

This is the safety floor of the whole system, and it has no model in it.

Every 3 seconds — 5 while any live lot is open — the exit loop takes every open lot of every agent that is not stopped, fetches one quote call per book, updates each lot's high-water mark, and checks the lot's levels and the session's flatten time. A hit becomes a market sell through the gate with an exit flag, which skips the caps and the armed check, but never the in-flight guard.

It runs while agents are paused, and while the gate is disarmed. It does not wait for an approval, a model, or you. If one lot's check fails that is one error line on that agent's timeline — never a stopped loop.

What it enforces: the hard stop, the target, the move to breakeven, any trail, and the flatten before the close. What it cannot do is beat a gap or a fast move: it sends a market order after the level is crossed, so the fill can be worse than the stop. See the risks you are taking.

5. Isolation by lots

Agents cannot interfere with each other or with you, because ownership is tracked per lot. An agent may only sell shares it bought. Your own sell is limited to shares no agent owns — for an agent's position the app offers Flatten instead.

Shares that vanish from the book outside the app — sold in the Robinhood app, say — mark the lot orphaned at the next reconciliation, which runs at startup and every 15 minutes. Nothing is ever invented to make the books balance.

6. Autonomy and approvals

An agent set to auto places orders inside its caps on its own, live included. An agent set to propose puts every entry in Approvals and waits for you. Approving one runs it through the gate again, with current prices and current caps, so an approval you leave sitting cannot execute something the limits no longer allow.

Propose-only is the right setting for an agent's first live week. It costs you nothing except having to be there.

7. The agent lifecycle

One task runs per agent, and its state is always one of these:

Created → Running

You start it.

Running → Paused

You pause it, or it pauses itself: its daily loss limit, its max drawdown, a model spend cap, or an order nobody can account for. The reason is on its card.

Running → Stopped

You stop it.

Running → Errored

Five failed runs in a row. Resume puts it back to Running.

Running → Halted

You disarmed the gate. Arming it resumes the agent.

Every transition is stored with its reason and written to the timeline. At startup, running and halted agents resume; paused, stopped and errored ones stay as they are.

A single run is: a run row, then the context (universe resolved, data prefetched, lots and the day's stats loaded), then the strategy's plan under the run timeout with its steps streamed as they happen, then the plan applied — lot levels first, then each intent as a proposal with an idempotency key, so a crash and a resume cannot double an order. The run keeps its summary, its model calls and cost, and its duration, and an equity snapshot follows.

8. Disarm and Flatten all

Disarm in the top bar is the kill switch. Every agent halts and no agent entry goes out until you arm the gate again. What keeps working:

• Stops, targets and the close flatten keep firing for every open lot.
• Your own orders still go out, after an extra confirmation.
• Flatten all sells every agent's open lots at market.

Disarming is not the same as stopping. A halted agent resumes when you re-arm; a stopped agent does not. And neither one abandons an open position — that is what the exit loop is for.

9. Models and spend

Each agent names its own model. For typed questions, every provider answers with a probability for each option under a JSON schema, and code derives the same structure whichever model answered — so a confidence threshold means the same thing across providers. A missing or malformed answer fails the call, which means no new entry. It never means a stranded position.

Jev answers typed probability questions only, which serves the breakout's optional gates and the Model analyst, but not TradingAgents, which needs a text model. Claude, OpenAI, Gemini and any OpenAI-compatible server serve every strategy.

What it costs:

• Rule strategies: nothing.
• Jev: $0.042 per million input tokens, output free — a fraction of a cent per decision, roughly a cent a day.
• Model analyst on a general model: cents per pass.
• TradingAgents: tens of cents to a few dollars per symbol, depending on the deep model and the number of debate rounds.

Every call is booked in a ledger against the agent and the run that made it, priced at the provider's configured rates. A call whose estimate would cross a cap — the app-wide one or the agent's own — is refused before it is sent, and an agent that hits its cap is paused with the reason on its card. There is a notification at 80 % of the month. Keys live in the Keychain, one per provider.

10. TradingAgents and the Python runtime

TradingAgents is a research project by TauricResearch: an LLM desk where several agents argue their way to a position. It is the most interesting strategy here and the most expensive, slowest and least predictable one.

It needs Python, which the app installs for you from Settings → Strategies & runtime → Install: a pinned, checksum-verified uv, CPython 3.12, a virtual environment, and TradingAgents 0.5.2 from its tagged source archive. Every step streams to the settings card, and an agent that needs Python cannot start until the health check passes. Remove deletes the environment and cache; past results stay.

Per symbol, per run, the pipeline is:

1. Analysts — market, social, news and fundamentals analysts each write a report from live data.
2. Researchers — a bull and a bear debate; a research manager rules.
3. Trader — proposes a position.
4. Risk — aggressive, neutral and conservative analysts debate.
5. Portfolio manager — issues the decision and a rating.

You watch it happen on the agent's page as a pipeline stepper, each stage's report expandable. The decision becomes an intent: Buy enters at the target weight, Overweight at half of it — both capped by the agent's max position and diffed against what it already holds. Sell and Underweight exit a held symbol. Hold, or a sell with nothing held, does nothing. Anything else — a Review, an unreadable answer — only proposes, with a note.

A run takes minutes per symbol and fetches its own network data inside the Python process. The run timeout, 15 minutes by default, marks the run and moves on. Your model keys never touch the disk: each run receives them through its environment.

11. Honest limits

• Exits are app-side. The loop checks quotes every few seconds and sends market orders, so a fast move can fill past a stop. Paper fills use the live bid and ask, which is kinder than a real fast market.
• Order status is best-effort. Robinhood's order payload was mapped from its schema at runtime; anything the tracker cannot read is treated as unknown, polled, and then pauses the agent. Watch your first live orders closely.
• The PDT guard is conservative. It counts same-day round trips per book over five business days, blocks agent buys under $25,000 equity, never blocks sells, and can be switched off. Check your account type's rules at Robinhood.
• TradingAgents is slow and costly — minutes and many model calls per symbol.
• Nothing runs when the app is closed. No entries and no exits. The Mac must be awake during your agents' session windows.
• Long only, stocks only. No shorting, no options, and no Level 2 or time-and-sales data, because the broker connection does not expose it.
• Apple silicon only, and builds are not yet notarized, so macOS asks before the first launch and there is no in-app updater.
• News feeds are free and unofficial, so any of them can change or close without notice, and reader views are best-effort.

12. Checklists

Your first paper agent

1. Robinhood connected for quotes; one model provider working, if the strategy needs one.
2. New agent: a daily rule strategy — Donchian, say — paper, a small allocation, three symbols, daily cadence. Start it, then Run now.
3. Watch the run and its steps appear on the agent's page; proposals go submitted → executed; lots appear on the card, on the page, and in the Trades positions table with the owner column.
4. Pause the agent and move a lot's stop above the market: the exit loop still sells it. This is the check worth doing yourself.
5. Disarm: the card says halted, a manual buy asks for confirmation, Flatten sells the rest. Re-arm and the agent resumes.
6. Set an agent to propose-only and approve one entry in Approvals.

Your first live dollar

Do this with real money before you do anything bigger with it. One dollar is enough to find out whether the whole path works.

1. Armed, the live book, the Agentic account selected. A Model analyst agent, live, capital $20, max position 10 %, 2 orders per day, one liquid fractional symbol, autonomy propose.
2. Approve one $1 buy in Approvals, and watch the order be polled to filled with its real quantity and price, becoming a lot with levels.
3. Set the stop above the market. A market sell is submitted, fills, and the lot closes with its realized P&L — which then syncs to your web account.
4. Disarm with an open lot: no entry goes out, the agent is halted, the stop still fires. Check that Flatten works.
5. Confirm the Orders card shows every transition and that the gate log has no failed rows.
6. Repeat once with autonomy auto.