# Settlements and payouts


Source: https://docs.stxapp.io/concepts/settlements/

A **settlement** is the final money-movement event for a set of contracts. Every settlement
results in a realized profit or loss and the release of the corresponding position liability
back into your available balance.

---

## When Settlements Are Created

Settlements are generated in two situations:

1. **You close a position by trading.** If you bought 10 contracts and then sell 5, those
   5 contracts are settled against each other at the prices you paid and received. The
   remaining 5 stay open.

2. **A market expires.** When STX resolves a market, outstanding contracts settle at the
   market's `max_price` for a win, or $0 for a loss. A `push` or `settled` result pays out
   between the two.

---

## Settlement Fields

| Field | Description |
|-------|-------------|
| `id` | Unique settlement ID |
| `type` | `closed_long`, `closed_short`, `expired_long` or `expired_short`: whether a trade or the market's result closed the position, and which side it was |
| `opening_trade_id` | The trade that opened the position |
| `closing_trade_id` | The trade that closed it; `null` when the market's result closed it |
| `opening_price` | Price of the opening trade, as a dollar string |
| `closing_price` | Price of the closing trade, or the market's settlement price (`max_price`, `0`, or between them) on expiry |
| `quantity` | Number of contracts settled, as a quantity string |
| `fee` | Exchange fee charged on this settlement |
| `gross_pnl` | `(closing_price − opening_price) × quantity` for a long; the sign is inverted for a short |
| `realized_pnl` | `gross_pnl − fee` |
| `settled_premium` | Premium settled: negative for a long, positive for a short |
| `settled_risk` | Risk released by the settlement |
| `market_id` | Market the settlement belongs to |
| `account_id` | Account the settlement belongs to |
| `time` | When the settlement was created, ISO 8601 |
| `inserted_at` | The same instant, as an integer of UNIX microseconds |

Money fields are dollar strings, the same format as every other REST field; see
[Wire format](/websockets/channels/wire-format/).

---

## Example Settlement

A member sold 100 contracts at $0.10 (opening a short) on a market whose `max_price` is
`"1.0000"`, and later bought 100 contracts back at $0.20 (closing the short): a loss,
because the price moved against the short. The settlement looks like:

```json
{
  "id": "801d773e-fecc-418a-b377-155605595178",
  "type": "closed_short",
  "opening_trade_id": "17aa760d-50c0-4c1a-a5c6-fe4af4adb4bb",
  "closing_trade_id": "7f959093-6a30-4b48-9a59-d1e09f004340",
  "opening_price": "0.1000",
  "closing_price": "0.2000",
  "quantity": "100.00",
  "fee": "0.5000",
  "gross_pnl": "-10.0000",
  "realized_pnl": "-10.5000",
  "settled_premium": "10.0000",
  "settled_risk": "90.0000",
  "market_id": "687e9cdb-a391-4118-aa80-1122bb14779f",
  "account_id": "c1c3614c-32ae-4bea-bae4-fc3f52047790",
  "time": "2026-11-01T19:02:28.125460Z",
  "inserted_at": 1793559748125460
}
```

Gross P&L: (0.10 − 0.20) × 100 = −$10.00. After a $0.50 fee: −$10.50 net realized P&L.

:::note
For a **short** position the sign convention is: selling contracts at a low price and
buying them back at a higher price is a **loss**; buying back at a lower price is a
**profit**. For a **long** position it is the reverse.
:::

---

## Querying Settlement History

Use [`GET /api/v1/portfolio/settlements`](/api/rest/portfolio/list-settlements/) to retrieve past settlements. Each one
names its `opening_trade_id` and `closing_trade_id`, which you can match against your
fills from [`GET /api/v1/fills`](/api/rest/fills/list-fills/).

---

## Real-Time Settlement Notifications

Subscribe to the [`settlements`](/websockets/channels/settlements/) channel to
receive settlement records the instant they are created. This is the most reliable way to
keep a running P&L in your integration; polling settlement history will always lag behind
the live state of the exchange.