Trading tools
Five tools prepare a trade and three resolve it. Read Placing trades first for the flow, sizing and symbols.
Every prepare_* tool returns the same card:
| Output | |
|---|---|
preparedActionId | Pass it to the tool that executes or declines |
actionType | What was prepared |
expiresAt | One hour after it was prepared |
executionMode | confirm-every-trade or pre-authorized |
nextStep | What the agent should do next, in words |
summary | coin, side, size, orderType, estimatedPrice, notionalUsd, marginUsd, leverage, liquidationPrice, reduceOnly, and take profit and stop loss as prices and as percents |
Every prepare_* tool also accepts an optional idempotencyKey (string, up to 128 characters). Reusing a key returns the same prepared trade.
prepare_open_order
Validates a new order and stores it. Nothing is sent to Hyperliquid.
Scope: orders:create
| Input | Type | |
|---|---|---|
coin | string | Required. Exact symbol: BTC, xyz:GOLD |
side | buy or sell | Required. buy is long, sell is short |
marginUsd | number | The dollars put in, as margin: $20 at 5x is marginUsd: 20, leverage: 5. Give this or size, not both |
size | string | Units of the asset as a plain decimal, such as "0.29". Not dollars. Give this or marginUsd, not both |
orderType | market, limit, stop_market, stop_limit or take_profit | Required |
leverage | integer, 1 to 50 | Required. Isolated margin, no default |
price | string | Required for limit and stop_limit |
triggerPrice | string | Required for stop_market, stop_limit and take_profit |
slippage | number, 0 to 0.1 | Default 0.03, which is 3% |
reduceOnly | boolean | Optional |
takeProfitPrice / stopLossPrice | string | Optional trigger prices |
takeProfitPct / stopLossPct | number | Optional, as a percent of margin. stopLossPct: 35 closes at −35% |
With marginUsd, Orus reads the price and computes the size, rounded down so the order never needs more margin than given. When the market's smallest order needs more margin at that leverage, Orus raises the leverage to the smallest whole number that fits. It never goes above the market maximum, nor above your max leverage on an autonomous connection. The card then shows the leverage asked for in leverageRaisedFrom. A reduce-only order takes size only.
prepare_close_position
Validates a close against the live position.
Scope: positions:close
| Input | Type | |
|---|---|---|
coin | string | Required |
size | string | Optional. Omit to close the whole position |
slippage | number, 0 to 0.1 | Optional |
Returns no_position when there is nothing open in that market.
prepare_cancel_order
Validates cancelling one resting order.
Scope: orders:cancel
| Input | Type | |
|---|---|---|
coin | string | Required |
orderId | integer | Required. From get_open_orders |
prepare_tpsl_update
Sets or replaces take profit and stop loss on an open position. Validated against the live liquidation price.
Scope: tpsl:write
| Input | Type | |
|---|---|---|
coin | string | Required |
takeProfitPrice / stopLossPrice | string | Optional trigger prices |
takeProfitPct / stopLossPct | number | Optional, as a percent of margin |
prepare_remove_tpsl
Removes one trigger from an open position.
Scope: tpsl:write
| Input | Type | |
|---|---|---|
coin | string | Required |
type | take_profit or stop_loss | Required |
confirm_prepared_action
Executes a prepared trade. Autonomous connections only. Orus checks your signed limits and today's cap, then places the order. On a manual connection it returns approval_required.
Scope: orders:create, whatever the action type
| Input | Type | |
|---|---|---|
preparedActionId | string | Required |
| Output | |
|---|---|
status | executed or failed |
orderRef | Reference of the placed order |
error | Why it failed, when it did |
warning | Set when the order executed with a problem, for example a take profit leg that failed. The agent must pass it on |
Calling it again for the same trade returns the first result.
approve_prepared_action
The human path for manual connections. It runs when you select Approve on a trade card. Orus lists this tool only to clients that show its cards and keep the tool away from the model, so an agent cannot call it.
Scope: orders:create · Input and output: same as confirm_prepared_action
decline_prepared_action
Cancels a prepared trade so it can no longer be executed.
Scope: orders:create
| Input | Type | |
|---|---|---|
preparedActionId | string | Required |
