# API ### Pools & Farms API This documentation covers the REST API endpoints for kodiak pools. #### Base URL ``` https://backend.kodiak.finance ``` #### Pools Endpoint ``` GET /vaults ``` Retrieves information about liquidity positions (pools) with comprehensive filtering, sorting, and pagination options. #### Request Parameters | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ------------------------------------------------------------ | | `chainId` | number | Yes | Blockchain network ID (e.g., 80094) | | `limit` | number | No | Maximum number of results to return (default: 20) | | `offset` | number | No | Number of results to skip for pagination (default: 0) | | `orderBy` | string | No | Field to sort results by (see Sorting Options) | | `orderDirection` | string | No | Sort direction: `asc` or `desc` (default: `desc`) | | `user` | string | No | Address to filter positions by user holdings | | `search` | string | No | Search term to filter results by token names or symbols | | `rewardVault` | boolean | No | When `true`, filters for positions with reward vaults | | `sweetened` | boolean | No | When `true`, filters for incentivized/sweetened positions | | `volatile` | boolean | No | Filter for volatile (`true`) or stable (`false`) pairs | | `minimumTvl` | number | No | Minimum total value locked threshold (e.g., 10000 = $10,000) | #### Sorting Options The API supports sorting by the following fields: | `orderBy` value | Description | | --------------- | -------------------------------------------------------------------------------- | | `tvl` | Total value locked in the position | | `farmTvl` | Total value locked in associated farms | | `apr` | Base APR from trading fees | | `farmApr` | Farm/incentive APR | | `totalApr` | Combined APR (base + farm) | | `balance` | User's balance in the position (requires `user` parameter) | | `farmBalance` | User's balance in associated farms/reward vaults (requires `user` parameter) | | `vaultBalance` | User's balance in associated pools that are unstaked (requires `user` parameter) | #### Filter Combinations The API supports multiple filter combinations: 1. **Incentivized Positions** * Set both `rewardVault=true` and `sweetened=true` 2. **Volatility Filters** * For volatile pairs: `volatile=true` * For stable pairs: `volatile=false` 3. **TVL Threshold** * Hide low TVL positions: `minimumTvl=10000` (filters out positions with less than $10,000 TVL) 4. **Search** * Filter by token names or symbols: `search=ETH` or `search=Ethereum` #### Pagination The API uses offset-based pagination: * `limit`: Number of results per page (default: 20) * `offset`: Starting position for results (default: 0) Example pagination: * Page 1: `offset=0&limit=20` * Page 2: `offset=20&limit=20` * Page 3: `offset=40&limit=20` #### Response Format The API returns a JSON object with the following structure: ```json { "data": [IslandApiResponse], "count": number } ``` Where `count` is the total number of results matching the query (before pagination), and `data` is an array of `IslandApiResponse` objects. #### IslandApiResponse Object Each island position is represented by an object with the following structure: ```typescript interface IslandApiResponse { id: string // Unique identifier for the position provider: string // Provider of the liquidity pool lowerTick: number // Lower price bound tick upperTick: number // Upper price bound tick currentTick: number // Current price tick tvl: number // Total value locked in USD farmTvl: number // Total value locked in associated farms in USD apr: number // Annual percentage rate from fees weeklyFeesEarnedUSD: number // Weekly fees earned in USD feeTier: number // Fee tier of the pool totalApr: number // Combined APR (base + farm) lastUpdated: string // Timestamp of last data update isSweetened: boolean // Whether position has additional incentives isRewardVault: boolean // Whether position has a reward vault isVolatile: boolean // Whether position is for volatile pairs // First token in the pair token0: { id: string // Token address symbol: string // Token symbol name: string // Token name decimals: number // Token decimals price: number // Current token price in USD } // Second token in the pair token1: { id: string // Token address symbol: string // Token symbol name: string // Token name decimals: number // Token decimals price: number // Current token price in USD } // Associated farm information (if applicable) farm: { id: string // Farm identifier provider: string // Farm provider tvl: number // Total value locked in farm apr: number // Farm APR rewardRates: BigNumber[] // Reward rates rewardTokens: { // Reward tokens id: string // Token address symbol: string // Token symbol name: string // Token name decimals: number // Token decimals price: number // Current token price in USD }[] } | null // Can be null if no farm exists // User-specific fields (only present when 'user' parameter is provided) balanceUSD?: number // User's total position balance (vault + farm) in USD farmBalanceUSD?: number // User's kodiak_farm/reward_vaults balance in USD vaultBalanceUSD?: number // User's pool balance that is unstaked in USD } ``` #### Example Requests 1. **Basic request for all positions on a specific chain** ``` GET /vaults?chainId=80094&limit=20&offset=0 ``` 2. **Filter for high TVL, incentivized positions** ``` GET /vaults?chainId=80094&rewardVault=true&sweetened=true&minimumTvl=10000 ``` 3. **Sort by highest APR descending** ``` GET /vaults?chainId=80094&orderBy=totalApr&orderDirection=desc ``` 4. **Get positions for a specific user, ordered by balance** ``` GET /vaults?chainId=80094&user=0x836966B09854d7a9c6C8a978ea72e0d906cBdfB4&orderBy=balance&orderDirection=desc ``` 5. **Filter for stable pools with minimum TVL** ``` GET /vaults?chainId=80094&volatile=false&minimumTvl=10000 ``` 6. **Search for a specific token** ``` GET /vaults?chainId=80094&search=BM ``` #### Error Handling The API returns standard HTTP status codes: * `200 OK`: Request successful * `400 Bad Request`: Invalid parameters * `404 Not Found`: Resource not found * `500 Internal Server Error`: Server-side error #### Notes on Chain IDs Ensure you're using the correct chain ID for the network you wish to query. For example: * 80094: BERA Mainnet * (Add other supported chains as needed, only BERA mainnet supported for now) *** For support or questions regarding the API, join our Discord community at . --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.kodiak.finance/developers/kodiak-islands/api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.