> For the complete documentation index, see [llms.txt](https://docs.yifi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yifi.io/docs/earn/core-concepts/market.md). # Market The raw building block underneath a strategy. A market is one specific on-chain vault or pool: an Aave v3 lending pool, a Curve LP pool, a Lido staking contract. It's the raw, protocol-level unit – a strategy is the human-readable wrapper built on top of one or more markets. ### Identity A market is keyed by `market_id`, in **`chain:address` format** – for example `ethereum:0xcd5fe23c85820f7b72d0926fc9b05b43e359b7ee`. It's what you pass to `GET /markets/{market_id}`. ### Fields * **`category`** – what kind of market this is. See the categories table below. * **`platform`** – the protocol operating the market (`aave-v3`, `curve`, `lido`, etc.). Fetch the reference list from `GET /platforms`. * **`chain`** – the network the market's contract lives on. #### Category | `category_id` | Covers | | ------------------- | --------------------------------------------------------------------------- | | `lending` | Overcollateralized lending protocols (Aave, Compound, Euler) | | `dex` | DEX liquidity provision (Uniswap, Curve, Balancer) | | `lst` | Liquid staking protocols (Lido, Rocket Pool, Frax Ether) | | `fixed-income` | Fixed-rate yield products (Pendle) | | `structured-vaults` | Yield-bearing tokens issued by on-chain capital allocators (Veda, Ether.fi) | | `stablecoin` | Stablecoin-specific yield strategies | #### Rate * **`annual_rate`** – the yield rate, as a percent string (`"3.84"` = 3.84%). * **`rate_format`** – whether `annual_rate` is `apy` (compounded) or `apr` (simple). * **`yield_type`** – `floating` (rate moves with market conditions) or `fixed`. * **`tvl_usd`** – total value locked, in USD. #### Participating tokens and roles `participating_tokens[]` lists every token involved in the market, each with a **`role`** describing what it does there: | `role` | Meaning | | ------------ | ------------------------------------------------------------------- | | `INPUT` | The strategy's input token | | `OUTPUT` | The strategy's own token (vault share, pool token, lending receipt) | | `COLLATERAL` | Deposited as collateral in a lending protocol | | `DEBT` | Borrowed token | | `SUPPLY` | Supplied/lent token earning interest | | `REWARD` | Protocol reward or incentive token | | `LP` | Liquidity provider receipt token | ### Historical data For APR/TVL history instead of a snapshot, use `GET /markets/{market_id}/metrics` – up to a year of daily points (`annual_rate`, `tvl_usd` per timestamp). Useful for a yield chart on a market or strategy detail page. ### Example – `GET /markets/{market_id}` ```json { "success": true, "data": { "market_id": "ethereum:0xcd5fe23c85820f7b72d0926fc9b05b43e359b7ee", "name": "Aave v3 weETH", "chain": "ethereum", "platform": "aave-v3", "category": "lending", "annual_rate": "3.84", "tvl_usd": "842000000", "rate_format": "apy", "yield_type": "floating", "participating_tokens": [ { "token_id": "ethereum:0xcd5fe23c85820f7b72d0926fc9b05b43e359b7ee", "symbol": "weETH", "address": "0xCd5fE23C85820F7B72D0926FC9b05b43E359b7ee", "chain": "ethereum", "decimals": 18, "price_usd": "3340.00", "role": "COLLATERAL" } ], "metadata": { "market_address": "0xCd5fE23C85820F7B72D0926FC9b05b43E359b7ee" } }, "error": null } ``` ### Try querying Market yourself! ## List markets > Get paginated markets with filters. ```json {"openapi":"3.1.1","info":{"title":"YiFi Yield Aggregator – Data Gateway API","version":"v1"},"tags":[{"description":"Unified DeFi markets – Staking/LST, DEX, Lending, Fixed Income, Structured Vaults, Stablecoins","name":"Markets"}],"servers":[{"url":"https://core-dev.yifi.io/api/v1"}],"security":[{"BearerToken":[]},{"PartnerApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"description":"Admin key for privileged operations (create/edit/delete).","type":"apiKey","name":"Authorization","in":"header"},"PartnerApiKey":{"description":"Partner API key used for B2B attribution (wallets, platforms). Requests authenticated with this key are attributed to the owning partner.","type":"apiKey","name":"X-Partner-Api-Key","in":"header"}},"schemas":{"rest.Response":{"type":"object","properties":{"code":{"type":"string"},"data":{},"isError":{"type":"boolean"},"message":{"type":"string"},"success":{"type":"boolean"}}},"common.Pagination-core_MarketsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/core.MarketsResponse"}},"page":{"$ref":"#/components/schemas/common.Page"}}},"core.MarketsResponse":{"type":"object","properties":{"annual_rate":{"description":"out of meta for effective search","type":"string"},"category":{"type":"string"},"chain":{"type":"string"},"market_id":{"type":"string"},"name":{"type":"string"},"participating_tokens":{"description":"slice of tokenIDs // no need for more for creating a market","type":"array","items":{"$ref":"#/components/schemas/common.TokenAddress"}},"platform":{"type":"string"},"rate_format":{"type":"string"},"tvl_usd":{"description":"in usd","type":"string"},"yield_type":{"description":"user inserts","type":"string"}}},"common.TokenAddress":{"type":"object","properties":{"address":{"type":"string"},"chain":{"type":"string"},"decimals":{"type":"integer"},"logo_url":{"description":"new","type":"string"},"price_usd":{"type":"string"},"role":{"type":"string"},"symbol":{"type":"string"},"token_id":{"type":"string"}}},"common.Page":{"type":"object","properties":{"currentPage":{"description":"page-based pagination","type":"integer"},"id":{"description":"keyset-based pagination","type":"string"},"limit":{"description":"common","type":"integer"},"nextCursor":{"type":"string"},"offset":{"description":"offset-based pagination","type":"integer"},"pageSize":{"type":"integer"},"prevCursor":{"description":"cursor-based pagination","type":"string"},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"type":{"type":"string"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/markets":{"get":{"description":"Get paginated markets with filters.","tags":["Markets"],"summary":"List markets","parameters":[{"schema":{"type":"string"},"description":"search","name":"search","in":"query"},{"schema":{"type":"string"},"description":"market ids","name":"ids","in":"query"},{"schema":{"type":"string"},"description":"comma separated category ids","name":"categoryIds","in":"query"},{"schema":{"type":"string"},"description":"comma separated platform ids","name":"platformIds","in":"query"},{"schema":{"type":"string"},"description":"comma separated chain ids","name":"chainIds","in":"query"},{"schema":{"type":"string"},"description":"comma separated token ids","name":"tokenIds","in":"query"},{"schema":{"type":"string"},"description":"min tvl usd","name":"minTvlUsd","in":"query"},{"schema":{"type":"string"},"description":"max tvl usd","name":"maxTvlUsd","in":"query"},{"schema":{"type":"string"},"description":"min apr","name":"minApr","in":"query"},{"schema":{"type":"string"},"description":"max apr","name":"maxApr","in":"query"},{"schema":{"type":"string"},"description":"sort field by tvlUsd | apr | apy | createdAt | updatedAt","name":"sortBy","in":"query"},{"schema":{"type":"string"},"description":"asc | desc","name":"sortDirection","in":"query"},{"schema":{"type":"integer"},"description":"limit","name":"limit","in":"query"},{"schema":{"type":"integer"},"description":"offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/rest.Response"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/common.Pagination-core_MarketsResponse"}}}]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}}}}}}} ``` ## Get market > Get market by id. ```json {"openapi":"3.1.1","info":{"title":"YiFi Yield Aggregator – Data Gateway API","version":"v1"},"tags":[{"description":"Unified DeFi markets – Staking/LST, DEX, Lending, Fixed Income, Structured Vaults, Stablecoins","name":"Markets"}],"servers":[{"url":"https://core-dev.yifi.io/api/v1"}],"security":[{"BearerToken":[]},{"PartnerApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"description":"Admin key for privileged operations (create/edit/delete).","type":"apiKey","name":"Authorization","in":"header"},"PartnerApiKey":{"description":"Partner API key used for B2B attribution (wallets, platforms). Requests authenticated with this key are attributed to the owning partner.","type":"apiKey","name":"X-Partner-Api-Key","in":"header"}},"schemas":{"rest.Response":{"type":"object","properties":{"code":{"type":"string"},"data":{},"isError":{"type":"boolean"},"message":{"type":"string"},"success":{"type":"boolean"}}},"core.MarketCurrentResponse":{"type":"object","properties":{"annual_rate":{"description":"out of meta for effective search","type":"string"},"category":{"type":"string"},"chain":{"type":"string"},"market_id":{"type":"string"},"meta":{},"name":{"type":"string"},"participating_tokens":{"description":"slice of tokenIDs // no need for more for creating a market","type":"array","items":{"$ref":"#/components/schemas/common.TokenAddress"}},"platform":{"type":"string"},"rate_format":{"type":"string"},"tvl_usd":{"description":"in usd","type":"string"},"yield_type":{"description":"user inserts","type":"string"}}},"common.TokenAddress":{"type":"object","properties":{"address":{"type":"string"},"chain":{"type":"string"},"decimals":{"type":"integer"},"logo_url":{"description":"new","type":"string"},"price_usd":{"type":"string"},"role":{"type":"string"},"symbol":{"type":"string"},"token_id":{"type":"string"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/markets/{market_id}":{"get":{"description":"Get market by id.","tags":["Markets"],"summary":"Get market","parameters":[{"schema":{"type":"string"},"description":"market id","name":"market_id","in":"path","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/rest.Response"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/core.MarketCurrentResponse"}}}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}}}}}}} ``` ## Market history metrics > Get market historical metrics for a given period. ```json {"openapi":"3.1.1","info":{"title":"YiFi Yield Aggregator – Data Gateway API","version":"v1"},"tags":[{"description":"Unified DeFi markets – Staking/LST, DEX, Lending, Fixed Income, Structured Vaults, Stablecoins","name":"Markets"}],"servers":[{"url":"https://core-dev.yifi.io/api/v1"}],"security":[{"BearerToken":[]},{"PartnerApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"description":"Admin key for privileged operations (create/edit/delete).","type":"apiKey","name":"Authorization","in":"header"},"PartnerApiKey":{"description":"Partner API key used for B2B attribution (wallets, platforms). Requests authenticated with this key are attributed to the owning partner.","type":"apiKey","name":"X-Partner-Api-Key","in":"header"}},"schemas":{"rest.Response":{"type":"object","properties":{"code":{"type":"string"},"data":{},"isError":{"type":"boolean"},"message":{"type":"string"},"success":{"type":"boolean"}}},"core.MarketHistoryResponse":{"type":"object","properties":{"history":{"description":"category specific history metrics","type":"array","items":{"$ref":"#/components/schemas/core.History"}},"market_id":{"description":"key in portals","type":"string"},"rate_format":{"type":"string"},"yield_type":{"description":"admin inserts","type":"string"}}},"core.History":{"type":"object","properties":{"annual_rate":{"description":"out of meta for effective search. NEED ONLY FOR SEARCH. NOT OUTPUT. META ALREADY CONTAINS ALL INFO","type":"string"},"timestamp":{"description":"Meta common.Meta `json:\"meta\"` // временно забиваем","type":"string"},"tvl_usd":{"description":"in usd","type":"string"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/markets/{market_id}/metrics":{"get":{"description":"Get market historical metrics for a given period.","tags":["Markets"],"summary":"Market history metrics","parameters":[{"schema":{"type":"string"},"description":"market id","name":"market_id","in":"path","required":true},{"schema":{"type":"string"},"description":"start time RFC3339","name":"from","in":"query"},{"schema":{"type":"string"},"description":"end time RFC3339","name":"to","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/rest.Response"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/core.MarketHistoryResponse"}}}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}}}}}}} ``` ### Relationship to Strategy A strategy references one or more markets by `market_id` and adds everything needed to actually deposit into one: input/output tokens, a risk rating, fee breakdown, and an executable path.