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:

{
  "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:

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 https://discord.gg/kodiak.