Setups
A setup is a record an AI agent writes: what it expects, where it would get in, where it is wrong, where it would take profit, and until when. The server then follows the price and scores the setup on paper. No order is ever sent. The agent cannot set or change an outcome, so its decisions get a track record a person can trust (ADR-0059).
Setups are off until the operator sets CHARTGEN_SETUPS=1.
They run on Binance symbols and on US stocks and ETFs, and over the HTTP
transport, where a call has an owner. A headless agent
needs durable tokens for them: a setup belongs to
the owner its token resolves to, which with sign-in off is the OAuth client, so an agent whose
token does not outlive a restart loses sight of its setups until someone authorizes it again. The tools
are in the MCP reference. The web app’s
Setups tab lists them.
A setup
Section titled “A setup”{ "symbol": "BTCUSDT", "interval": "1h", "direction": "long", "thesis": "Why, in plain text.", "entry": { "low": 60000, "high": 60200 }, "invalidation": 59400, "targets": [61200, 62000], "expires_at": "2026-12-01T12:00:00Z", "drawings": [ { "tool": "horizontalStraightLine", "points": [{ "time": "2026-11-30T08:00:00Z", "snap": "low" }] } ]}- It must be able to be wrong. A setup without an
invalidationand anexpires_atis refused. The invalidation is below the entry zone of a long and above that of a short, and at least 42 bps of the price away from it (three times the assumed cost of getting in and out; 24 bps on a stock). - All or nothing. If anything is wrong, nothing is stored, and the error names each field with a hint.
- Drawings are the ones
generate_charttakes, checked by the same rules on the bars of the setup’s symbol and interval.
How it is scored
Section titled “How it is scored”The server moves the status from closed 1m bars: watching, then triggered when a bar
reaches the entry zone, then won at the first target, invalidated at the invalidation, or
expired. So a status can be up to a minute behind the price.
The result is in R: the move from the fill to the exit, in units of the distance from the fill to the invalidation, less an assumed 5 bps fee and 2 bps slippage on each side. A setup that was never filled scores 0.
A 1m bar does not say in which order it traded. Where a bar is ambiguous, the worse outcome for the agent counts:
| The bar reaches | Counts as |
|---|---|
| The invalidation and the target | Invalidated |
| The entry zone and the invalidation, while watching | Filled and invalidated: a loss |
| The entry zone and the target, while watching | Filled only; that bar cannot win |
| The invalidation, opening beyond it or never reaching the zone | Invalidated, never filled, 0 R |
Excursions
Section titled “Excursions”From the fill on, a setup also says how far the price went each way, for reviewing a trade after the fact. They are read with the same 1m bars and the same rule as the result:
mae_r: the furthest the price went against the position, in R from the fill. It is 0 or less:-0.5means half the risk.mfe_r: the furthest it went for the position, in R. It is 0 or more.mae_atandmfe_at: the open time (ms) of the 1m bar that set each, the first one where two went as far. They say whether the worst point came before or after the best one; they do not say on their own whether a break-even stop would have been hit, since the price can come back to the fill later without setting a new extreme.
They are measured from the fill price with the bars’ highs and lows, before costs, so a
setup that won at a target 2 R away has mfe_r 2 while its result_r is a little less. Where a
bar is ambiguous they follow the scorer: the bar that fills a setup counts against it but not for
it, a bar that reaches the invalidation counts as out at the stop (its open is the most it went
for the position), and nothing past the exit counts. So a setup stopped at its invalidation
has mae_r -1, or less if the price gapped through.
While a setup is filled they are the values so far. Before a fill they are null, and they stay null on a setup that is never filled. Setups filled before the server kept them have none.
Durations
Section titled “Durations”Durations are in bars of the setup’s own interval, the one it was created with (1h, 4h,
or a custom one such as 45m): the elapsed time over the interval’s length, to two places. A
month counts as 30 days. They are measured between the open times of the 1m bars involved, so
they move in steps of one minute.
bars_to_fill: from creation to the bar that filled it.bars_to_exit: from the fill to the exit. While filled, to the newest bar scored so far.bars_to_maeandbars_to_mfe: from the fill tomae_atandmfe_at.
All are null before a fill. bars_to_exit is also null on a setup that expired filled while
nobody scored it, since it has no exit.
How close an unfilled setup came
Section titled “How close an unfilled setup came”closest_approach_r is, while a setup is watching, the least distance between a bar’s high or
low and the entry zone, in R of the risk from the zone’s edge nearest the price to the
invalidation. 0.1 means the price came within a tenth of the planned risk. It is 0 once a bar
reaches the zone, so on a setup that expired or was cancelled unfilled it says how near it came.
It is to the entry zone in effect: when revised levels take effect, it starts again.
It is null before the first bar is scored, and on setups that were already being scored before
the server kept it.
Why a setup closed
Section titled “Why a setup closed”There is no separate exit reason: status says it. won is the first target, invalidated the
invalidation, expired the expiry and cancelled your cancel.
Shadow results
Section titled “Shadow results”A setup is scored all out at its first target. To compare ways of managing the exit without
committing to one, the server also scores every filled setup with three fixed exit variants
on the same 1m bars, under shadow_results
(ADR-0066). They are for comparison only:
status and result_r never change because of them, and you cannot choose or change them.
| Variant | Rule |
|---|---|
v1_half_t1_be | Half out at T1. The other half runs to T2 with its stop moved to break-even after costs, or to T1 where T1 is nearer the fill than that. With one target it runs until that stop or the expiry. |
v2_be_at_1r | All out at T1. Once price has gone +1R from the fill, the stop moves to break-even after costs. |
v3_time_stop | The setup as it is, but if T1 and the stop have not been reached by the close of the 12th bar of its interval after the fill bar (the 6th for 4h and longer), out at that close when it is below +0.5R. |
- Break-even after costs is the price where an exit scores 0 R with the assumed fee and slippage on both sides: a little above the fill for a long, a little below for a short.
- R for the +1R and +0.5R rules is measured from the fill with the bars’ highs, lows and
closes, before costs, as
mfe_ris. The bars of the interval are the ones every chart here uses: hours from the epoch, days from midnight UTC, weeks from Monday. - The same rules as the setup: the fill bar can stop a variant but cannot move its stop or win it; a bar that reaches a stop and a target counts the stop; a bar that opens past a stop is out at its open. A stop a variant moves counts from the next bar, so a bar that takes T1 or reaches +1R and then falls back to the fill does not stop it out. A cancel or the expiry closes every open variant at that bar’s open, as it does the setup.
- A variant can outlive the setup. v1’s other half is still in after the setup was closed at T1, and the server keeps scoring it until it is out or the setup’s expiry. That keeps the symbol’s feed watched, but the setup is closed: it does not count as open, toward the limit of open setups or of symbols.
Each variant has:
status:open,won(its last target),stopped(out at or through the invalidation, also when a gap went past a moved stop to it),breakeven(the moved stop was hit; its result is near 0 R, a little under after a gap through the stop or when v1’s stop is T1 because T1 is nearer the fill than the costs),timed_out,expiredorcancelled.result_r: each part’s R net of its own costs, weighted by its share. Null while open.stop: the stop in force from the next bar on.exits: each part closed,{price, fraction, bar_time}; v1 has two once both halves are out.exited_at: the open time of the 1m bar of the last exit.time_stop_at: v3 only, the time its time stop is judged; null once it was.
shadow_results is null before the fill, on a setup never filled, and on setups filled before
the server kept them.
tags labels a setup so that you can group your track record: strategy:breakout,
trigger:rsi-oversold, pattern:double-top-ee. Up to 10, each 1 to 64
characters of lowercase letters, digits and : - _ . /, starting with a letter or digit; a
tag given twice is kept once. list_setups with tags returns only
the setups that have all of them. Tags are not levels: revise_setup can change them after the
fill, and even after a setup closed, for labels such as review:r1 added in a review. On a
closed setup, or one being cancelled, a revision may change the tags only. The change goes to
the log like any other.
Changing a setup
Section titled “Changing a setup”Nothing is edited in place. revise_setup and cancel_setup need a reason, and each adds an
entry to the setup’s log with what it was and what it became. get_setup returns the whole log,
the server’s own status moves included.
- The thesis, drawings and tags change at once.
- New levels, and a cancel, count from the next 1m bar. The bar forming now still meets the
setup as it was, so a fill or a stop inside it stands. Levels not yet in effect are under
pending. - Once a setup is filled its levels are fixed.
- Cancelling a filled setup closes it at the next bar’s open and scores it.
What a setup was made with
Section titled “What a setup was made with”When you make a setup you can state three more things (ADR-0064):
features: what you measured, as a flat object of at most 16 short entries, for example{ "example_number": 1.5, "example_flag": true }.probability: your own estimate, from 0 to 1, that it reaches its first target.playbook_version: a short label for the rules you followed.
The server gives them no meaning. They are fixed once the setup is made: no tool changes
them, because a record that could be rewritten after the outcome is no record. If one was
wrong, cancel the setup and make a new one. Keeping a feature’s name meaning the same thing
from one setup to the next is yours to do; change playbook_version when it does not.
The market it was made in
Section titled “The market it was made in”The server adds three features of its own to every setup it makes
(ADR-0077), so that you can
group setups by the market they were made in without typing it yourself. They are read from
the symbol’s market context at that moment, in the
words get_market_context uses:
| Feature | Value |
|---|---|
ctx_trend_4h | up, down or mixed |
ctx_trend_1d | up, down or mixed |
ctx_fear_greed | extreme fear, fear, neutral, greed or extreme greed |
A feature the server could not read is unknown: always on a replay server, which has no
market context; on a symbol that is not trading; when the read failed or took longer than 10
seconds; and ctx_fear_greed on a symbol that is not on Binance, which has no Fear & Greed
index. The setup is made either way. Like your own features they are fixed once the setup is
made, and revisions do not change them.
The ctx_ prefix is the server’s. A setup whose features names one starting with
ctx_ is refused, so the server’s values are never mixed with yours. The three do not count
against your 16 features.
A decision not to trade is worth recording too. decision: "skip" stores it with a
direction and a thesis and no levels. The server scores it as if it had been taken, with the
same bracket for every skip: in at the next bar’s open, out one ATR(14) against it or two with
it. On a quiet chart, where one ATR is less than the least risk a setup may have (42 bps), the
stop is that far and the target twice that; bracket on the setup says which applied (atr or
floor; agent for a setup with your own levels). A skip has an expiry after 24 bars of the setup’s interval, at most 90 days. A skip cannot be
cancelled.
Limits
Section titled “Limits”Per owner: 20 open setups, 500 in total, open setups on 5 symbols, 50 revisions per setup (tags
alone on a closed setup do not count), 10 changes a minute, and 4 MiB for setups and their logs. Closed setups are kept; at a limit a new
one is refused and nothing old is dropped. list_setups returns the limits.
Your track record
Section titled “Your track record”get_track_record counts your closed setups: how many, how they ended, the total and mean
result in R, and your stated probability beside the share that won. You can filter by
symbol, direction, decision, playbook_version and the time a setup was made, and group by
one of playbook_version, one feature (the server’s ctx_ features included, such as
ctx_trend_4h), the probability in tenths, symbol or direction. The
reference has the fields.
It counts and judges nothing. Read it with care:
- A small group means little. Three wins of four is not a rate.
- Setups that are open at the same time, on the same market, for the same reason are one observation more than they are several.
- A result with
gap: truedoes not cover what the server missed, and a setup with no result is counted but not in the mean. - A setup that was cancelled, ran out or was invalidated before its entry was reached has a result of 0 R.
It is in
mean_rand in the observed share, and pulls both towards 0.enteredandmean_r_enteredcount only the setups whose entry was reached, andobserved_enteredis the share that won among those. shadowsputs the fixed exit variants side by side over the setups that traded, with those whose variant is still open counted apart. Compare each with its own canonical figures, not with the total: v1’s open positions are the runners after T1, so until they end its closed ones are mostly losers.- Skips are in it as well, scored with the server’s bracket. Filter with
decision.
Stock setups
Section titled “Stock setups”A setup can be made on a stock or ETF listed in the US, such as NVDA or SPY
(ADR-0070). It is scored with the same rules as a
Binance setup, with these differences:
- Bars. Yahoo has no live feed, so the server reads a stock’s 1m bars from Yahoo once a minute while the market is open, regular session only: 09:30 to 16:00 New York, 13:00 on an early close. Pre- and post-market trading does not count. A status moves after the price by 1 to 2 minutes of polling and settling, plus Yahoo’s own lag, which has not been measured yet. On Binance it is up to one minute.
- What it takes. Stocks and ETFs on Nasdaq, NYSE, NYSE American, NYSE Arca and Cboe BZX.
- An index such as
^GSPCcannot be traded: use an ETF that tracks it, such asSPY. - OTC stocks, other exchanges and Yahoo’s crypto, FX and futures are refused.
- An index such as
- Costs. 1 bps fee and 3 bps slippage per side, so the least risk is 24 bps. This assumes a liquid stock: a thinly traded one is scored better than it would fill.
- Expiry. A stock setup ends at the last 1m close at or before
expires_at.- An expiry on a Saturday ends at Friday’s close, not at Monday’s open after the weekend’s gap.
- An expiry on a holiday ends at the close before it.
- Gaps at the open.
- An open past the invalidation exits at that open, as on Binance.
- An open past the first target exits at that open too, which is the better price. A Binance setup exits at the target.
- Counting in bars. These count bars of the session grid, which starts at the open with the
session’s last bar shorter, not hours on the clock:
- a skip’s 24 bars, on a 1h chart (7 bars a session) about 3.4 sessions;
- the time stop of
v3_time_stop; bars_to_*.
- Splits and dividends.
- A split during a setup divides all its prices by the ratio, since Yahoo’s bars are adjusted from then on. R does not change.
- A dividend that goes ex while the position is open is paid to a long and by a short, in the result from its exit on.
- Both are logged as
adjustedand listed inadjustments. - If Yahoo sends a session’s first bars far from the last close (below 0.7 or above 1.4 times it) with no split, the server waits for the split for up to half an hour before it takes them as a real gap.
- Gaps in the data. A minute without a trade is not a bar, and nights, weekends and holidays
are not gaps. A read that fails is made again, and so does one whose setups could not be
stored. A past stretch Yahoo answered nothing for is a
gap. Only bars older than 29 days, a day short of Yahoo’s 1m history, after a long outage, are agap. - Holidays. The exchange calendar here lists NYSE holidays and early closes through 2028. A stock setup cannot expire later than that, a skip’s bracket included.
- ABNB and the like. A US stock whose ticker ends like a Binance quote asset (ABNB ends in BNB) is read from Binance, by charts and setups alike, so setups refuse it. The error says so.
- A symbol Yahoo stops answering. If it is delisted, or halted with no data, its setups end
as
expiredwithgap: truea whole session after their expiry: at 0 R if never filled, and with no result if filled.
Server alerts still run on Binance symbols only. A stock setup’s own status changes wake your agent as a Binance setup’s do.
When the server was away
Section titled “When the server was away”After a restart or a dropped feed the server reads the 1m bars a setup missed, up to 1000 of
them, and scores them in order. If it cannot, the log gets a gap entry that names the stretch
that was not scored, and the setup’s gap field is true from then on. Treat a result with
gap: true as incomplete.
If the operator takes your account off the server’s list, your setups are no longer scored. You
can still read them. One that runs out meanwhile is marked expired with gap: true: at 0 R if
it was never filled, and with no result (result_r: null) if it was, since no price was read.
Its open shadow results end the same way, as expired with no result.
A gap in bars after the setup closed, while only a shadow result was being scored, is in the
log, but leaves gap false: the setup’s own result covers all of its bars.
Being woken about a setup
Section titled “Being woken about a setup”A server alert can name a setup: setup_id,
with notify_agent: true. When the price it watches is reached, your agent’s receiver gets
the setup as it stands, with its status and levels before its thesis. The alert only
reports: it changes nothing on the setup, and the server alone moves a status. It needs
server alerts on and a receiver the operator configured for you. A replay server has no
alerts.
With such a receiver, the server also wakes your agent when it gives one of your take
setups a status (triggered, won, invalidated, expired). There is no flag for this
on the setup. Your own cancellation and everything on a skip setup wake nobody. All of
these are in your event log either way: after a time away, call
list_events with the cursor you
kept. The wake-up shows the setup as it is when it is sent, which can be later than what it
reports.
A take that goes 0.8 R against it wakes your agent once more, before the stop
(setup.near_stop, ADR-0072): at
the first 1m bar that takes mae_r to -0.8 or below while it stays open. The setup then shows
near_stop_at, and its log a near_stop entry. It is said once, however often the price comes
back; a bar that stops it out says so with its status instead. After the server was away, a
warning written together with the stop that followed it is logged and not sent: the stop’s
wake-up comes, the warning only in list_events.
A wake-up can also carry context, the symbol’s market when it is sent: price, trend on 4h
and 1d, funding, the long/short split and Fear & Greed, as
get_market_context answers it. It is absent
when it was not held from the last minute and could not be read within 5 seconds, or when the
symbol’s bars cannot be read, so do not rely on it being there. Whether a macro blackout is on is
not in it.
Replay
Section titled “Replay”A replay server answers the same tools from fixture bars, as of a time each call names. It is for evaluating an agent on a scenario that can be run again: the same calls give the same answers, byte for byte, on every run.
CHARTGEN_REPLAY_FIXTURES=tests/fixtures/replay chartgen --serve --port 9315A fixture is one JSON file per symbol, of 1m bars in order:
{ "symbol": "BTCUSDT", "bars": [[1767225600, 60000.0, 60024.0, 59976.0, 60000.0, 10.0]] }Each bar is [open time in unix seconds, open, high, low, close, volume]. The files in
tests/fixtures/replay/ are synthetic. chartgen replay-fixtures writes fixtures from real
Binance history; see Replay over real history, which also shows how to
keep a replay server private.
- Every call needs
as_of: unix seconds, unix ms or an ISO 8601 time. It is taken by the five setup tools and bygenerate_chart,inspect_chart,get_indicatorsandget_quotes. - Nothing after
as_ofis used. A 1m bar counts only if it had closed by then, and every other interval is built from those bars. The bar still forming atas_ofis not there. - Time only moves forward. The server has one clock for all tools and all callers. A call
with an
as_ofbefore the latest one the server has been sent is refused, whoever sent it. One process is one run: run two evaluations as two servers. - Everything it stores lives in memory: setups, and the OAuth clients that register with
it. A replay server opens no database file, not
chartgen.dbeither, and all of it is gone when the process ends. To run a scenario again, restart the server. Ids count per caller:setup-000001, and so on. - What is refused:
get_footprint,get_tpo,search_symbols, chart subscriptions, the alert tools, and the indicators that fetch a series of their own (funding rate, open interest, long/short ratio, fear and greed). get_quotesreturns the close of the newest closed 1m bar aslast, and its 24-hour fields from the 1m bars of the 24 hours beforeas_of.- A replay server is nothing else: it refuses to start with
--trade,--mcp,CHARTGEN_SERVER_ALERTS=1,CHARTGEN_SETUPS=1or a sign-in provider. On any other serveras_ofis refused.