Trade with leverage

Check that an account at an exchange is set up the way trdrs trades it, set the leverage and the margin mode on an instrument, and see what an order would cost in margin before you send it. Use this page when your trading program trades perpetuals at a provider that keeps leverage per instrument. Leverage is a setting some providers keep per instrument. Futures don’t have one, because a contract’s leverage is fixed by its margin, so the leverage routes refuse an account without the setting. By the end you know whether an account can trade, what leverage an instrument uses, and what margin an order needs.

Before you start

The same routes work on a paper account a venue issued on a provider’s contract, which takes the provider’s own leverage tiers and margin modes, with PROVIDER=paper. Paper accounts on provider contracts describes those accounts. The examples trade HYPERLIQUID:BTC on a Hyperliquid testnet account connected in the sandbox trading app, with PROVIDER=hyperliquid and the account’s number in ACCOUNT. The TypeScript SDK isn’t published, so call the routes over HTTP, as the curl examples do. The TypeScript examples show the same calls through the SDK’s client, with provider and account set.

Check the account’s mode

Exchanges let a trader choose how an account holds positions and margin: one-way or hedge positions, the collateral mode, the account type and the margin mode. Each provider supports some of those setups in trdrs. trdrs reads the account’s choice every time it reads the account. It never changes the position mode, the collateral mode or the account type: the trader changes those at the provider. The margin mode changes through Set margin mode, below. The account’s mode is accountMode on the account snapshot and on every account stream frame. It’s null on accounts whose provider has no mode to check. When the mode isn’t one trdrs trades, or trdrs couldn’t read it, accountMode carries a refusal with a code, params naming the provider, the setting, the value the provider reported and the values trdrs trades, and an English message. Because params lists the supported values, your screen can tell the trader exactly what to change at the provider, in a message chosen by code, without a list of its own. A refusal with instrument set to null covers the whole account. One that names an instrument covers only that instrument. Either way, new orders, exits, closes and flattens are refused with 422 and the same code, while cancels keep working. Get what the account may do states the same refusals for each action before you send anything, so a ticket can disable what would be refused.

Know which accounts have leverage

Read capabilities.symbolConfig on the account snapshot, or capabilities.symbolLeverage on a row of List accounts. When it’s true, the account has per-instrument leverage and the steps below apply. Use capabilities to decide what to show: the engine checks every call again and refuses what the account can’t do. Positions show the same difference. leverage, margin and liquidationPrice on a position are what the provider reports, and they’re null where it reports none, such as leverage on futures. Show a dash for null, never a made-up 1. On the paper book, the account’s risk policy states them. leverage is the instrument’s: the leverage set on a perpetual its provider’s tiers margin, or notional over initial margin for one margined at a fixed rate. margin is the initial margin the position requires, in the account’s currency. liquidationPrice is the price at which the policy would start closing the position, every other price held where it is: where the account’s equity reaches the stop-out level, or a floor that flattens the account, whichever comes first. It’s null where it can’t be stated exactly, such as on a ticket that shares its instrument with another.

Read the settings from the account frame

The account snapshot and every account stream frame carry margin on an account with the setting: one entry for every instrument the account holds a position in or a working order on, and for every instrument it saved a setting for, each with its leverage, marginMode, maxLeverage, marginModes, marginModeScope and the provider whose margin terms it trades by, plus accountModes, the one mode each provider that sets its margin mode across the account holds there. A ticket shows the leverage and the margin mode from the frame it already holds, with no request on open, and a change of either arrives as the next frame. Decide whether the trader may change the mode now from the same frame: a change is held while a position or a working order sits within its reach, the instrument’s own with marginModeScope instrument, and every instrument of that provider on the account with account; the engine judges the change again when it is sent. An instrument with no entry trades at its starting setting, which Get leverage and margin mode answers, as the next step reads it.

Read an instrument's leverage

Get leverage and margin mode reads one instrument’s setting. It’s configuration, not trading, so a risk lock doesn’t block it.

curl "$TRDRS_API_BASE_URL/api/trading/symbol-config?provider=$PROVIDER&account=$ACCOUNT&instrument=HYPERLIQUID:BTC" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY"

const { config } = await client.trading.getLeverageAndMarginMode({ provider, account, instrument: 'HYPERLIQUID:BTC' })

{
  "config": {
    "leverage": 10,
    "marginMode": "cross",
    "maxLeverage": 40,
    "marginModes": ["cross", "isolated"],
    "marginModeScope": "instrument",
    "marginModeChange": { "allowed": true }
  }
}

