> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plurex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Balances, positions and settings

> Read an account's balances, positions and margin, set leverage and position mode safely, and reconcile balance postings.

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](https://docs.plurex.io/api-reference/platform/hosts/list-wallets.md) |
| Open derivative positions | [List open positions](https://docs.plurex.io/api-reference/platform/hosts/list-positions.md) |
| Margin per margin group | [List margin states](https://docs.plurex.io/api-reference/platform/hosts/list-margin-states.md) |
| Everything about one market | [Get market account state](https://docs.plurex.io/api-reference/platform/hosts/get-market-state.md) |
| Leverage | [Get market leverage](https://docs.plurex.io/api-reference/platform/hosts/get-leverage.md), [Set market leverage](https://docs.plurex.io/api-reference/platform/hosts/set-leverage.md) |
| Position mode | [Get market position mode](https://docs.plurex.io/api-reference/platform/hosts/get-position-mode.md), [Set market position mode](https://docs.plurex.io/api-reference/platform/hosts/set-position-mode.md) |
| Fees, funding, deposits and other postings | [List account transactions](https://docs.plurex.io/api-reference/platform/hosts/list-transactions.md) |

> [!NOTE]
>
> 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](https://docs.plurex.io/api-reference/platform/hosts/list-wallets.md) returns one entry per asset, and per wallet where the host keeps several:

```json theme={null}
{ "accountId": "acc_123" }
```

```json theme={null}
{
  "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](https://docs.plurex.io/api-reference/platform/hosts/list-positions.md) 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:

```json theme={null}
{
  "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](https://docs.plurex.io/concepts/instruments.md).
* 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](https://docs.plurex.io/api-reference/platform/hosts/list-margin-states.md) 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.

```json theme={null}
{
  "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](https://docs.plurex.io/api-reference/platform/hosts/get-market-state.md) gathers what matters for one market into a single read. The result's `type` depends on the market:

```json theme={null}
{
  "accountId": "acc_123",
  "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" }
}
```

**Derivative**

Leverage setting, collateral and the position:

```json theme={null}
{
  "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"
    }
  }
}
```

**Spot**

The available base and quote balances:

```json theme={null}
{
  "data": {
    "type": "Spot",
    "instrument": { "type": "Spot", "base": "BTC", "quote": "USDT" },
    "base": { "available": "0.150" },
    "quote": { "available": "8710.15" }
  }
}
```

**SpotMargin**

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`.

```json theme={null}
{
  "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:

1. The host's `capabilities.marketSettings.getMarketLeverage` and `setMarketLeverage` must not be `NotSupported`.
2. The market's `settings.leverage` (from [List host markets](https://docs.plurex.io/api-reference/platform/hosts/list-markets.md)) must be non-null. Inside it, `get` says whether you can read it, and `setEffectScope` is `null` when it cannot be set.

```json theme={null}
{ "min": "1", "max": "100", "step": "0.01", "get": true, "setEffectScope": { "type": "Market" } }
```

### Read it

[Get market leverage](https://docs.plurex.io/api-reference/platform/hosts/get-leverage.md) 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](https://docs.plurex.io/api-reference/platform/hosts/set-leverage.md) takes a value on the market's grid: between `min` and `max` inclusive, and exactly `min` plus a whole number of `step`s. 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`.

```json theme={null}
{
  "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.

> [!WARNING]
>
> 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.

```json theme={null}
{
  "accountId": "acc_123",
  "instrument": { "type": "Perp", "base": "BTC", "quote": "USDT" },
  "mode": "Hedging"
}
```

[Set market position mode](https://docs.plurex.io/api-reference/platform/hosts/set-position-mode.md) 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](https://docs.plurex.io/api-reference/platform/hosts/list-transactions.md) 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`.

```json theme={null}
{ "accountId": "acc_123" }
```

```json theme={null}
{
  "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](https://docs.plurex.io/guides/streams.md#transaction-events) 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](https://docs.plurex.io/guides/streams.md) 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.

## Related

* [Instruments](https://docs.plurex.io/concepts/instruments.md): native contract sizes and canonical symbols.
* [Host capabilities](https://docs.plurex.io/capabilities/host-capabilities.md): market settings and transaction capabilities.
* [Order rules](https://docs.plurex.io/capabilities/order-rules.md): `positionEffect`, `reduceOnly` and the other order flags.
* [Stream account updates](https://docs.plurex.io/guides/streams.md): live order and transaction events.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.