Placing trades

A trade is never one call. The agent prepares it, then it is executed, and who executes depends on the execution mode.

Prepare, then execute

Prepare

The agent calls a prepare_* tool. Orus validates the request against the live market and your account, stores it, and returns a preparedActionId with a summary: market, side, size, estimated price, notional, margin, leverage, liquidation price, and take profit and stop loss if set.

Nothing has been sent to Hyperliquid yet. The result also carries executionMode and a nextStep line that tells the agent what to do next.

Execute

Manual. You select Approve on the trade card.
Autonomous. The agent calls confirm_prepared_action in the same turn. Orus checks your signed limits, then places the order.

Either side can cancel with decline_prepared_action.

A prepared trade expires after 1 hour. Executing the same one twice returns the first result, it does not place a second order.

Symbols

Crypto on the main Hyperliquid exchange uses a plain ticker: BTC, ETH, SOL, HYPE.

Stocks, commodities, indices and FX carry an exchange prefix: xyz:NVDA, xyz:GOLD, xyz:BRENTOIL. A bare NVDA or GOLD is not a valid symbol.

When unsure, the agent should call get_supported_assets once and use the name it returns.

Size, margin and leverage

size is in units of the asset, not dollars: "0.001" means 0.001 ETH.

notional = margin × leverage
size     = notional ÷ price

When you say "$20 of NVDA at 5x", the $20 is margin. The notional is $100, and the size is 100 divided by the price.

Leverage is required on every new order, from 1 to 50 and no higher than the market's own maximum. There is no default.
Margin is always isolated. A loss is capped at the margin of that position.
The minimum is on notional, about $10. $1 of margin at 15x is $15 of notional and is valid. The exact figure per market is minNotionalUsd in get_market_snapshot.
Slippage on market orders defaults to 3% and cannot exceed 10%.

An order that breaks one of these is rejected at the prepare step with risk_rejected.

Order types

`orderType`	Needs
`market`	Nothing extra
`limit`	`price`
`stop_market`	`triggerPrice`
`stop_limit`	`triggerPrice` and `price`
`take_profit`	`triggerPrice`

Take profit and stop loss

Pass them with the entry on prepare_open_order, or set them later with prepare_tpsl_update. Give each one as a price or as a percent, not both.

As a price: takeProfitPrice, stopLossPrice.
As a percent of margin, the same convention as the Farao app: takeProfitPct, stopLossPct. A stop "at −35%" is stopLossPct: 35. At 10x that is a 3.5% move in price. Orus works out the trigger price.

Rules:

A stop loss beyond the liquidation price is rejected.
A trigger on the wrong side of the current price is rejected.
Take profit and stop loss attach only when the entry fills at once. A limit order that would rest on the book is rejected if it carries them. Place it alone, then set them after it fills.
stop_market, stop_limit and take_profit entries cannot carry them. Open the position first.

If the entry fills but a take profit or stop loss leg fails, the result has status: "executed" and a warning. The agent must tell you.

Display currency

Results that contain money include a display field with the currency you chose in the Farao app. When it is EUR, the agent shows amounts in euros using display.usdToEur. This is presentation only. Every input, minimum and limit stays in USD.

Retries

Pass an idempotencyKey to a prepare_* tool to make a retry safe. The same key returns the same prepared trade instead of creating a second one.