marginMode is cross or isolated, as the provider reports it, and marginModes lists the modes the provider offers on the instrument. maxLeverage is the highest leverage the instrument allows, so use it as the top of your leverage control; it’s null when the provider states none. marginModeScope says what one change of margin mode reaches: instrument for this instrument alone, account where the provider holds one mode for every instrument it margins on the account. marginModeChange says whether the trader can change the mode now, and when not, why: unsupported, single_mode or exposure_open. config is null when the provider has no setting for this instrument, which is an answer, not an error.On a paper account a venue issued, the venue’s own limits narrow the provider’s: maxLeverage is the lower of the provider’s highest leverage on the instrument and the venue’s cap for it, and marginModes lists the modes the provider offers and the venue allows. Paper accounts on provider contracts shows where a venue states them. A venue’s backend reads the same answer for one of its traders with its Venue key: the key needs trader:trade and the request names the trader in x-trdrs-trader, as Route your traders’ orders shows. With only trader:read, the backend reads the margin entries on the trader’s account snapshot instead.

Set the leverage

Set leverage takes the instrument and a positive leverage.

curl -X PUT "$TRDRS_API_BASE_URL/api/trading/symbol-config?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instrument": "HYPERLIQUID:BTC", "leverage": 10 }'

await client.trading.setLeverage({ provider, account, instrument: 'HYPERLIQUID:BTC', leverage: 10 })

The response is { "ok": true }. Setting the leverage leaves the margin mode as it is, so don’t send marginMode. Where a provider sets leverage and margin mode in one action, trdrs reads the instrument’s current margin mode first and sends it back unchanged. If it can’t read it, nothing changes and the call answers 422. On the paper book, a Hyperliquid perpetual’s leverage can be raised while a position is held, as Hyperliquid allows, with no collateral moved; lowering it waits until the position is closed.

Change the margin mode

Set margin mode moves the instrument between cross and isolated, keeping its leverage. When marginModeScope is account, the change reaches every instrument the provider margins on the account, so say so before the trader confirms.

curl -X PUT "$TRDRS_API_BASE_URL/api/trading/margin-mode?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instrument": "HYPERLIQUID:BTC", "marginMode": "isolated" }'

await client.trading.setMarginMode({ provider, account, instrument: 'HYPERLIQUID:BTC', marginMode: 'isolated' })

The response is { "ok": true }. Where the provider states that a change needs no position or working order within its reach, as Binance does, the change is refused with 409 before it is sent, because the provider would have to move that margin. On the paper book it is refused while money is still owed there or the account is being liquidated. Any other provider, as Hyperliquid and Bybit are, is sent the change whatever the account holds, and a refusal comes back as 422 in the provider’s own words. Asking for the mode already set changes nothing.On the paper book, an order on an isolated instrument moves its margin from the account’s cross margin, as its provider does. On Hyperliquid, the unrealized profit of cross positions can fund it, and the cross balance can fall below zero while that profit backs it. On Bybit, only the cross balance can fund it. An order the cross margin can’t fund is refused with collateral_insufficient.On the paper book, only a write that raises the collateral an account or an isolated scope must hold can be refused for it. A cancel, and a replacement that lowers what an order reserves, are made even when the account’s free collateral is already negative, as Hyperliquid checks leverage only upon opening a position and Bybit takes an order that can only reduce a position whatever margin is available.

Price the order's margin before you send it

Preview order margin says what margin an order would need. It only reads: nothing is placed, so it takes no clientOrderId, and a risk lock doesn’t block it.

curl -X POST "$TRDRS_API_BASE_URL/api/trading/margin-preview?provider=$PROVIDER&account=$ACCOUNT" \
  -H "Authorization: Bearer $TRDRS_TRADING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instrument": "HYPERLIQUID:BTC", "side": "buy", "qty": 0.01, "orderType": "market" }'

const margin = await client.trading.previewOrderMargin({
  provider,
  account,
  instrument: 'HYPERLIQUID:BTC',
  side: 'buy',
  qty: 0.01,
  orderType: 'market',
})

Three fields decide how you show the answer:

Field	What it means
`marginRequired`	The margin, in `currency`. `null` when it’s unknown: say so instead of showing zero.
`estimate`	`false` when the provider computed the figure itself. `true` otherwise, so label it an estimate.
`sufficient`	Whether the account can cover it. `false` means block the order. `null` means there’s no verdict.

