Settlements Channel

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.

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)	["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

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

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

Nothing follows until a settlement is recorded.

Pushed when a settlement is recorded

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

[
  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
      }
    ]
  }
]