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

# Open positions in a market

> Open positions of one market, long, short or both, sorted by notional or another field.



## OpenAPI

````yaml /data-api/openapi.json get /v1/markets/{coin}/positions
openapi: 3.1.0
info:
  title: Hyperdash Data API
  version: v1
  description: >-
    Hyperliquid data from Hyperdash's own nodes and stored datasets; requests
    never call Hyperliquid's public API. Every response reports the credits it
    cost.
servers:
  - url: https://data.hyperdash.com
security: []
tags:
  - name: Accounts
  - name: Async jobs
  - name: Builders
  - name: Cohorts
  - name: HIP-3 dexes
  - name: Leaderboards
  - name: Lending
  - name: Liquidations
  - name: Markets
  - name: 'Markets: analytics'
  - name: 'Markets: funding'
  - name: 'Markets: liquidation and stop levels'
  - name: 'Markets: open interest and positioning'
  - name: 'Markets: order book'
  - name: 'Markets: prices and candles'
  - name: 'Markets: queue priority'
  - name: 'Markets: trades and flow'
  - name: 'Markets: TWAPs'
  - name: Network
  - name: Outcomes
  - name: Positions
  - name: Referrals
  - name: Snapshots
  - name: Spot
  - name: Staking
  - name: Traders
  - name: Vaults
