# 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 .