Orders & exits¶
Entering, sizing, flattening, and rebalancing positions.
Start with the topic guide for worked examples. Signatures below show the available arguments.
allocate_weights(longs: List[str], shorts: List[str], long_pct: float = 0.5, short_pct: float = 0.5) -> Dict[str, float]¶
Divide long_pct across the long list and short_pct across the short list, with shorts given negative weights. The defaults are 0.5 for each side; the two authored fractions must sum to 1. An empty side does not redistribute its share to the other side. Returns a weights dictionary without placing orders.
bottom_n(scores: Union[Dict[str, float], List[Tuple[str, float]]], n: int) -> List[str]¶
Read the lowest N values from a symbol-to-score mapping or a list of (symbol, score) pairs. Returns instrument names; it does not place orders. n is a count.
buy(qty_or_symbol, qty=None, symbol: Optional[str] = None) -> None¶
Submit an additional raw buy quantity. buy(10) uses the current instrument; buy('TCS', 10) selects it explicitly. Repeated calls can add exposure. Use long for a final position target instead.
check_stop(pct: float, symbol: Optional[str] = None) -> bool¶
pct is a fraction such as 0.02 for 2%. Checks the current position against the price and can request an exit; it is an action, unlike a read-only risk gate. Registered entry protection has its own bar-range checking. See protection.
close(qty=None, symbol: Optional[str] = None, side: Optional[str] = None) -> bool¶
With no qty, request flat holdings for the selected/current instrument. With qty, close that many units of its current holding. This is separate from reading close[0]. An optional side filters the side being closed. See orders.
entry(side: str, qty=None, *, size_pct=None, cash=None, risk_pct=None, stop=None, target=None, trail=None, trail_amount=None, stop_amount=None, target_amount=None, stop_price=None, target_price=None, hold=None, symbol: Optional[str] = None) -> bool¶
Choose side='long' or 'short' and exactly one sizing argument: positive qty in units, size_pct as an equity fraction, cash as a money amount, or risk_pct as a planned-loss fraction with a fixed percentage stop. 0.05 means 5% in fraction arguments.
stop, target and trail are fractions. stop_amount, target_amount and trail_amount are price distances frozen at submission and anchored to the owner's confirmed fill. stop_price and target_price are absolute decision snapshots. Choose one form per protection kind. hold is a positive whole bar count. Omitted symbol uses the current dispatch instrument. See fill and distance examples.
This requests a final signed target, so a repeated identical target is a no-op. Submission does not establish a confirmed fill. See order examples.
forecast(fn: Callable[[], float]) -> Callable[[], float]¶
Import from atom.library.forecast and decorate a per-instrument scalar function; do not place orders inside it. The universe's forecasts are sized jointly. This shape does not invoke manage(). See forecast portfolios.
forecast_sizing(*, forecast_cap: float = 20.0, vol_target: float = 0.2, idm=auto, idm_cap: float = 2.5)¶
Forecast weights are clipped forecast / 10 times vol_target / annualized instrument volatility times IDM. Defaults: cap 20, vol_target 0.20, idm='auto', idm_cap=2.5. Requires vol(symbol); optional cov(weights) returns annualized portfolio variance for auto diversification. Missing covariance uses IDM 1. See forecast portfolios.
long(qty=None, *, size_pct=None, cash=None, risk_pct=None, stop=None, target=None, trail=None, trail_amount=None, stop_amount=None, target_amount=None, stop_price=None, target_price=None, hold=None, symbol: Optional[str] = None) -> bool¶
Request the long direction with exactly one sizing argument: positive qty in units, size_pct as an equity fraction, cash as a money amount, or risk_pct as a planned-loss fraction with a fixed percentage stop. 0.05 means 5% in fraction arguments.
stop, target and trail are fractions. stop_amount, target_amount and trail_amount are price distances frozen at submission and anchored to the owner's confirmed fill. stop_price and target_price are absolute decision snapshots. Choose one form per protection kind. hold is a positive whole bar count. Omitted symbol uses the current dispatch instrument. See fill and distance examples.
This requests a final signed target, so a repeated identical target is a no-op. Submission does not establish a confirmed fill. See order examples.
rebalance(weights: Dict[str, float], *, client: Optional[Any] = None, bar: Optional[Any] = None, portfolio: Optional[Any] = None) -> None¶
weights maps exact instrument identifiers to signed equity fractions: 0.2 is long 20%, -0.2 is short 20%. Call inside a strategy function. In ordinary authoring, omit client, bar and portfolio; the run supplies them. A rebalance target is separate from confirmed execution.
rebalance_top(symbols, score_fn, n: int, gross: float = 0.95) -> dict¶
score_fn(symbol) returns a numeric score; higher wins. n is the maximum selected count and gross is a fraction (default 0.95). Selected available names share that gross equally. The -inf score excludes a name; if no scores remain, return {} without issuing a rebalance. The returned mapping is submitted target weights, not confirmed holdings. See ranking.
sell(qty_or_symbol, qty=None, symbol: Optional[str] = None) -> None¶
Submit an additional raw sell quantity. sell(10) uses the current instrument; sell('TCS', 10) selects it explicitly. Repeated calls can add short exposure or reduce longs. Use short/close when you intend a final target or exit.
short(qty=None, *, size_pct=None, cash=None, risk_pct=None, stop=None, target=None, trail=None, trail_amount=None, stop_amount=None, target_amount=None, stop_price=None, target_price=None, hold=None, symbol: Optional[str] = None) -> bool¶
Request the short direction with exactly one sizing argument: positive qty in units, size_pct as an equity fraction, cash as a money amount, or risk_pct as a planned-loss fraction with a fixed percentage stop. 0.05 means 5% in fraction arguments.
stop, target and trail are fractions. stop_amount, target_amount and trail_amount are price distances frozen at submission and anchored to the owner's confirmed fill. stop_price and target_price are absolute decision snapshots. Choose one form per protection kind. hold is a positive whole bar count. Omitted symbol uses the current dispatch instrument. See fill and distance examples.
This requests a final signed target, so a repeated identical target is a no-op. Submission does not establish a confirmed fill. See order examples.
target(longs: Optional[Sequence[str]] = None, shorts: Optional[Sequence[str]] = None, *, weights: Optional[Dict[str, float]] = None, by_group: Optional[str] = None, flat: bool = False) -> TargetBook¶
Import with from atom.library.book import target; this constructor is not automatically injected. It builds the desired book returned by book(). Explicit signed weights are used as authored. With longs/shorts lists, a single side divides full gross equally; both sides each divide half. flat=True or empty membership requests an empty book. by_group carries a grouping hint rather than an exposure cap. See target portfolios.
top_n(scores: Union[Dict[str, float], List[Tuple[str, float]]], n: int) -> List[str]¶
Read the highest N values from a symbol-to-score mapping or a list of (symbol, score) pairs. Returns instrument names; it does not place orders. n is a count, not a fraction of the list.