Skip to content

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.

{
"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 invalidation and an expires_at is 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_chart takes, checked by the same rules on the bars of the setup’s symbol and interval.

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 reachesCounts as
The invalidation and the targetInvalidated
The entry zone and the invalidation, while watchingFilled and invalidated: a loss
The entry zone and the target, while watchingFilled only; that bar cannot win
The invalidation, opening beyond it or never reaching the zoneInvalidated, never filled, 0 R

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.5 means half the risk.
  • mfe_r: the furthest it went for the position, in R. It is 0 or more.
  • mae_at and mfe_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 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_mae and bars_to_mfe: from the fill to mae_at and mfe_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.

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.

There is no separate exit reason: status says it. won is the first target, invalidated the invalidation, expired the expiry and cancelled your cancel.

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.

VariantRule
v1_half_t1_beHalf 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_1rAll out at T1. Once price has gone +1R from the fill, the stop moves to break-even after costs.
v3_time_stopThe 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_r is. 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, expired or cancelled.
  • 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.

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.

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 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:

FeatureValue
ctx_trend_4hup, down or mixed
ctx_trend_1dup, down or mixed
ctx_fear_greedextreme 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.

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.

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: true does 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_r and in the observed share, and pulls both towards 0. entered and mean_r_entered count only the setups whose entry was reached, and observed_entered is the share that won among those.
  • shadows puts 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.

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 ^GSPC cannot be traded: use an ETF that tracks it, such as SPY.
    • OTC stocks, other exchanges and Yahoo’s crypto, FX and futures are refused.
  • 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 adjusted and listed in adjustments.
    • 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 a gap.
  • 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 expired with gap: true a 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.

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.

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.

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.

Terminal window
CHARTGEN_REPLAY_FIXTURES=tests/fixtures/replay chartgen --serve --port 9315

A 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 by generate_chart, inspect_chart, get_indicators and get_quotes.
  • Nothing after as_of is 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 at as_of is not there.
  • Time only moves forward. The server has one clock for all tools and all callers. A call with an as_of before 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.db either, 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_quotes returns the close of the newest closed 1m bar as last, and its 24-hour fields from the 1m bars of the 24 hours before as_of.
  • A replay server is nothing else: it refuses to start with --trade, --mcp, CHARTGEN_SERVER_ALERTS=1, CHARTGEN_SETUPS=1 or a sign-in provider. On any other server as_of is refused.