> For the complete documentation index, see [llms.txt](https://docs.outpoll.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.outpoll.com/api/futures-api/websockets/futures-account-streams/margin-call.md).

# Margin Call

Real-time warnings when your cross margin gets close to liquidation.

Use this stream to react before a `CROSS` position is liquidated: add funds, reduce or close positions. Warnings are sent only for `CROSS` margin. `ISOLATED` positions have their own liquidation price (`lq`) and get no margin calls.

## Endpoint

```
wss://futures-trading-service.outpoll.com/ws/margin-call
```

## Authentication

Send an API-key-signed `AUTH` as the first message, within 5 seconds; sign `ts + "GET" + "/ws/margin-call"`. See [Futures Account → Authentication](broken://pages/a86734d3e8286b04f95a8b4d8e32befac5eb7208#authentication).

```json
{
  "t": "AUTH",
  "d": {
    "key": "your-api-key",
    "ts": "1790835600",
    "sig": "signature"
  }
}
```

The server replies `{"t":"AUTH","d":{"ok":true}}`.

## Message Envelope

| Field       | Type   | Description                                                       |
| ----------- | ------ | ----------------------------------------------------------------- |
| `type`      | string | Always `MARGIN_CALL`                                              |
| `positions` | array  | Your open `CROSS` positions at risk; omitted if the list is empty |

## Message Types

| Type          | Direction       | Description                                    |
| ------------- | --------------- | ---------------------------------------------- |
| `AUTH`        | Client → Server | Authenticate with your API key (first message) |
| `AUTH`        | Server → Client | Authentication acknowledgement `{"ok": true}`  |
| `ping`        | Client → Server | Plain-text keep-alive                          |
| `pong`        | Server → Client | Plain-text answer to `ping`                    |
| `MARGIN_CALL` | Server → Client | Your cross margin is close to liquidation      |

There is no subscribe message: after `AUTH` you receive every margin call of your account.

## When It Is Sent

Cross margin is evaluated per settlement coin: all your open `CROSS` positions settled in the same coin share one margin pool. The pool's risk is checked about every 3 seconds while its pairs' mark prices move, and is measured as how far the pool is on the way to liquidation (100% = liquidation).

* A margin call is sent when the pool rises into a warning level. By default the levels are **75%**, **90%** and **97%** of the way to liquidation.
* While the pool stays in the same level, the margin call is repeated at most once per **60 seconds**.
* When the pool falls back below the lowest level, the warning resets: the next rise sends a new margin call.
* A margin call is also sent right before liquidation of the pool starts, unless one was just sent.

The message does not carry the level. Check your margin over REST when it arrives.

## MARGIN\_CALL Payload

```json
{
  "type": "MARGIN_CALL",
  "positions": [
    {
      "id": "position-id",
      "symbol": "BTCUSDT",
      "side": "LONG"
    },
    {
      "id": "position-id-2",
      "symbol": "ETHUSDT",
      "side": "SHORT"
    }
  ]
}
```

`positions[]` item:

| Field    | Type   | Description                                                                                                                                                                                                                                |
| -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`     | string | Position ID (UUID); matches `id` on the [Account](broken://pages/03b5eb7e31273427a7e8e339026a8d152a8c3f15#position-payload) stream and in [Get Open Positions](broken://pages/8a65b0267b58d7282fdacb75e81c6a9b308f8eac#get-open-positions) |
| `symbol` | string | Pair name, e.g. `BTCUSDT`                                                                                                                                                                                                                  |
| `side`   | string | `LONG` or `SHORT`                                                                                                                                                                                                                          |

`positions` lists every open `CROSS` position of the pool at risk, not only the losing ones.

## Heartbeat

Send the plain text `ping` every 20–30 seconds; the server replies `pong`. Both are plain text, not JSON.

## Errors

No error messages are sent. Authentication failures close the connection with code `1008` (`auth required`). Other messages are ignored.

## Reconnect

Margin calls are not stored or replayed. A margin call that fires while you are disconnected is lost; after reconnecting you get the next one (repeats come at most every 60 seconds while the pool stays at risk). Reconnect with exponential backoff and jitter.

## Python Example

{% code title="margin\_call.py" %}

```python
import asyncio, base64, hashlib, hmac, json, time, websockets


API_KEY = "your-api-key"
API_SECRET = "your-api-secret"


def auth_frame(path):
    ts = str(int(time.time()))
    secret = base64.urlsafe_b64decode(API_SECRET + "=" * (-len(API_SECRET) % 4))
    digest = hmac.new(secret, (ts + "GET" + path).encode(), hashlib.sha256).digest()
    sig = base64.urlsafe_b64encode(digest).decode().rstrip("=")
    return json.dumps({"t": "AUTH", "d": {"key": API_KEY, "ts": ts, "sig": sig}})

URL = "wss://futures-trading-service.outpoll.com/ws/margin-call"


async def keepalive(ws):
    while True:
        await asyncio.sleep(20)
        await ws.send("ping")


async def main():
    async with websockets.connect(URL) as ws:
        await ws.send(auth_frame("/ws/margin-call"))
        print("auth:", await ws.recv())
        asyncio.create_task(keepalive(ws))
        async for raw in ws:
            if raw == "pong":
                continue
            msg = json.loads(raw)
            if msg.get("type") == "MARGIN_CALL":
                for p in msg.get("positions", []):
                    print("at risk:", p.get("symbol"), p.get("side"), p.get("id"))


asyncio.run(main())
```

{% endcode %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.outpoll.com/api/futures-api/websockets/futures-account-streams/margin-call.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
