Balances, positions and settings

These operations tell you what an account holds and how its markets are configured. They work the same way for real and paper accounts, and every one needs your API key and the accountId.

To read or change	Use
Asset balances	List wallets
Open derivative positions	List open positions
Margin per margin group	List margin states
Everything about one market	Get market account state
Leverage	Get market leverage, Set market leverage
Position mode	Get market position mode, Set market position mode
Fees, funding, deposits and other postings	List account transactions

Every list on this page is paged. Omit cursor for the first page and send each nextCursor back with the same query until it is null, even if you usually get everything in one page.

Balances

List wallets returns one entry per asset, and per wallet where the host keeps several:

{ "accountId": "acc_123" }

{
  "items": [
    { "id": null, "name": null, "asset": "USDT", "totalBalance": "10250.40", "availableBalance": "8710.15" },
    { "id": null, "name": null, "asset": "BTC", "totalBalance": "0.150", "availableBalance": "0.150" }
  ],
  "nextCursor": null
}

totalBalance is everything the wallet holds; availableBalance is what is free to use. id and name are null when the host has a single unnamed wallet per asset.

Positions

List open positions returns one entry per derivative market with an open position. Every entry has both a long and a short leg, so the same shape covers hedged and netted positions:

{
  "items": [
    {
      "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" },
      "long": { "size": "0.250", "entryPrice": "61250.5" },
      "short": { "size": "0", "entryPrice": null },
      "mode": "Netting"
    }
  ],
  "nextCursor": null
}

Sizes are in native contracts, not base units. Convert with the market’s contractDetails; see Instruments.
A leg with no exposure has size "0". In Hedging mode both legs can be open at once.
entryPrice and mode are null when the host does not report them.

Margin

List margin states returns the account’s margin per margin group: the collateral asset, total collateral value, initial and maintenance margin, and accountMarginRatio when the host reports it.

{
  "items": [
    {
      "baseCollateralAsset": "USDT",
      "totalCollateralValue": "10250.40",
      "totalInitialMargin": "1531.26",
      "totalMaintenanceMargin": "76.56",
      "accountMarginRatio": "0.0075"
    }
  ],
  "nextCursor": null
}

One market at a glance

Get market account state gathers what matters for one market into a single read. The result’s type depends on the market:

{
  "accountId": "acc_123",
  "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" }
}

Derivative
Spot
SpotMargin

Leverage setting, collateral and the position:

{
  "data": {
    "type": "Derivative",
    "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" },
    "currentLeverageSetting": { "type": "Leveraged", "leverage": "10" },
    "collateral": { "valueAsset": "USDT", "total": "10250.40", "available": "8710.15" },
    "position": {
      "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" },
      "long": { "size": "0.250", "entryPrice": "61250.5" },
      "short": { "size": "0", "entryPrice": null },
      "mode": "Netting"
    }
  }
}

The available base and quote balances:

{
  "data": {
    "type": "Spot",
    "instrument": { "type": "Spot", "base": "BTC", "quote": "USDT" },
    "base": { "available": "0.150" },
    "quote": { "available": "8710.15" }
  }
}

A spot market whose leverage is a market-level setting. It is returned only when the market’s settings.leverage is non-null; spot margin that a host offers only per order is returned as Spot.

{
  "data": {
    "type": "SpotMargin",
    "instrument": { "type": "Spot", "base": "BTC", "quote": "USDT" },
    "currentLeverageSetting": { "type": "Leveraged", "leverage": "3" },
    "collateral": { "valueAsset": "USDT", "total": "10250.40", "available": "8710.15" },
    "base": { "available": "0.150" },
    "quote": { "available": "8710.15" }
  }
}

Leverage

Leverage is a setting on a market, never a field on an order. Whether you can read or change it depends on two levels:

The host’s capabilities.marketSettings.getMarketLeverage and setMarketLeverage must not be NotSupported.
The market’s settings.leverage (from List host markets) must be non-null. Inside it, get says whether you can read it, and setEffectScope is null when it cannot be set.

{ "min": "1", "max": "100", "step": "0.01", "get": true, "setEffectScope": { "type": "Market" } }

Read it

Get market leverage returns one of three settings:

`type`	Meaning
`Leveraged`	Leverage is on, at `leverage`.
`Disabled`	The market has a leverage control and it is off for this account, so orders are not leveraged.
`Unknown`	The host cannot report the setting truthfully. `message` says why.

