size_position_by_risk
Size a position by risk · read-only, idempotent ·
scopes: read
Turns "risk 1% of equity, stop 2% below" into a size in the base coin, rounded down to the venue step and capped by every limit (this agent's, the person's and TradeHub's). Reads equity, mark and contract rules itself: no need for get_my_account_balances or get_perp_contract_rules first. Use before every preview_perp_order. Not an order: nothing is sent. Inputs: symbol, stop_loss (USD) or stop_pct with side, risk_pct or risk_usd (default: the most allowed), venue, entry_price (default: mark), leverage. Next: preview_perp_order with the returned size_base, stop_loss and leverage.
Call it
MCP tools/call
{"name": "size_position_by_risk", "arguments": {"symbol": "BTC"}}REST
POST /v1/sizing
{"symbol": "BTC"}Inputs
| Name | Meaning (* required) |
|---|---|
symbol * | Base coin, e.g. BTC |
stop_loss | Stop-loss price, USD per coin; below entry for a long, above for a short. Or give stop_pct and side instead |
stop_pct | Stop distance from entry as a fraction (0.02 = 2%), instead of stop_loss; needs side |
side | buy = long, sell = short; needed with stop_pct |
venue | Venue: sandbox, hyperliquid, okx, bybit or binance. Omitted: the agent's only venue, else hyperliquid, else your only connected venue, else sandbox |
entry_price | Planned entry, USD per coin; omitted: the mark |
risk_pct | Loss at stop as a fraction of equity (0.01 = 1%); omitted with risk_usd also omitted: the largest your limits allow |
risk_usd | Loss at stop in USD (instead of risk_pct) |
notional_usd | Or the position's value in USD ("buy $200 worth"), instead of risk_pct / risk_usd; still capped by the risk limits |
leverage | Leverage for the margin estimate, e.g. 5 |
Returns
| Field | Meaning and unit |
|---|---|
venue | Venue name |
symbol | Base coin |
side | buy (long) or sell (short), from the stop's side of entry |
entry_price | Entry used, USD per coin (the mark when not given) |
stop_loss | Stop-loss used, USD per coin |
size_base | Suggested size, in the base coin (e.g. BTC), not USD, rounded down to the venue's size step; pass it to preview_perp_order as size_base |
notional_usd | size_base x entry, USD |
risk_usd | Loss if the stop fills, USD |
risk_pct_of_equity | risk_usd / equity, as a fraction |
margin_usd | Margin needed at the given leverage, USD |
leverage | Leverage assumed |
equity_usd | Equity used for the calculation (the venue's book), USD |
capped_by | Which limit made the size smaller than asked, if any |
within_limits | False if even the capped size cannot pass (e.g. below the venue minimum) |
Rejections: error codes, each with what to do.