> For the complete documentation index, see [llms.txt](https://agentdex.gitbook.io/agentdex-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agentdex.gitbook.io/agentdex-docs/trading/margin-and-leverage.md).

# Margin and leverage

AgentDex uses **cross margin** by default: a single USDT balance backs every open position. Free collateral on one position can flow into another that's under stress, and excess equity automatically pads liquidation prices for the rest of your book. Isolated margin is exposed where supported per instrument, with explicitly-locked margin and no spill-over.

### The key quantities

For any open position, three numbers matter:

* **Position value** — notional in USDT, equal to `|contracts × contract_size × mark_price|`.
* **Initial Margin (IM)** — collateral required to open. `IM = |position_value| / leverage + fee_reserve`.
* **Maintenance Margin (MM)** — minimum equity required to keep the position open. Below this, liquidation triggers.

The matching engine reports these in the position object and over the `position` WebSocket topic. MCP exposes the same via `get_positions` and `get_balances`.

#### MM formula

{% code title="Maintenance margin formula" %}

```
MM = |contract_base_volume × value| × (1 / max_leverage) × maintenance_margin_rate
   + funding_amount.negative_part
   + fee_reserve
```

{% endcode %}

The protocol-wide `maintenance_margin_rate` is **0.5** on production. The funding-amount term means a position trending against you accrues margin pressure even between funding settlements.

### Leverage

Every position carries a leverage value that scales required margin:

* **Range**: minimum 1×, default 5×, per-instrument cap (currently 20× for BTC/ETH, up to 50× for some alts). The protocol enforces a hard cap of 100× regardless of instrument config.
* **Set leverage** before opening, or while a position is open, via `POST /v1/futures/change-leverage` (HTTP) or `change_leverage` (MCP). Both take an integer in the allowed range.

{% code title="Change leverage" %}

```http
POST /v1/futures/change-leverage
{ "instrument_id": "BTC_USDT_PERPETUAL", "leverage": 10 }
```

{% endcode %}

Raising leverage on an open position reduces IM and frees collateral back to `available`. Lowering leverage on an open position requires more collateral to be locked — the call fails if you don't have it.

`prepare-leverage` returns the deltas without committing — a dry-run useful for UIs and agents.

### Adding / removing margin from a position

For cross positions you can move margin in and out without closing:

{% code title="Change margin" %}

```http
POST /v1/futures/change-margin
{ "instrument_id": "BTC_USDT_PERPETUAL",
  "delta": "100", "direction": "add" }
```

{% endcode %}

This is mostly cosmetic for cross (the engine already pools your balance), but it's useful for isolated positions where each position's margin is a hard envelope.

`change-margin-type` switches a position between cross and isolated. The call fails if the resulting margin would leave the position liquidatable.

### What you see on the account

`get_balances` (MCP) and the equivalent REST endpoint return:

| Field            | Meaning                                                        |
| ---------------- | -------------------------------------------------------------- |
| `available`      | Free USDT — usable for new orders and new margin               |
| `on_hold`        | USDT locked in open orders and open position margin            |
| `unrealized_pnl` | Mark-to-market PnL across all open positions (can be negative) |

Total equity is `available + on_hold + unrealized_pnl`. Liquidation decisions use position-level margin against mark price, not total equity — see [Liquidations](/agentdex-docs/trading/liquidations.md).

### Worked example

Open a **$1 000 long on BTC at 10× leverage**, BTC trading at $80 000:

* Position value: $1 000.
* Initial margin: $1 000 / 10 = $100, plus fee reserve.
* Maintenance margin (rough): $1 000 × (1/20) × 0.5 = $25 plus funding/fees buffer.
* Equity after open: deposit – fees, with $100 locked as position margin.

If BTC drops to $76 000 (-5%), unrealised PnL is -$50. Your position margin still covers MM. Cross margin means any other free USDT can absorb further losses before liquidation triggers.

If BTC drops to \~$72 000 (-10%), unrealised PnL is -$100 — close to your locked IM. The engine evaluates liquidation against mark price, and pulls free balance to avoid liquidation (cross only) before resorting to forced close.

The exact liquidation price depends on your available balance and the per-instrument MM rate. See [Liquidations](/agentdex-docs/trading/liquidations.md) for the full formula.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://agentdex.gitbook.io/agentdex-docs/trading/margin-and-leverage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.