> ## Documentation Index > Fetch the complete documentation index at: https://docs.fairground.fi/llms.txt > Use this file to discover all available pages before exploring further. # GetOpenPositionsStreaming > Server-streaming endpoint. Opens a long-lived Connect/gRPC-Web stream and sends a `GetOpenPositionsStreamingResponse` message immediately, then again on a fixed interval, until the client disconnects. Each message is a full snapshot of the wallet's currently open positions, not a diff. `update_interval_ms` defaults to 250ms when omitted, and is clamped to the 100–60000ms range rather than rejected. NOTE: Mintlify's request-based API explorer cannot exercise a real streaming response. ## OpenAPI ````yaml /developers/api-reference/openapi.yaml post /position_service.v1.PositionService/GetOpenPositionsStreaming openapi: 3.1.0 info: title: Fairground.Fi API description: | API for the Fairground Perpetuals trading platform. This API uses ConnectRPC which accepts JSON over HTTP POST requests. All service endpoints follow the pattern: `/package.ServiceName/MethodName` version: 1.0.0 contact: name: Forte Service Company url: https://github.com/Forte-Service-Company-Ltd/perpetuals-api-server license: name: Proprietary identifier: UNLICENSED servers: - url: https://api.fairground.fi description: Production API server security: - bearerAuth: [] tags: - name: Trades description: Wallet trade/fill history - name: Markets description: Market configuration and summary endpoints - name: Orderbook description: Orderbook data retrieval - name: Orders description: Order management operations - name: Portfolio description: Aggregated per-wallet portfolio data - name: Positions description: Position management operations - name: Prices description: Oracle price and historical price data paths: /position_service.v1.PositionService/GetOpenPositionsStreaming: post: tags: - Positions summary: GetOpenPositionsStreaming description: |- Server-streaming endpoint. Opens a long-lived Connect/gRPC-Web stream and sends a `GetOpenPositionsStreamingResponse` message immediately, then again on a fixed interval, until the client disconnects. Each message is a full snapshot of the wallet's currently open positions, not a diff. `update_interval_ms` defaults to 250ms when omitted, and is clamped to the 100–60000ms range rather than rejected. NOTE: Mintlify's request-based API explorer cannot exercise a real streaming response. operationId: position_service.v1.PositionService.GetOpenPositionsStreaming parameters: - name: Connect-Protocol-Version in: header required: true schema: $ref: '#/components/schemas/connect-protocol-version' - name: Connect-Timeout-Ms in: header schema: $ref: '#/components/schemas/connect-timeout-header' requestBody: content: application/json: schema: $ref: >- #/components/schemas/position_service.v1.GetOpenPositionsStreamingRequest required: true responses: '200': description: >- One streamed message (the server sends a sequence of these, not a single response). content: application/json: schema: $ref: >- #/components/schemas/position_service.v1.GetOpenPositionsStreamingResponse example: positions: - owner: '0x71c7656ec7ab88b098defb751b7401b5f6d8976' positionId: '48213' marketId: '1' timestamp: '2026-07-11T14:32:07Z' market: BTC-PERP side: SIDE_LONG marginType: MARGIN_TYPE_ISOLATED nominalSize: 0.1538 entryPrice: 65000.5 markPrice: 65420 liquidationPrice: 54200 allocatedMargin: 2000 leverage: 5 unrealizedPnl: 64.6 reduceOnly: false associatedOrders: [] associatedOrderIds: - orderId: '50501' marketId: '1' reduceOnly: true tickDecimals: 1 revenueSpent: 12.5 effectiveSize: 0.1538 estimatedRebate: 3.2 stopLossPrice: 60000 takeProfitPrice: 72000 components: schemas: connect-protocol-version: type: number title: Connect-Protocol-Version enum: - 1 description: Define the version of the Connect protocol. If omitted, use 1. const: 1 default: 1 connect-timeout-header: type: number title: Connect-Timeout-Ms description: Define the timeout, in ms position_service.v1.GetOpenPositionsStreamingRequest: type: object properties: address: type: string title: address description: >- Wallet address to stream open positions for. Trimmed and matched case-insensitively. updateIntervalMs: type: - integer - 'null' title: update_interval_ms description: |- Interval between stream updates, in milliseconds. Defaults to 250 when omitted or zero, and is clamped to the 100–60000 range. title: GetOpenPositionsStreamingRequest required: - address additionalProperties: false position_service.v1.GetOpenPositionsStreamingResponse: type: object properties: positions: type: array items: $ref: '#/components/schemas/base_objects.v1.Position' title: positions description: |- Full snapshot of `address`'s open positions as of this message. Not a diff against the previous message. title: GetOpenPositionsStreamingResponse additionalProperties: false base_objects.v1.Position: type: object properties: owner: type: string title: owner description: Lowercase EVM wallet address that owns the position. positionId: type: string title: position_id format: int64 description: |- On-chain position identifier. The same ID as the order that opened the position. marketId: type: string title: market_id format: int64 description: On-chain market identifier. timestamp: $ref: '#/components/schemas/google.protobuf.Timestamp' title: timestamp description: >- Timestamp of the most recent event applied to this position (open, margin update, or size update). market: type: string title: market description: Human-readable market name, such as `BTC-PERP`. side: $ref: '#/components/schemas/base_objects.v1.Side' title: side description: Position direction, from the on-chain `isLong` flag. marginType: $ref: '#/components/schemas/base_objects.v1.MarginType' title: margin_type description: >- Margin mode for this position. Currently always `MARGIN_TYPE_ISOLATED` — all positions are isolated-margin on-chain. nominalSize: type: number title: nominalSize format: float description: Position size in the base asset's units. entryPrice: type: number title: entry_price format: float description: Average entry price in quote asset units. markPrice: type: number title: mark_price format: float description: Current mark price in quote asset units. liquidationPrice: type: number title: liquidation_price format: float description: >- Estimated liquidation price in quote asset units. Not a stored on-chain value. allocatedMargin: type: number title: allocated_margin format: float description: >- Current collateral allocated to the position, in quote asset units, including any margin adds or removes since the position opened. leverage: type: number title: leverage format: float description: Leverage multiplier used to open the position. unrealizedPnl: type: number title: unrealized_pnl format: float description: >- Unrealized profit or loss in quote asset units, derived from `markPrice` vs. `entryPrice`. Recomputed on every read, not a stored value. reduceOnly: type: boolean title: reduce_only description: |- Legacy field mirrored from the position's on-chain open/update events. Not generally meaningful at the position level — see `associatedOrders` for the position's individual reduce-only orders. associatedOrders: type: array items: $ref: '#/components/schemas/base_objects.v1.Order' title: associated_orders description: Orders associated with this position (opening and reduce-only). associatedOrderIds: type: array items: $ref: '#/components/schemas/base_objects.v1.OrderRef' title: associated_order_ids description: Lightweight identifiers for orders associated with this position. tickDecimals: type: integer title: tick_decimals description: Market price precision used to convert raw on-chain price values. revenueSpent: type: number title: revenue_spent format: float description: |- Revenue-per-unit snapshot recorded when the position opened. The position's total earned revenue at close time is `market_revenue - revenue_spent`. effectiveSize: type: number title: effectiveSize format: float description: |- Currently always equal to `nominalSize`. Intended to eventually scale by an ADL scale factor (`position.adl_scale_factor / market.adl_scale_factor`), but that scaling is not yet implemented server-side. estimatedRebate: type: number title: estimated_rebate format: float description: >- Estimated rebate accrued to this position so far, in quote asset units — the market's current cumulative revenue-per-unit for this position's side, minus `revenueSpent`. Returns `0` if the underlying revenue data isn't available yet, or `-1` if the market itself can't be loaded. stopLossPrice: type: number title: stop_loss_price format: float description: >- Stop-loss trigger price derived from this position's active reduce orders, in quote asset units. Zero when no stop-loss is configured takeProfitPrice: type: number title: take_profit_price format: float description: >- Take-profit trigger price derived from this position's active reduce orders, in quote asset units. Zero when no take-profit is configured title: Position additionalProperties: false description: >- Current stored state of a position. For closed positions, `markPrice`, `liquidationPrice`, `unrealizedPnl`, and `estimatedRebate` are still computed against live market data, so they don't reflect conditions at the time the position closed. google.protobuf.Timestamp: type: string examples: - '2023-01-15T01:30:15.01Z' - '2024-12-25T12:00:00Z' format: date-time base_objects.v1.Side: type: string title: Side enum: - SIDE_LONG - SIDE_SHORT description: Direction of the position represented by an order. base_objects.v1.MarginType: type: string title: MarginType enum: - MARGIN_TYPE_ISOLATED base_objects.v1.Order: type: object properties: owner: type: string title: owner description: Lowercase EVM wallet address that owns the order. orderId: type: string title: order_id format: int64 description: >- On-chain order identifier. Unique together with `marketId` and `reduceOnly`. Connect/JSON encodes this uint64 as a decimal string. timestamp: $ref: '#/components/schemas/google.protobuf.Timestamp' title: timestamp description: >- Order-creation timestamp from the submission event, in RFC 3339 format. marketId: type: string title: market_id format: int64 description: |- On-chain market identifier. Connect/JSON encodes this uint64 as a decimal string. market: type: string title: market description: >- Human-readable market name, such as `BTC-PERP`. Falls back to `MARKET-{marketId}` when market metadata is unavailable. type: $ref: '#/components/schemas/base_objects.v1.OrderType' title: type description: Order-type classification. Currently always `ORDER_TYPE_MARKET`. side: $ref: '#/components/schemas/base_objects.v1.Side' title: side description: >- Position direction. For reduce-only orders, inherited from the associated position-opening order. thresholdPrice: type: number title: threshold_price format: float description: >- Execution price threshold in quote asset terms per underlying asset. Converted using the market's tick precision. This is not necessarily the fill price. size: type: number title: size format: float description: Amount exposed for the order. leverage: type: number title: leverage format: float description: >- Leverage multiplier. For reduce-only orders, inherited from the associated position-opening order when available. status: $ref: '#/components/schemas/base_objects.v1.OrderStatus' title: status description: Current order lifecycle state. filledSize: type: number title: filled_size format: float description: Order Amount that has been filled unfilledSize: type: number title: unfilled_size format: float description: Order amount remaining to be filled reduceOnly: type: boolean title: reduce_only description: >- Whether the order is reducing an existing position. False for orders that open or increase exposure; true for orders that reduce exposure. canceled: type: boolean title: canceled description: |- Legacy field that the server does not populate. Use `status` to determine whether an order was cancelled. initialMargin: type: number title: initial_margin format: float description: >- Initial collateral or threshold-price notional, denominated in quote asset units. For position-opening orders, this is the initial collateral. tickDecimals: type: integer title: tick_decimals description: Market price precision used to convert raw on-chain price values. fees: type: number title: fees format: float description: Fees recorded for the order, denominated in quote asset units. rebates: type: number title: rebates format: float description: >- Direct order-side rebates recorded for reduce fills, denominated in quote asset units. reduceOrderType: type: string title: reduce_order_type description: >- Reduce-order classification. Values are `MANUAL`, `STOP_LOSS`, `TAKE_PROFIT`, `LIQUIDATION`, or `ADL`. Empty for position-opening orders. initialNotional: type: number title: initial_notional format: float description: >- Initial notional amount for a position-opening order. Calculated as `initialMargin * leverage`. Zero for reduce-only orders. stopLossPrice: type: number title: stop_loss_price format: float description: >- Stop-loss trigger price attached to a position-opening order, in quote asset units. Zero when no stop-loss is configured. takeProfitPrice: type: number title: take_profit_price format: float description: >- Take-profit trigger price attached to a position-opening order, in quote asset units. Zero when no take-profit is configured. title: Order additionalProperties: false description: |- Current stored state of a position-opening or reduce-only order. Because both order kinds share this message, some numeric fields have different meanings and units. Use `reduceOnly` when interpreting them. base_objects.v1.OrderRef: type: object properties: orderId: type: - integer - string title: order_id format: int64 description: >- On-chain order identifier. Combine with `marketId` and `reduceOnly` to look up the full order via `GetOrder`. marketId: type: - integer - string title: market_id format: int64 description: Market the referenced order belongs to. reduceOnly: type: boolean title: reduce_only description: Whether the referenced order is reduce-only. title: OrderRef additionalProperties: false description: >- OrderRef is a lightweight reference to an order by its composite primary key (order_id, market_id, reduce_only). Used where only the identity of related orders is needed (e.g. Position.associated_order_ids), so clients can resolve full order details from the orders stream without shipping full Order objects (and the misleading proto3 default values that come with sparsely-populated Order messages). base_objects.v1.OrderType: type: string title: OrderType enum: - ORDER_TYPE_MARKET description: >- Order-type classification used by the API. Currently only market orders are returned. base_objects.v1.OrderStatus: type: string title: OrderStatus enum: - ORDER_STATUS_PENDING - ORDER_STATUS_PARTIALLY_FILLED - ORDER_STATUS_FULLY_FILLED - ORDER_STATUS_CLOSED - ORDER_STATUS_CANCELLED - ORDER_STATUS_MERGED - ORDER_STATUS_PARTIALLY_MERGED - ORDER_STATUS_PARTIALLY_CANCELLED description: Current lifecycle state of an order. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````