Positions and settlement

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

{
  "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 and in the account_all and account_all_positions WebSocket channels as bo_positions. The account_market channel reports a single market’s position as bo_position. See the linked sections of the WebSocket reference 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 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

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

portfolio_boPnl (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

{
  "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.