# Settlements Channel


Source: https://docs.stxapp.io/websockets/channels/settlements/

Topic: `settlements:{user_id}`

Delivers a settlement recorded against your account whenever a trade closes or
expires. Money arrives as dollar strings and contract counts as quantity strings;
see [Wire format](/websockets/channels/wire-format/).

:::tip[No snapshot on join]
This is a change feed. Joining tells you nothing about settlements that already
happened. Pull those from `GET /api/v1/portfolio/settlements` and keep them current
from here.
:::

## Settlement object

### Identity

- `id` : The unique id of the settlement.
- `account_id` : The id of the account the settlement is for.
- `market_id` : The id of the market the settlement is on.
- `opening_trade_id` : The id of the trade that opened the position being settled.
- `closing_trade_id` : The id of the trade that closed the position. Null when the
  position was closed by the market settling rather than by a closing trade.
- `type` : What caused the settlement and the position beforehand:
  `closed_short`, `closed_long`, `expired_short` or `expired_long`.
- `inserted_at` : When the settlement was recorded, as an integer of Unix microseconds.

### Amounts

- `opening_price` : The price the opening trade traded at.
- `closing_price` : The price the closing trade traded at, or the market's
  settlement price for an `expired_*` settlement.
- `quantity` : The number of contracts settled, as a quantity string. Can be
  fractional.
- `fee` : The fee charged for the settlement.
- `gross_pnl` : The profit or loss before fees.
- `realized_pnl` : The profit or loss after fees.
- `settled_premium` : The amount of premium settled.
- `settled_risk` : The amount of risk settled.

### Pre-start flags

- `opening_placed_pre_start` : Whether the opening trade's order was placed before
  the event started.
- `closing_placed_pre_start` : Whether the closing trade's order was placed before
  the event started. Null when there is no closing trade.
- `opening_traded_pre_start` : Whether the opening trade executed before the event
  started.
- `closing_traded_pre_start` : Whether the closing trade executed before the event
  started. Null when there is no closing trade.
- `pre_start` : Whether the settlement itself was created before the event started.

## Use Cases

| Use case | Message to send |
| --- | --- |
| Join and start receiving settlements | `["3","3","settlements:<user_id>","phx_join",{}]` |
| Join filtered to one market (see [filtering](/websockets/channels/wire-format/#filtering)) | `["3","3","settlements:<user_id>","phx_join",{"market_ids":["<uuid>"]}]` |
| Change the market filter without rejoining | `["3","4","settlements:<user_id>","select_market_ids",{"market_ids":null}]` |
| Check the connection is alive | `["3","5","settlements:<user_id>","ping",{}]` |

### Joining

```json
["3","3","settlements:<user_id>","phx_join",{}]
```

```json
{"status":"ok","response":{"selected_market_ids":null}}
```

Nothing follows until a settlement is recorded.

### Pushed when a settlement is recorded

```json
[null, null, "settlements:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "new_settlements", { "settlements": [Settlement]}]
```

Settlements are batched into one frame. This event is a **delta**: when a
`market_ids` filter is active and none of the settlements match it, no frame is sent
at all rather than one carrying an empty list.

```json
[
  null,
  null,
  "settlements:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "new_settlements",
  {
    "settlements": [
      {
        "id": "801d773e-fecc-418a-b377-155605595178",
        "account_id": "c1c3614c-32ae-4bea-bae4-fc3f52047790",
        "market_id": "687e9cdb-a391-4118-aa80-1122bb14779f",
        "opening_trade_id": "17aa760d-50c0-4c1a-a5c6-fe4af4adb4bb",
        "closing_trade_id": "7f959093-6a30-4b48-9a59-d1e09f004340",
        "type": "closed_short",
        "inserted_at": 1793559748125460,
        "opening_price": "0.2000",
        "closing_price": "0.1000",
        "quantity": "100.00",
        "fee": "0.5000",
        "gross_pnl": "10.0000",
        "realized_pnl": "9.5000",
        "settled_premium": "20.0000",
        "settled_risk": "80.0000",
        "opening_placed_pre_start": false,
        "closing_placed_pre_start": false,
        "opening_traded_pre_start": false,
        "closing_traded_pre_start": false,
        "pre_start": false
      }
    ]
  }
]
```