# List settlements

> Settled positions and their payouts, most recent first.

Source: https://docs.stxapp.io/api/rest/portfolio/list-settlements/

Settled positions and their payouts, most recent first.

```http
GET /api/v1/portfolio/settlements
```

Send it with your own demo key: [Try it](/quick-start/?op=portfolio_settlements_get#try-it).

:::tip[In the SDKs]
- TypeScript: [`STX.settlements()`](/sdks/typescript/reference/stx/#settlements)
- Python: [`STX.settlements()`](/sdks/python/reference/stx/#settlements)
- C#: [`STXSettlementService.GetMySettlementsAsync()`](/sdks/csharp/reference/account/#stxsettlementservice)
:::

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `market_ids` | `query` | string | no | Comma-separated market UUIDs. |
| `type` | `query` | `closed_short` \| `closed_long` \| `expired_short` \| `expired_long` | no | Filter to one settlement type. |
| `limit` | `query` | integer | no | Rows per page. Defaults to 100 and is silently clamped to 200; a larger value is not an error. |
| `cursor` | `query` | string | no | Cursor from the previous response. Omit for the first page. |

## Responses

| Status | Description | Schema |
|---|---|---|
| `200` | Success | object |
| `400` | A parameter was missing or invalid. | Error |
| `401` | Missing, malformed or unrecognized signature, or a timestamp outside the 30-second window. Body: {"error":"Missing or invalid API key credentials"} | Error |
| `403` | The account behind this key is not active, for example it is pending approval or suspended. Body: {"error":"Your account is suspended. Contact support."}, the message naming the account's status. | Error |

## Example

Request:

```bash
curl --request GET \
  --url 'https://demo.stxapp.io/api/v1/portfolio/settlements' \
  --header 'X-STX-ACCESS-KEY: <key-id>' \
  --header 'X-STX-ACCESS-TIMESTAMP: <unix-ms>' \
  --header 'X-STX-ACCESS-SIGNATURE: <base64-ed25519>'
```

Response `200`:

```json
{
  "cursor": null,
  "settlements": [
    {
      "account_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "closing_placed_pre_start": null,
      "closing_price": "0.6700",
      "closing_trade_id": null,
      "closing_traded_pre_start": null,
      "fee": "0.6700",
      "gross_pnl": "0.6700",
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "inserted_at": 0,
      "market_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "opening_placed_pre_start": false,
      "opening_price": "0.6700",
      "opening_trade_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "opening_traded_pre_start": false,
      "pre_start": false,
      "quantity": "2.00",
      "realized_pnl": "0.6700",
      "settled_premium": "0.6700",
      "settled_risk": "0.6700",
      "time": "2026-08-25T04:42:46.242093Z",
      "type": "closed_short"
    }
  ]
}
```

### Response fields

| Field | Type | Description |
|---|---|---|
| `cursor` | string | Opaque cursor for the next page. Pass the value from the previous response; omit for the first page. `null` once there are no more pages. |
| `account_id` | uuid | The account the record belongs to. |
| `closing_placed_pre_start` | boolean | Whether the closing trade's order was placed before the event started. |
| `closing_price` | decimal | The price of the contracts when the position was closed. In dollars. |
| `closing_trade_id` | uuid | The id of the trade that closed this settlement, if any. |
| `closing_traded_pre_start` | boolean | Whether the closing trade was placed before the event started. |
| `fee` | decimal | The fee charged for the settlement. In dollars. |
| `gross_pnl` | decimal | The profit or loss associated with the position. In dollars. |
| `id` | uuid | Unique identifier for the record. |
| `inserted_at` | int64 | Creation time, as UNIX microseconds. |
| `market_id` | uuid | The market this record relates to. |
| `opening_placed_pre_start` | boolean | Whether the opening trade's order was placed before the event started. |
| `opening_price` | decimal | The price of the contracts when the position was opened. In dollars. |
| `opening_trade_id` | uuid | The id of the trade that opened this settlement. |
| `opening_traded_pre_start` | boolean | Whether the opening trade was placed before the event started. |
| `pre_start` | boolean | Whether the settlement was placed before the event started. |
| `quantity` | decimal | The number of contracts that were settled. |
| `realized_pnl` | decimal | The net profit or loss minus fees. In dollars. |
| `settled_premium` | decimal | The amount of premium that was settled by the trade. In dollars. |
| `settled_risk` | decimal | The amount of risk that was settled by the trade. In dollars. |
| `time` | date-time | ISO-8601 timestamp of when the settlement was created. Same instant as `inserted_at`, which carries it as UNIX microseconds. |
| `type` | string | The type of settlement. |