Trading
Place and cancel orders, close positions, set stop-loss and take-profit, change leverage.
The calls on this page need the trading:write scope. Prices and amounts are
decimal strings.
Real money. These calls send real orders to the exchange through the terminal, and there is no confirmation. To stop a program at once, switch the Local API off in the terminal.
Place an order
accepted = terminal.place_order(
12,
"binance:futures:BTCUSDT",
side="buy",
order_type="limit",
price="60000",
size="0.001",
client_key="bot-42",
)
print(accepted.key)| Argument | Meaning |
|---|---|
order_type | limit with a price, or market without one. type in TypeScript. |
size or notional | Exactly one: the amount in the base coin or in the quote currency. |
reduce_only, post_only | Optional, false by default. |
time_in_force | Optional: gtc, ioc, fok or post_only. |
Always pass client_key. A repeat with the same key returns the first answer
and places nothing, so a retry never places the order twice. The terminal
remembers the last 1000 keys.
Pass prices and sizes as strings. Python refuses a float.
Check the outcome
# accepted is the answer of place_order
orders = terminal.account_orders(12)
order = next((o for o in orders.data if o.key == accepted.key), None)
if order:
print(order.status, order.exchange_id, order.filled)The answer accepted means the terminal took the command. It does not mean
the exchange accepted the order or filled it. Read the outcome from the
account: the order appears there under its key.
To avoid polling, subscribe to account.orders before you place the order.
See Account.
Cancel an order
terminal.cancel_order(12, "binance:futures:BTCUSDT", "t-173029440000000001")
terminal.cancel_all(12, "binance:futures:BTCUSDT")The first call takes the terminal's key of the order or the exchange's id.
Send it after the order shows an exchange_id in the account. A cancel of a
pending order finds nothing on the exchange, and the order stays.
The second call cancels every order of the instrument. Trigger orders stay.
Close a position
terminal.close_position(12, "binance:futures:BTCUSDT")On futures the terminal sends a market order for the size of the position. On spot it cancels all orders of the instrument and closes the position in one command.
Set a stop-loss or a take-profit
stop_loss = terminal.place_trigger(
12, "binance:futures:BTCUSDT", kind="stop_loss", trigger_price="59000", client_key="sl-42"
)
print(stop_loss.key)kind is stop_loss or take_profit. Both are placed on the open position:
the terminal takes the side and the size from it.
Place a stop
stop = terminal.place_trigger(
12,
"binance:futures:BTCUSDT",
kind="stop",
side="sell",
notional="800",
trigger_price="59000",
rule="price_below_or_equal",
)
print(stop.key)A stop is an order of its own. It needs its own side and notional, the
amount in the quote currency. rule is optional: by default the stop is
above the market for a buy and below it for a sell.
Move a trigger
for trigger in terminal.account_orders(12).triggers:
print(trigger.id, trigger.client_id, trigger.trigger_price)
terminal.amend_trigger(12, "binance:futures:BTCUSDT", 42, kind="stop_loss", trigger_price="58500")A trigger is moved and cancelled by its numeric id from the account, not by
its key. Its client_id there is the key you got when you placed it.
The terminal replaces the trigger with a new one. Pass kind again, and
side for a stop.
Cancel a trigger
terminal.cancel_trigger(12, "binance:futures:BTCUSDT", 42)
terminal.cancel_all_triggers(12, "binance:futures:BTCUSDT")The second call cancels every trigger of the instrument. Ordinary orders stay.
Change the leverage
terminal.set_leverage(12, "binance:futures:BTCUSDT", leverage=20)
terminal.set_leverage(12, "binance:futures:BTCUSDT", mode="max")Leverage is for futures only. Pass either leverage, a whole number from 1,
or mode, which is max or smart.
Read the leverage
leverage = terminal.leverage(12, "binance:futures:BTCUSDT")
print(leverage.leverage, leverage.max_leverage, leverage.mode, leverage.margin_mode)This call needs the account:read scope. It answers 409 not_active until
the instrument was opened in the terminal or its leverage was set.
Change the margin mode
terminal.set_margin_mode(12, "binance:futures:BTCUSDT", "isolated")The mode is cross or isolated. The exchange refuses the change while a
position is open, and the answer accepted does not show that.
When a call fails
| What happens | What you get | What to do |
|---|---|---|
| The connection is disabled, read-only or has no credentials | 409 not_tradable | Use a trading connection |
| A wrong argument, or an order below the minimum of the exchange | 400 invalid_request | Fix the request |
| There is no open position to close or to protect | 400 invalid_request | Read the positions first |
| More than 10 trading commands a second, for the whole terminal | 429 rate_limited | Slow down, see Limits |
| The terminal is too busy to take the command | 503 unavailable | It was not sent. Send it again |
| The terminal has no trigger orders for this exchange | 501 unsupported | Nothing to retry |
What is not available
Trading on the Moscow Exchange (MOEX) is not available: every call for a
moex: instrument answers 501 unsupported.