> 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/account.md).

# Account

Real-time updates of your futures positions, orders, conditional orders and TP/SL levels.

Use this stream to keep your positions, active orders, conditional orders and TP/SL levels in sync without polling. Every change to one of them produces one message carrying the full, current object — the same object the [Futures REST API](broken://pages/5af105514c769e54cdcc5c7c16de2848aa3aa267) returns. Changes made anywhere (web, mobile app, API, the engine itself: fills, TP/SL, liquidation, funding) are pushed to every open connection of your account.

### Endpoint

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

### Authentication

Send an API-key-signed `AUTH` as the first message, within 5 seconds; sign `ts + "GET" + "/ws/account"`. 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                                                                                                                                    |
| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `e`   | string  | Object kind: `POSITION`, `ORDER`, `CONDITIONAL`, `TPSL`                                                                                        |
| `a`   | string  | Action that produced the message (see [Actions](#actions))                                                                                     |
| `d`   | object  | Full object: [position](#position-payload), [order](#order-payload), [conditional order](#conditional-payload) or [TP/SL level](#tpsl-payload) |
| `ts`  | integer | Server send time, epoch ms                                                                                                                     |

```json
{
  "e": "ORDER",
  "a": "PLACED",
  "d": {
    "id": "order-id",
    "pi": 1
  },
  "ts": 1790662754945
}
```

`d` is shortened here; each payload is described below. Fields inside `d` are always present; a missing value is `null`.

### 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`                                                            |
| `POSITION`    | Server → Client | A position was opened, changed, closed or liquidated                                   |
| `ORDER`       | Server → Client | An order was placed, filled, changed or cancelled                                      |
| `CONDITIONAL` | Server → Client | A conditional (stop / OCO) order was placed, changed, triggered, cancelled or rejected |
| `TPSL`        | Server → Client | A position TP/SL level was added, changed, triggered or cancelled                      |

The type of a data message is its `e` field. There is no subscribe message: after `AUTH` you receive every update of your account.

### Actions

| `e`           | `a`          | Meaning                                                                                                           |
| ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `POSITION`    | `OPENED`     | New position opened                                                                                               |
| `POSITION`    | `UPDATED`    | Position changed and remains open: scale-in, partial close, partial liquidation, funding settlement, bonus change |
| `POSITION`    | `CLOSED`     | Position fully closed (manual, API, TP/SL, reduce-only, NETTING reversal)                                         |
| `POSITION`    | `LIQUIDATED` | Position fully liquidated                                                                                         |
| `ORDER`       | `PLACED`     | Limit order accepted and resting (`st` = `NEW`)                                                                   |
| `ORDER`       | `FILLED`     | Order executed: market orders, filled limits, and system-created closes (TP/SL, liquidation)                      |
| `ORDER`       | `UPDATED`    | Resting order changed in place (for example, its attached TP/SL)                                                  |
| `ORDER`       | `CANCELLED`  | Order cancelled, by you or by the system                                                                          |
| `CONDITIONAL` | `PLACED`     | Conditional order armed (single stop or each OCO leg)                                                             |
| `CONDITIONAL` | `UPDATED`    | Pending conditional order amended (trigger, size, attached TP/SL)                                                 |
| `CONDITIONAL` | `TRIGGERED`  | Trigger reached; the resulting order was placed (it arrives as an `ORDER` message)                                |
| `CONDITIONAL` | `CANCELLED`  | Cancelled: by you, by the other OCO leg, or by the system                                                         |
| `CONDITIONAL` | `REJECTED`   | Trigger reached but the resulting order could not be placed                                                       |
| `TPSL`        | `ADDED`      | New TP/SL level set on a position                                                                                 |
| `TPSL`        | `UPDATED`    | Level price or size changed (same `id`)                                                                           |
| `TPSL`        | `TRIGGERED`  | Level fired; the close order arrives as an `ORDER` message                                                        |
| `TPSL`        | `CANCELLED`  | Level cancelled, by you or by the system                                                                          |

{% hint style="info" %}

* One user action often produces several messages, e.g. a filled market order gives an `ORDER` `FILLED` plus a `POSITION` `OPENED` / `UPDATED` / `CLOSED`.
* `d` is the object's state when the message is sent. Treat `d` as the source of truth and use `a` to decide what to do with the row: upsert by `id`, or remove it (`POSITION` `CLOSED` / `LIQUIDATED`).
* Messages are sent only after the change is committed, so you never receive a change that was rolled back.
  {% endhint %}

## Position Payload

`e` = `POSITION`. Same object as [Get Open Positions](broken://pages/8a65b0267b58d7282fdacb75e81c6a9b308f8eac#get-open-positions), with the differences noted below.

```json
{
  "e": "POSITION",
  "a": "OPENED",
  "d": {
    "id": "position-id",
    "pi": 1,
    "s": "LONG",
    "sz": 0.01700000,
    "e": 83797.00000000,
    "l": 10.00,
    "im": 142.45490000,
    "lq": 75836.30000000,
    "upn": null,
    "mmd": "ISOLATED",
    "tf": 0.00000000,
    "af": 0.00000000,
    "rpn": -0.78368400,
    "bm": 0.00000000,
    "bib": 0.00000000,
    "tpsl": [
      {
        "id": "tpsl-id",
        "po": "position-id",
        "ty": "TP",
        "p": 88000.00000000,
        "q": null,
        "ep": true,
        "toi": null
      }
    ]
  },
  "ts": 1790662754945
}
```

| Field  | Type            | Description                                                                                                                                                                                                                                          |
| ------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`   | string          | Position ID (UUID)                                                                                                                                                                                                                                   |
| `pi`   | integer         | Pair ID (`gid`)                                                                                                                                                                                                                                      |
| `s`    | string          | `LONG` or `SHORT`                                                                                                                                                                                                                                    |
| `sz`   | decimal         | Size. Linear: base coin. Inverse: USD contracts                                                                                                                                                                                                      |
| `e`    | decimal         | Average entry price                                                                                                                                                                                                                                  |
| `l`    | decimal         | Leverage                                                                                                                                                                                                                                             |
| `im`   | decimal         | Initial margin in the settlement coin, incl. bonus part `bm`                                                                                                                                                                                         |
| `lq`   | decimal \| null | Liquidation price stored on the position at this change; `null` if none. For `CROSS` it is not recalculated on price moves — use [Get Open Positions](broken://pages/8a65b0267b58d7282fdacb75e81c6a9b308f8eac#get-open-positions) for the live value |
| `upn`  | null            | Always `null` on this stream. Calculate unrealized PnL from market data: best bid for `LONG`, best ask for `SHORT`                                                                                                                                   |
| `mmd`  | string          | `ISOLATED` or `CROSS`                                                                                                                                                                                                                                |
| `tf`   | decimal         | Trading fees owed and not yet charged (normally `0`)                                                                                                                                                                                                 |
| `af`   | decimal         | Funding owed (paid, not yet settled); settled on close                                                                                                                                                                                               |
| `rpn`  | decimal         | Net realized PnL: close PnL − all fees ± funding. Same value as REST                                                                                                                                                                                 |
| `bm`   | decimal         | Bonus locked in margin; `0` if none                                                                                                                                                                                                                  |
| `bib`  | decimal         | Margin the bonus share was fixed against; `bm` / `bib` = bonus-funded fraction on close                                                                                                                                                              |
| `tpsl` | array           | Active [TP/SL levels](#tpsl-payload) of the position; `[]` = none                                                                                                                                                                                    |

## Order Payload

`e` = `ORDER`. Same object as [Place Order](broken://pages/2d7e1d40d8e19f9de1a0ebe485fd2e9a598d0b28#place-order).

```json
{
  "e": "ORDER",
  "a": "FILLED",
  "d": {
    "id": "order-id",
    "pi": 1,
    "d": "OPEN_LONG",
    "ty": "MARKET",
    "st": "FILLED",
    "q": 0.01700000,
    "fq": 0.01700000,
    "afp": 83797.00000000,
    "p": null,
    "l": 10.00000000,
    "f": 0.78368400,
    "rpn": null,
    "po": "position-id",
    "ca": 1790662754940,
    "ea": 1790662754945,
    "atp": 88000.00000000,
    "asl": null,
    "mm": "ISOLATED"
  },
  "ts": 1790662754950
}
```

| Field | Type            | Description                                                                    |
| ----- | --------------- | ------------------------------------------------------------------------------ |
| `id`  | string          | Order ID (UUID)                                                                |
| `pi`  | integer         | Pair ID                                                                        |
| `d`   | string          | `OPEN_LONG`, `OPEN_SHORT`, `CLOSE_LONG`, `CLOSE_SHORT`                         |
| `ty`  | string          | `MARKET` or `LIMIT`                                                            |
| `st`  | string          | `NEW` (resting), `FILLED`, `CANCELLED`                                         |
| `q`   | decimal         | Order quantity                                                                 |
| `fq`  | decimal         | Filled quantity                                                                |
| `afp` | decimal \| null | Average fill price; `null` until filled                                        |
| `p`   | decimal \| null | Limit price; `null` for `MARKET`                                               |
| `l`   | decimal         | Leverage applied                                                               |
| `f`   | decimal         | Fee in the settlement coin: maker fee to pay (resting) or fee charged (filled) |
| `rpn` | decimal \| null | Realized PnL of this fill (closing fills only)                                 |
| `po`  | string \| null  | Position ID; `null` for an unfilled opening limit                              |
| `ca`  | integer         | Created (placement) time, epoch ms                                             |
| `ea`  | integer \| null | Execution time, epoch ms; `null` until filled                                  |
| `atp` | decimal \| null | Attached take-profit price                                                     |
| `asl` | decimal \| null | Attached stop-loss price                                                       |
| `mm`  | string          | `ISOLATED` or `CROSS`                                                          |

## Conditional Payload

`e` = `CONDITIONAL`. Same object as [Place Conditional Order](broken://pages/46e8bed26373d40acb6ef34336395d3b0f22db95#place-conditional-order).

```json
{
  "e": "CONDITIONAL",
  "a": "PLACED",
  "d": {
    "id": "conditional-order-id",
    "pi": 1,
    "d": "OPEN_LONG",
    "ot": "STOP_MARKET",
    "trp": 86000.00000000,
    "q": 0.02000000,
    "s": null,
    "l": 10.00000000,
    "st": "PENDING",
    "og": null,
    "ca": 1790662754.945123000,
    "atp": null,
    "asl": null,
    "mm": "ISOLATED",
    "pm": "NETTING"
  },
  "ts": 1790662754950
}
```

| Field | Type            | Description                                                                                  |
| ----- | --------------- | -------------------------------------------------------------------------------------------- |
| `id`  | string          | Conditional order ID (UUID)                                                                  |
| `pi`  | integer         | Pair ID                                                                                      |
| `d`   | string          | `OPEN_LONG`, `OPEN_SHORT`, `CLOSE_LONG`, `CLOSE_SHORT`                                       |
| `ot`  | string          | `STOP_MARKET`                                                                                |
| `trp` | decimal         | Trigger price                                                                                |
| `q`   | decimal         | Quantity; an estimate at `trp` for spend-sized orders, final at trigger                      |
| `s`   | decimal \| null | Spend for spend-sized orders; `null` otherwise                                               |
| `l`   | decimal         | Leverage                                                                                     |
| `st`  | string          | `PENDING`, `TRIGGERED`, `CANCELLED`, `REJECTED`                                              |
| `og`  | string \| null  | OCO group ID; `null` for a single stop                                                       |
| `ca`  | number          | Created time, epoch **seconds** with fraction (unlike the other payloads' ms); × 1000 for ms |
| `atp` | decimal \| null | Attached take-profit price                                                                   |
| `asl` | decimal \| null | Attached stop-loss price                                                                     |
| `mm`  | string          | `ISOLATED` or `CROSS`                                                                        |
| `pm`  | string          | `NETTING` or `HEDGING`                                                                       |

## TPSL Payload

`e` = `TPSL`. One position TP/SL level — the same object as in the position's `tpsl` array. Merge it into the position with ID `po`: upsert on `ADDED` / `UPDATED`, remove on `TRIGGERED` / `CANCELLED`.

```json
{
  "e": "TPSL",
  "a": "ADDED",
  "d": {
    "id": "tpsl-id",
    "po": "position-id",
    "ty": "SL",
    "p": 80000.00000000,
    "q": 0.01000000,
    "ep": false,
    "toi": null
  },
  "ts": 1790662754950
}
```

| Field | Type            | Description                                                      |
| ----- | --------------- | ---------------------------------------------------------------- |
| `id`  | string          | Level ID (UUID)                                                  |
| `po`  | string          | Position ID                                                      |
| `ty`  | string          | `TP` or `SL`                                                     |
| `p`   | decimal         | Trigger price                                                    |
| `q`   | decimal \| null | Quantity to close; `null` for an entire-position level           |
| `ep`  | boolean         | `true` = entire-position level, `false` = partial with fixed `q` |
| `toi` | string \| null  | ID of the close order the level produced (set on `TRIGGERED`)    |

## 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 unrecognised messages are ignored.

## Reconnect

There is no snapshot on connect and no replay of missed messages. On every (re)connect:

{% stepper %}
{% step %}

### Connect and authenticate

Connect and send `AUTH`; wait for `{"t":"AUTH","d":{"ok":true}}`.
{% endstep %}

{% step %}

### Load the current state

Load the current state over REST: [Get Open Positions](broken://pages/8a65b0267b58d7282fdacb75e81c6a9b308f8eac#get-open-positions), [Get Orders](broken://pages/2d7e1d40d8e19f9de1a0ebe485fd2e9a598d0b28#get-orders), and your [conditional orders](broken://pages/46e8bed26373d40acb6ef34336395d3b0f22db95).
{% endstep %}

{% step %}

### Apply stream messages

Apply stream messages on top, keyed by `id`.
{% endstep %}
{% endstepper %}

Reconnect with exponential backoff and jitter.

## Python Example

{% code title="futures\_account.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/account"


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/account"))
        print("auth:", await ws.recv())
        asyncio.create_task(keepalive(ws))
        async for raw in ws:
            if raw == "pong":
                continue
            msg = json.loads(raw)
            d = msg.get("d", {})
            print(msg.get("e"), msg.get("a"), d.get("id"), d.get("st") or d.get("s"))


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/account.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.
