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.

PreviousKodiak Island RouterNextBaults

Last updated