> For the complete documentation index, see [llms.txt](https://docs.pearprotocol.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pearprotocol.io/api-integration/api-specification/markets.md).

# Markets

## Get markets data

> Retrieve market groups including active markets, top gainers, top losers, highlighted markets, and watchlist

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/markets":{"get":{"description":"Retrieve market groups including active markets, top gainers, top losers, highlighted markets, and watchlist","operationId":"MarketsController_getMarkets","parameters":[{"name":"offset","required":false,"in":"query","description":"Offset for pagination","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number for pagination (minimum 1)","schema":{"type":"string"}},{"name":"pageSize","required":false,"in":"query","description":"Page size (items per page, maximum 100)","schema":{"type":"string"}},{"name":"engine","required":false,"in":"query","description":"Filter by engine type","schema":{"type":"string"}},{"name":"minVolume","required":false,"in":"query","description":"Filter by minimum volume","schema":{"type":"string"}},{"name":"change24h","required":false,"in":"query","description":"Filter by price change","schema":{"type":"string"}},{"name":"netFunding","required":false,"in":"query","description":"Filter by either positive or negative funding rate","schema":{"type":"string"}},{"name":"searchText","required":false,"in":"query","description":"Search text to filter markets","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field and direction (e.g., volume:desc)","schema":{"type":"string"}},{"name":"excludeText","required":false,"in":"query","description":"Text to exclude from results","schema":{"type":"string"}},{"name":"active","required":false,"in":"query","description":"Filter by active status","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved markets data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketsResponse"}}}},"400":{"description":"Bad request - Invalid query parameters"}},"summary":"Get markets data","tags":["Markets"]}}},"components":{"schemas":{"MarketsResponse":{"type":"object","properties":{"markets":{"description":"List of active order-asset groups","type":"array","items":{"$ref":"#/components/schemas/MarketsGroupItem"}},"total":{"type":"number","description":"Total number of markets (after filters)"},"page":{"type":"number","description":"Page number for pagination"},"pageSize":{"type":"number","description":"Page size (items per page)"},"totalPages":{"type":"number","description":"Total number of pages"}},"required":["markets","total","page","pageSize","totalPages"]},"MarketsGroupItem":{"type":"object","properties":{"longAssets":{"description":"Distinct long assets in the order group with weights","type":"array","items":{"$ref":"#/components/schemas/PairAssetDto"}},"shortAssets":{"description":"Distinct short assets in the order group with weights","type":"array","items":{"$ref":"#/components/schemas/PairAssetDto"}},"openInterest":{"type":"string","description":"Open interest in USD for all assets in this group"},"volume":{"type":"string","description":"24h traded volume in USD for this order group"},"ratio":{"type":"string","description":"Current long/short ratio for this group"},"prevRatio":{"type":"string","description":"Previous day long/short ratio for this group"},"change24h":{"type":"string","description":"24h change as decimal (e.g. 0.05 = +5%)"},"weightedRatio":{"type":"string","description":"Weighted (synthetic 50/50) current ratio for this group"},"weightedPrevRatio":{"type":"string","description":"Weighted (synthetic 50/50) previous day ratio for this group"},"weightedChange24h":{"type":"string","description":"Weighted (synthetic 50/50) 24h change as decimal"},"netFunding":{"type":"string","description":"Net funding for the basket, weighted by allocation (longs negative, shorts positive)"}},"required":["longAssets","shortAssets","openInterest","volume","netFunding"]},"PairAssetDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol"},"weight":{"type":"number","description":"Weight allocation for this asset (0.0001 to 1.0). If not provided, weights will be evenly distributed.","minimum":0.0001,"maximum":1}},"required":["asset"]}}}}
```

## GET /markets/active

> Get active market assets and pairs

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/markets/active":{"get":{"operationId":"MarketsController_getActiveMarket","parameters":[],"responses":{"200":{"description":"Market data retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveAssetsResponse"}}}}},"summary":"Get active market assets and pairs","tags":["Markets"]}}},"components":{"schemas":{"ActiveAssetsResponse":{"type":"object","properties":{"active":{"description":"List of actively traded order-asset groups","type":"array","items":{"$ref":"#/components/schemas/ActiveAssetGroupItem"}},"topGainers":{"description":"Top gaining long/short pairs over 24h","type":"array","items":{"$ref":"#/components/schemas/ActiveAssetGroupItem"}},"topLosers":{"description":"Top losing long/short pairs over 24h","type":"array","items":{"$ref":"#/components/schemas/ActiveAssetGroupItem"}},"highlighted":{"description":"Highlighted long/short pairs","type":"array","items":{"$ref":"#/components/schemas/ActiveAssetGroupItem"}},"watchlist":{"description":"User watchlist long/short pairs","type":"array","items":{"$ref":"#/components/schemas/ActiveAssetGroupItem"}}},"required":["active","topGainers","topLosers","highlighted","watchlist"]},"ActiveAssetGroupItem":{"type":"object","properties":{"key":{"type":"string","description":"Unique identifier for the order group"},"longAssets":{"description":"Distinct long assets in the order group with weights","type":"array","items":{"$ref":"#/components/schemas/PairAssetDto"}},"shortAssets":{"description":"Distinct short assets in the order group with weights","type":"array","items":{"$ref":"#/components/schemas/PairAssetDto"}},"openInterest":{"type":"string","description":"Open interest in USD for all assets in this group"},"volume":{"type":"string","description":"24h traded volume in USD for this order group"},"ratio":{"type":"string","description":"Current long/short ratio for this group"},"prevRatio":{"type":"string","description":"Previous day long/short ratio for this group"},"change24h":{"type":"string","description":"24h change as decimal (e.g. 0.05 = +5%)"},"weightedRatio":{"type":"string","description":"Weighted (synthetic 50/50) current ratio for this group"},"weightedPrevRatio":{"type":"string","description":"Weighted (synthetic 50/50) previous day ratio for this group"},"weightedChange24h":{"type":"string","description":"Weighted (synthetic 50/50) 24h change as decimal"},"netFunding":{"type":"string","description":"Net funding for the basket, weighted by allocation (longs negative, shorts positive)"}},"required":["key","longAssets","shortAssets","openInterest","volume","netFunding"]},"PairAssetDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol"},"weight":{"type":"number","description":"Weight allocation for this asset (0.0001 to 1.0). If not provided, weights will be evenly distributed.","minimum":0.0001,"maximum":1}},"required":["asset"]}}}}
```

## GET /markets/v2

> Get market data v2 (actives + watchlist baskets)

```json
{"openapi":"3.0.0","info":{"title":"Pear Protocol Trading API","version":"1.0.0"},"servers":[{"url":"https://hl-v2.pearprotocol.io","description":"Production (Mainnet)"}],"paths":{"/markets/v2":{"get":{"operationId":"MarketsController_getMarketDataV2","parameters":[],"responses":{"200":{"description":"Market data v2 retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketDataV2Response"}}}}},"summary":"Get market data v2 (actives + watchlist baskets)","tags":["Markets"]}}},"components":{"schemas":{"MarketDataV2Response":{"type":"object","properties":{"baskets":{"description":"List of baskets","type":"array","items":{"$ref":"#/components/schemas/MarketDataV2BasketDto"}}},"required":["baskets"]},"MarketDataV2BasketDto":{"type":"object","properties":{"longAssets":{"description":"Long assets with weights","type":"array","items":{"$ref":"#/components/schemas/MarketDataV2AssetDto"}},"shortAssets":{"description":"Short assets with weights","type":"array","items":{"$ref":"#/components/schemas/MarketDataV2AssetDto"}},"category":{"type":"string","description":"Basket category","enum":["active","watchlist","ai-picks"]},"name":{"type":"string","description":"Optional basket name"}},"required":["longAssets","shortAssets","category"]},"MarketDataV2AssetDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol"},"weight":{"type":"number","description":"Weight allocation"}},"required":["asset","weight"]}}}}
```