paths:
  /v1/markets/{coin}/positions:
    get:
      tags:
        - 'Markets: open interest and positioning'
      summary: Open positions in a market
      description: >-
        Open positions of one market, long, short or both, sorted by notional or
        another field.


        **Fields**

        - `meta` has the counts and notionals of the positions matching every
        filter: `total_count`, and per side as asked.

        - `meta` also has the long and short tab badges in `badge_*`. They apply
        the range filters only, whatever `side` is.

        - `block_time` is the block, in epoch ms, that the positions state
        reflects.

        - `computed_at` is when the server computed it.

        - `mark` is the price positions are valued at. For core-exchange
        markets, it is Hyperliquid's own mark from the validators' latest price
        update, at most 20 seconds old, rounded to 5 significant figures as
        Hyperliquid publishes it.

        - For HIP-3 markets, or when that update is older than 20 seconds,
        `mark` is the median of the fresh sources among the last trade (at most
        about 10 seconds old), the reference oracle and, for core markets, that
        update's average of oracle and mark. With two fresh sources it is their
        midpoint, and with one it is that source.

        - A row with `margin_uncertain` set to `true` has a `null` liquidation
        price and account value. Its margin is certified again at the engine's
        next state snapshot, about every 12 minutes. When the position itself
        was opened since the last snapshot, `leverage` and `leverage_type` are
        `null` too.


        **Filters**

        - Optional ranges apply to notional, entry, liquidation price,
        unrealized PnL and account value. Bounds are inclusive.

        - A position without a liquidation price fails any liquidation bound.

        - An unknown account value filters as 0.


        **Notes**

        - The range filters are the asset page's filters on hyperdash.com.


        **Credits:** 10 per request + 1 per row.


        **Scope:** `markets:read`
      operationId: getMarketPositions
      parameters:
        - name: coin
          in: path
          required: true
          description: Perp market, for example `BTC` or `xyz:TSLA`.
          schema:
            type: string
        - name: side
          in: query
          required: false
          description: Position side.
          schema:
            type: string
            default: all
            enum:
              - all
              - long
              - short
        - name: sort
          in: query
          required: false
          description: Field to sort by.
          schema:
            type: string
            default: notional
            enum:
              - notional
              - entry_px
              - liquidation_px
              - unrealized_pnl
              - funding_pnl
              - account_value
              - address
        - name: order
          in: query
          required: false
          description: Sort order. Use `asc` for A to Z addresses.
          schema:
            type: string
            default: desc
            enum:
              - desc
              - asc
        - name: min_notional
          in: query
          required: false
          description: Minimum notional at mark in USD, inclusive.
          schema:
            type: string
        - name: max_notional
          in: query
          required: false
          description: Maximum notional at mark in USD, inclusive.
          schema:
            type: string
        - name: min_entry_px
          in: query
          required: false
          description: Minimum entry price, inclusive.
          schema:
            type: string
        - name: max_entry_px
          in: query
          required: false
          description: Maximum entry price, inclusive.
          schema:
            type: string
        - name: min_liquidation_px
          in: query
          required: false
          description: Minimum liquidation price, inclusive.
          schema:
            type: string
        - name: max_liquidation_px
          in: query
          required: false
          description: Maximum liquidation price, inclusive.
          schema:
            type: string
        - name: min_unrealized_pnl
          in: query
          required: false
          description: Minimum unrealized PnL in USD, inclusive.
          schema:
            type: string
        - name: max_unrealized_pnl
          in: query
          required: false
          description: Maximum unrealized PnL in USD, inclusive.
          schema:
            type: string
        - name: min_account_value
          in: query
          required: false
          description: Minimum account value in USD, inclusive.
          schema:
            type: string
        - name: max_account_value
          in: query
          required: false
          description: Maximum account value in USD, inclusive.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Rows per page.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: cursor
          in: query
          required: false
          description: Opaque cursor from `next_cursor`.
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            X-Credits-Charged:
              schema:
                type: integer
            X-Credit-Price-Version:
              schema:
                type: integer
            X-Request-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - has_more
                  - next_cursor
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        address:
                          type: string
                          description: Wallet.
                        side:
                          type: string
                          description: '`long` or `short`.'
                        size:
                          type: string
                          description: Signed size. Negative means short. Decimal string.
                        notional:
                          type: string
                          description: Notional at mark, in USD. Decimal string.
                        entry_px:
                          type: string
                          description: Entry price. Decimal string.
                        liquidation_px:
                          type:
                            - string
                            - 'null'
                          description: Liquidation price. Decimal string.
                        unrealized_pnl:
                          type: string
                          description: Unrealized PnL. Decimal string.
                        funding_pnl:
                          type: string
                          description: >-
                            Funding since the position opened, in USD. Received
                            funding is above 0. Decimal string.
                        account_value:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Equity of the margin pool behind this position, in
                            USD. This is the value its liquidation is judged on,
                            not the wallet's total. A cross position carries its
                            account's cross account value on the position's dex;
                            for unified and portfolio-margin accounts that is
                            their one account-wide pool, spot collateral
                            included. An isolated position carries its own
                            isolated margin plus unrealized PnL. A wallet's rows
                            can therefore differ. Decimal string.
                        leverage:
                          type:
                            - integer
                            - 'null'
                          description: >-
                            Leverage setting. `null` when `margin_uncertain` is
                            `true` and the position was opened since the last
                            state snapshot.
                        leverage_type:
                          type:
                            - string
                            - 'null'
                          description: >-
                            `cross` or `isolated`. `null` when
                            `margin_uncertain` is `true` and the position was
                            opened since the last state snapshot.
                        margin_uncertain:
                          type:
                            - boolean
                            - 'null'
                          description: >-
                            `true` when the position's margin is not certified
                            yet: it was opened since the engine's last state
                            snapshot (about every 12 minutes), it is a cross
                            position sharing its margin pool with one, or a fill
                            since then left its pool below the maintenance
                            requirement, which means an input such as a deposit
                            or transfer is missing (portfolio-margin pools
                            excepted). Its liquidation price and account value
                            are then `null`, and so are `leverage` and
                            `leverage_type` when the position itself was opened
                            since then. It is left out of the liquidation levels
                            until the next snapshot. `null` when the positions
                            server does not report it.
                    description: Result rows.
                  has_more:
                    type: boolean
                    description: '`true` when another page follows.'
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Cursor for the next page, passed as `cursor`. `null` on
                      the last page.
                  meta:
                    type: object
                    description: >-
                      Response metadata. Its keys depend on the endpoint and are
                      described above.
        '400':
          description: 'Invalid parameter (also: a request body that is not valid JSON)'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Invalid, expired or revoked key
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Scope, plan, history or credit limit
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found: an unknown market, dex or token'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Price version changed, or a cursor's snapshot expired
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: >-
            Rate limited (Retry-After; free): request rate, concurrent requests
            (a request counts one slot per 1,000 rows it can return), or this
            server busy with your workspace's requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Upstream data source failed (free; retry later)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Backend at capacity or temporarily unavailable (Retry-After)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '504':
          description: Upstream data source timed out (free; retry later)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearer: []
      x-codeSamples:
        - lang: curl
          source: >-
            curl -H "Authorization: Bearer $HYPERDASH_API_KEY"
            'https://data.hyperdash.com/v1/markets/BTC/positions?side=long&limit=50'
components:
  schemas:
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - code
        - request_id
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        code:
          type: string
        detail:
          type: string
        hint:
          type: string
        request_id:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Your API key, sent as `Bearer hdk_sk_live_v1_…`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.