> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ekiden.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Position Info

> Query real-time position data, such as position size, cumulative realized PNL, etc.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/position/list
openapi: 3.1.0
info:
  title: ekiden-gateway
  description: >-
    API Gateway and WebSocket proxy based on Axum and Utoipa, handling auth,
    rate limiting, and connection buffering.
  license:
    name: ''
  version: 0.1.1
servers:
  - url: https://api.ekiden.fi/
    description: Production
  - url: https://api.staging.ekiden.fi/
    description: Staging
  - url: https://api.dev.ekiden.fi/
    description: Development
  - url: http://localhost:4020/
    description: Local
security: []
paths:
  /api/v1/position/list:
    get:
      tags:
        - Position
      summary: Get Position Info
      description: >-
        Query real-time position data, such as position size, cumulative
        realized PNL, etc.
      operationId: get_position_info
      parameters:
        - name: sub_account_address
          in: query
          description: Trading vault address (subaccount) to query against.
          required: true
          schema:
            type: string
        - name: symbol
          in: query
          required: false
          schema:
            oneOf:
              - type: 'null'
              - $ref: '#/components/schemas/Symbol'
        - name: limit
          in: query
          required: false
          schema:
            type:
              - integer
              - 'null'
            format: int32
            minimum: 0
        - name: cursor
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: Positions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPositionInfoResponse'
      security:
        - bearer_auth: []
components:
  schemas:
    Symbol:
      type: string
      example: BTCUSDC
    GetPositionInfoResponse:
      type: object
      description: Position info response.
      required:
        - list
        - next_page_cursor
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Position'
        next_page_cursor:
          type: string
          description: >-
            Cursor. Use the next_page_cursor token from the response to retrieve
            the next page of the data set
    Position:
      type: object
      description: >-
        Position information.


        * risk_id: numeric identifier of the current risk tier your position is
        on for that symbol.

        * risk_limit_value: the maximum position value allowed under that tier
        (the tier’s limit). If your position value grows beyond this, the tier
        steps up (higher requirements).


        Details:

        * Meaning: Bybit enforces “risk limit tiers” to cap position value and
        scale maintenance margin. The tier is referenced by riskId, and its cap
        is riskLimitValue.

        * Effects: Higher tiers allow larger positions but increase maintenance
        margin and may constrain leverage.

        * Portfolio margin note: In portfolio margin mode, both fields are not
        meaningful and are returned as 0 (docs: “risk limit rules are invalid”).
      required:
        - risk_id
        - risk_limit_value
        - symbol
        - sub_account_address
        - side
        - size
        - avg_price
        - position_value
        - margin_mode
        - position_balance
        - position_status
        - leverage
        - mark_price
        - liq_price
        - bust_price
        - position_im
        - position_im_by_mp
        - position_mm
        - position_mm_by_mp
        - unrealized_pnl
        - unrealized_funding
        - realized_pnl_cur
        - realized_pnl_cum
        - cum_funding
        - adl_rank_indicator
        - is_reduce_only
        - created_time
        - updated_time
        - seq
      properties:
        adl_rank_indicator:
          $ref: '#/components/schemas/AdlRankIndicator'
          description: Auto-deleverage rank indicator.
        avg_price:
          type: string
          description: Average entry price.
        bust_price:
          type: string
          description: Bankruptcy price
        created_time:
          type: string
          format: date-time
          description: >-
            Timestamp of the first time a position was created on this symbol
            (ms)
          example: '1672531200000'
        cum_funding:
          type: string
          description: >-
            Net realized funding PnL accumulated for this position (receive
            positive, pay negative).
        is_reduce_only:
          type: boolean
        leverage:
          type: string
          description: Position leverage
        leverage_sys_updated_time:
          type:
            - string
            - 'null'
          format: date-time
          example: '1672531200000'
        liq_price:
          type: string
          description: Position liquidation price
        margin_mode:
          $ref: '#/components/schemas/MarginMode'
          description: Is position cross margin or isolated margin
        mark_price:
          type: string
          description: Mark price
        mmr_sys_update_time:
          type:
            - string
            - 'null'
          format: date-time
          example: '1672531200000'
        position_balance:
          type: string
          description: Position margin
        position_im:
          type: string
          description: Initial margin
        position_im_by_mp:
          type: string
          description: Initial margin calculated by mark price
        position_mm:
          type: string
          description: Maintenance margin
        position_mm_by_mp:
          type: string
          description: Maintenance margin calculated by mark price
        position_status:
          $ref: '#/components/schemas/PositionStatus'
          description: Position status. Normal, Liq, Adl
        position_value:
          type: string
          description: Position value
        realized_pnl_cum:
          type: string
          description: Sum of all historical Current Realized PnLs (and the latest one).
        realized_pnl_cur:
          type: string
          description: |-
            Sum of Fill Realized PnL for position of this symbol/side
            since this position was created last time
        risk_id:
          type: integer
          format: int32
          description: Risk tier ID
          minimum: 0
        risk_limit_value:
          type: string
          description: Risk limit value
        seq:
          type: integer
          format: int64
          description: >-
            Cross sequence, used to associate each fill and each position update

            * Different symbols may have the same seq, please use seq + symbol
            to check unique
          minimum: 0
        side:
          $ref: '#/components/schemas/Side'
          description: 'Position side. Buy: long, Sell: short'
        size:
          type: string
          description: Position size, always positive
        stop_loss:
          type:
            - string
            - 'null'
          description: Stop loss price
        sub_account_address:
          type: string
        symbol:
          $ref: '#/components/schemas/Symbol'
          description: Symbol name
        take_profit:
          type:
            - string
            - 'null'
          description: Take profit price
        trailing_stop:
          type:
            - string
            - 'null'
          description: Trailing stop (The distance from market price)
        unrealized_funding:
          type: string
          description: >-
            Net unsettled funding PnL for this position (receive positive, pay
            negative).
        unrealized_pnl:
          type: string
          description: |-
            How much USDC an account will receive (or pay if negative)
            if the position is closed at the current MarkPrice
        updated_time:
          type: string
          format: date-time
          description: Position data updated timestamp (ms)
          example: '1672531200000'
    AdlRankIndicator:
      type: string
      description: Auto-deleverage rank indicator.
      enum:
        - Zero
        - One
        - Two
        - Three
        - Four
        - Five
    MarginMode:
      type: string
      enum:
        - Cross
        - Isolated
    PositionStatus:
      type: string
      enum:
        - Normal
        - Liq
        - Adl
    Side:
      type: string
      description: 'Order side: buy or sell.'
      enum:
        - Sell
        - Buy
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer

````