Disabled is different from a null settings.leverage, which means the market has no leverage control at all.

Set it

Set market leverage takes a value on the market’s grid: between min and max inclusive, and exactly min plus a whole number of steps. With the example above, 12.34 is valid, 12.345 is not. When min equals max, that single value is the only one accepted. Plurex does not round an off-grid value; it rejects it with 422 Rejected.

{
  "accountId": "acc_123",
  "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" },
  "leverage": "10"
}

The response is the resulting setting. Setting the same value again is safe.

Check setEffectScope before you set. Market changes only this market; MarketGroup changes a host-defined group of markets; Account changes every market on the account. After a wider change, read the setting again on every market you trade instead of assuming the old values still hold.

Position mode

Position mode decides whether a market holds long and short exposure separately (Hedging) or as one net position (Netting). The market’s settings.positionMode lists the modes it accepts in values, whether you can read the mode (get), and the blast radius of a change (setEffectScope, null when it cannot be set). The host’s marketSettings.getMarketPositionMode and setMarketPositionMode capabilities must also allow it.

{
  "accountId": "acc_123",
  "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" },
  "mode": "Hedging"
}

Set market position mode returns the resulting mode and is safe to repeat with the same value. Position mode and an order’s positionEffect are independent. Whether you may send positionEffect (Open or Close) is decided only by the order type’s supportsPositionEffect flag on the market, never by the position mode. Read each flag on its own.

Transactions

List account transactions returns the account’s balance postings: trading fees, funding payments, interest, deposits, withdrawals and so on. Check the host’s accountTransactions.listTransactions capability first; a host without transaction history returns 422 NotSupported.

{ "accountId": "acc_123" }

{
  "items": [
    {
      "id": "txn_40213",
      "effectiveAt": "2026-10-25T08:00:00Z",
      "amount": { "asset": "USDT", "value": "-1.27" },
      "type": "FundingPayment",
      "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" },
      "orderId": null,
      "fillId": null,
      "positionId": null,
      "groupId": null,
      "nativeType": "SETTLEMENT",
      "description": null
    }
  ],
  "nextCursor": "eyJwIjoyfQ"
}

How to read a posting:

amount is signed from your side: positive increases the balance, negative decreases it. A fee you pay is negative; a deposit is positive.
type classifies the posting: TradingFee, FundingPayment, BorrowInterest, Financing, LiquidationFee, Settlement, Rebate, Deposit, Withdrawal, Transfer, Conversion, Adjustment or Other. nativeType keeps the host’s own label. The host’s supportedTransactionTypes lists the types it reports. Treat a type you do not recognise as Other.
Links to an instrument, order, fill or position are present only when the host reports them reliably; otherwise they are null.
groupId links postings that come from one host record, such as the legs of a conversion and its fee, when the host reports it.
id is stable: it never changes and is the same ID the transaction stream sends.
effectiveAt is when the posting took effect.

Results come in the order the listTransactions capability’s defaultOrdering states, Chronological or ReverseChronological, across all pages.

Reconcile postings

Because IDs are stable, deduplicate by id. To stay complete:

Combine history with the transaction stream where subscribeToAccountTransactions is supported: connect, read history, then add streamed postings you do not have.
After a disconnect, or on each polling pass, re-read recent history back past the newest posting you already hold, and add any IDs you have not seen. Overlap with what you already hold instead of stopping at the first known ID, so a posting that appears late is still picked up.
Do not rebuild a ledger from wallet balances, fills or orders. Postings are the record of what changed a balance.

Instruments: native contract sizes and canonical symbols.
Host capabilities: market settings and transaction capabilities.
Order rules: positionEffect, reduceOnly and the other order flags.
Stream account updates: live order and transaction events.

Get started

Concepts

Capabilities

Trading guides

Paper trading

Web app

Balances, positions and settings

Balances

Positions

Margin

One market at a glance

Leverage

Read it

Set it

Position mode

Transactions

Reconcile postings

​Balances

​Positions

​Margin

​One market at a glance

​Leverage

​Read it

​Set it

​Position mode

​Transactions

​Reconcile postings

​Related

Balances

Positions

Margin

One market at a glance

Leverage

Read it

Set it

Position mode

Transactions

Reconcile postings

Related