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

# List global markets perps positions

> List open perpetual futures positions for a user.

Returns position data including size, entry price, mark price, PnL, liquidation price,
leverage, and cumulative funding. Optionally filter by asset ticker.
Returns an empty list if no positions are open.



## OpenAPI

````yaml /v2/combined_spec.json get /v2/global_markets_perps/positions
openapi: 3.1.0
info:
  title: Compass API
  description: Compass Labs DeFi API
  version: 0.0.1
servers:
  - url: https://api.compasslabs.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /v2/global_markets_perps/positions:
    get:
      tags:
        - Global Markets Perps
      summary: List global markets perps positions
      description: >-
        List open perpetual futures positions for a user.


        Returns position data including size, entry price, mark price, PnL,
        liquidation price,

        leverage, and cumulative funding. Optionally filter by asset ticker.

        Returns an empty list if no positions are open.
      operationId: v2_global_markets_perps_positions
      parameters:
        - name: owner
          in: query
          required: true
          schema:
            type: string
            title: Owner
            default: '0x06A9aF046187895AcFc7258450B15397CAc67400'
          description: >-
            User's EOA address (looks up their global markets perps product
            account)
        - name: asset
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Asset
            default: null
          description: Filter to a specific asset ticker (e.g. AAPL)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalMarketsPerpsPositionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: python
          label: Python (SDK)
          source: |-
            from compass_api_sdk import CompassAPI


            with CompassAPI(
                api_key_auth="<YOUR_API_KEY_HERE>",
            ) as compass_api:

                res = compass_api.global_markets_perps.global_markets_perps_positions(owner="0x06A9aF046187895AcFc7258450B15397CAc67400")

                # Handle response
                print(res)
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { CompassApiSDK } from "@compass-labs/api-sdk";

            const compassApiSDK = new CompassApiSDK({
              apiKeyAuth: "<YOUR_API_KEY_HERE>",
            });

            async function run() {
              const result = await compassApiSDK.globalMarketsPerps.globalMarketsPerpsPositions({
                owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
              });

              console.log(result);
            }

            run();
components:
  schemas:
    GlobalMarketsPerpsPositionsResponse:
      properties:
        positions:
          items:
            $ref: '#/components/schemas/GlobalMarketsPerpsPosition'
          type: array
          title: Positions
          description: Open perpetual futures positions
        account_value:
          type: string
          title: Account Value
          description: Total account value in USD (margin + unrealized PnL)
          default: '0'
        withdrawable:
          type: string
          title: Withdrawable
          description: Available USDC balance (withdrawable margin)
          default: '0'
      type: object
      required:
        - positions
      title: GlobalMarketsPerpsPositionsResponse
      description: List of open global markets perps positions with account balance.
      example:
        account_value: '1058.32'
        positions:
          - asset: AAPL
            asset_id: 12
            entry_price: '212.40'
            funding_accrued: '-0.12'
            leverage: '3'
            liquidation_price: '180.12'
            margin_used: '354.00'
            mark_price: '213.88'
            side: long
            size: '5.00'
            unrealized_pnl: '7.40'
        withdrawable: '704.32'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GlobalMarketsPerpsPosition:
      properties:
        asset:
          type: string
          title: Asset
          description: Asset ticker symbol
        asset_id:
          type: integer
          title: Asset Id
          description: Hyperliquid asset index
        side:
          type: string
          enum:
            - long
            - short
          title: Side
          description: 'Position side: ''long'' or ''short'''
        size:
          type: string
          title: Size
          description: Position size in contracts
        entry_price:
          type: string
          title: Entry Price
          description: Average entry price
        mark_price:
          type: string
          title: Mark Price
          description: Current mark price
        liquidation_price:
          anyOf:
            - type: string
            - type: 'null'
          title: Liquidation Price
          description: Estimated liquidation price
        unrealized_pnl:
          type: string
          title: Unrealized Pnl
          description: Unrealized PnL in USD
        leverage:
          type: string
          title: Leverage
          description: Current leverage
        margin_used:
          type: string
          title: Margin Used
          description: Margin used for this position in USD
        funding_accrued:
          type: string
          title: Funding Accrued
          description: Cumulative funding payments (negative = paid)
      type: object
      required:
        - asset
        - asset_id
        - side
        - size
        - entry_price
        - mark_price
        - unrealized_pnl
        - leverage
        - margin_used
        - funding_accrued
      title: GlobalMarketsPerpsPosition
      description: A single open perpetual futures position.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Compass API Key. Get your key
        [here](https://www.compasslabs.ai/dashboard).

````