On the paper book, including a Demo, the preview gives the verdict the order will get: marginRequired is the collateral the order needs, and sufficient says whether the account’s free collateral covers it. It’s still an estimate, because prices and free collateral can move before the order arrives. If they have, the order is refused with collateral_insufficient, whose params give the amount required and the amount available.

Trade a Demo perpetual on the house’s tiers

A Demo trades each perpetual on its provider’s own leverage tiers where the provider publishes them to anyone. Where a provider shows its tiers only to a signed-in account, as Binance does today, the Demo margins that perpetual by the house’s tiers instead. They’re trdrs’s own terms, not the provider’s, and they’re the same for every such perpetual:

Position notional, in USDT	Most leverage	Initial margin	Maintenance margin
From 0	20x	5%	2.5%
From 100,000	10x	10%	5%, less 2,500
From 500,000	5x	20%	10%, less 27,500
From 1,000,000	2x	50%	25%, less 177,500
From 5,000,000	1x	100%	50%, less 1,427,500

A position’s tier is the one its whole notional reaches, valued at the mark price. Its initial margin is the notional divided by the leverage you set, and never less than the tier’s rate. Its maintenance margin is the tier’s rate of the notional, less the amount shown, so the requirement doesn’t jump at a tier’s edge. The routes on this page work on these perpetuals as they do on any other. maxLeverage is 20, marginModes lists cross and isolated, and marginModeScope is instrument. You can raise the leverage while a position is held. An order reserves its initial margin at the leverage you set, and the account stops out when its equity falls to the maintenance margin of everything it holds. Each fill pays the house’s fee, 0.020% to make and 0.055% to take, and each position pays the funding rate its provider publishes for each funding time, a long paying a positive rate on the mark price.

When a call is refused

Route	Status	What it means	What to do
Read, set	`400`	The instrument is missing or invalid, its asset class can’t be traded here, or the account has no leverage setting.	Check `capabilities.symbolConfig` first.
Set	`400`	`leverage` is missing or not positive, or the body carries `marginMode`.	Send only `instrument` and a positive `leverage`.
Set	`409`	On the paper book, a working order sits within the change’s reach, money is still owed there or the account is being liquidated, or a position is held and the change is not a raise its provider allows on a held position.	Cancel the orders or wait for the money to post or the liquidation to end; with a position held, raise the leverage only where the provider allows it, or close the position first.
Set	`422`	The provider refused, in its own words and code, or trdrs couldn’t read the margin mode it has to send back.	Show the reason, and try again later.
Set margin mode	`400`	`marginMode` isn’t `cross` or `isolated`, or the provider offers no change of margin mode.	Read `marginModeChange` first.
Set margin mode	`409`	A position or a working order sits within the change’s reach at a provider that states that rule, or on the paper book money is still owed there or the account is being liquidated.	Close the position and cancel the orders, or wait for the money to post or the liquidation to end, then try again.
Set margin mode	`422`	The instrument trades in one mode only, the provider refused, in its own words, or trdrs couldn’t read what the change needs.	Show the reason.
Preview	`400`	The instrument, side, quantity or order type is invalid, or the account can’t trade this asset class. The body carries a `code` for the asset class case.	Fix the request.

Test it end to end

On a testnet account in the sandbox, such as one at Hyperliquid:

Read the snapshot and confirm accountMode has no refusal.
Read the leverage for HYPERLIQUID:BTC, set it to a different value below maxLeverage, and read it again.
With no position or order on it, set the margin mode to the other one in marginModes, read it again, and set it back.
Preview a market buy, and check your screen labels the figure an estimate when estimate is true.
Set the leverage back.

Next steps

Place your first order

Send an order with its bracket, then confirm and close it.

Track fills and P&L

Read what the account made, after the fact.

Conventions

Learn how the API writes times, quantities and unknown values.

Start here

Trading

Before you start

Check the account’s mode

Know which accounts have leverage

Read the settings from the account frame

Trade a Demo perpetual on the house’s tiers

When a call is refused

Test it end to end

Next steps

Place your first order

Track fills and P&L

Conventions

​Before you start

​Check the account’s mode

​Know which accounts have leverage

​Read the settings from the account frame

​Trade a Demo perpetual on the house’s tiers

​When a call is refused

​Test it end to end

​Next steps

Place your first order

Track fills and P&L

Conventions

Before you start

Check the account’s mode

Know which accounts have leverage

Read the settings from the account frame

Trade a Demo perpetual on the house’s tiers

When a call is refused

Test it end to end

Next steps