> For the complete documentation index, see [llms.txt](https://docs.lighter.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lighter.xyz/developers/binary-options/positions-and-settlement.md).

# Positions and settlement

Read binary options positions, settlement payouts and realized PnL.

Binary options positions are reported separately from perps positions, in `bo_positions`:

```json
{
  "bo_positions": [
    {
      "market_id": 4206,
      "sign": 1,
      "size": "100.0000",
      "entry_quote": "51.000000",
      "avg_entry_price": "0.51"
    }
  ]
}
```

| Field             | Meaning                                                                       |
| ----------------- | ----------------------------------------------------------------------------- |
| `market_id`       | Binary options market ID                                                      |
| `sign`            | `1` holds Up; `-1` holds Down                                                 |
| `size`            | Shares held, as a positive magnitude                                          |
| `entry_quote`     | Entry quote amount in USDC                                                    |
| `avg_entry_price` | Average price paid for the held side. For `sign = -1`, this is the Down price |

Positions appear in [account](https://docs.lighter.xyz/api/account) and in the [account\_all](https://docs.lighter.xyz/api/websocket#account-all) and [account\_all\_positions](https://docs.lighter.xyz/api/websocket#account-all-positions) WebSocket channels as `bo_positions`. The [account\_market](https://docs.lighter.xyz/api/websocket#account-market) channel reports a single market’s position as `bo_position`. See the linked sections of the [WebSocket reference](https://docs.lighter.xyz/api/websocket) for subscription formats, authentication and response payloads.

## Settlement

When the window ends the market moves to `waiting-for-settlement`. Resting GTT orders can remain until settlement; cancel them to release reserved funds sooner. When the operator initiates settlement from the price source, remaining orders are cancelled before positions are paid to the USDC balance:

| Position                  | Settles Up (`outcome = 2`) | Settles Down (`outcome = 1`) |
| ------------------------- | -------------------------- | ---------------------------- |
| Up shares (`sign = 1`)    | `1.00` USDC per share      | `0` USDC                     |
| Down shares (`sign = -1`) | `0` USDC                   | `1.00` USDC per share        |

Market definition fields use **price ticks**. Convert them before calculating payouts in USDC:

```
Up payout per share   = settlement_price / 10^price_decimals
Down payout per share = (settlement_cap − settlement_price) / 10^price_decimals
```

For Up/Down markets, `price_decimals = 2` and `settlement_cap = 100`, so `100` ticks equals `1.00` USDC.

If no outcome can be determined, the market settles at its `default_price` (`50` ticks, or `0.50` USDC per share to both sides) and `outcome` stays `0`.

Each settled position gets a [trade](https://docs.lighter.xyz/api/orders) with `type: "market-settlement"`, alongside regular `trade` fills. The settlement record's `price` is always in **Up terms**:

| Result                      | `price`  |
| --------------------------- | -------- |
| Up wins                     | `"1.00"` |
| Down wins                   | `"0.00"` |
| Refund at the default price | `"0.50"` |

`usd_amount` is the actual USDC payout to that account. The losing side also receives a settlement record, with `usd_amount: "0.000000"`. For example, when Down wins, both sides' records have `price: "0.00"`, but only the Down holder receives a payout. The counterparty is account `281474976710655`. Settlement records carry no trading fees; handle `taker_fee` and `maker_fee` as absent or `null`. Use `usd_amount`, rather than `price × size`, to read the payout.

## Realized PnL

```shell
curl -H "authorization: $AUTH" "https://mainnet.zklighter.elliot.ai/api/v1/portfolio/boPnl?account_index=$ACCOUNT_INDEX"
```

[portfolio\_boPnl](https://docs.lighter.xyz/api/binary-options) (`GET /api/v1/portfolio/boPnl`, authenticated) returns realized binary options PnL grouped by event, newest first. Every outcome the account has traded is listed, including open and unsettled markets.

| Parameter         | Notes                                                    |
| ----------------- | -------------------------------------------------------- |
| `account_index`   | Required                                                 |
| `event_id`        | Return a single event                                    |
| `cursor`, `limit` | Exclusive event id cursor (`next_cursor`), `limit` 1–100 |

```json
{
  "code": 200,
  "next_cursor": 106,
  "events": [
    {
      "event_id": 107,
      "event_title": "ETH Up or Down",
      "event_description": "Up if the chainlink ETH price at the end of the 15m window is at least the one at its start.",
      "total_pnl": "48.750000",
      "outcomes": [
        {
          "market_id": 4206,
          "symbol": "ETH-UPDOWN-15M-1792436400",
          "outcome": 2,
          "end_timestamp": 1792437300000,
          "settlement_pnl": "49.000000",
          "last_trade_id": 41804794,
          "total_pnl": "48.750000"
        }
      ]
    }
  ]
}
```

`settlement_pnl` stays `null` until the market settles with a position. `total_pnl` includes all realized PnL, including settlement, **gross of fees**: exit or settlement notional minus entry quote. Trading fees are not subtracted. To calculate net PnL, account for fees separately from the trade records. The response above is an example; IDs, prices and PnL depend on the account and event.


---

# 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.lighter.xyz/developers/binary-options/positions-and-settlement.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.