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
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:
Incentivized Positions
Set both
rewardVault=true
andsweetened=true
Volatility Filters
For volatile pairs:
volatile=true
For stable pairs:
volatile=false
TVL Threshold
Hide low TVL positions:
minimumTvl=10000
(filters out positions with less than $10,000 TVL)
Search
Filter by token names or symbols:
search=ETH
orsearch=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
Basic request for all positions on a specific chain
GET /vaults?chainId=80094&limit=20&offset=0
Filter for high TVL, incentivized positions
GET /vaults?chainId=80094&rewardVault=true&sweetened=true&minimumTvl=10000
Sort by highest APR descending
GET /vaults?chainId=80094&orderBy=totalApr&orderDirection=desc
Get positions for a specific user, ordered by balance
GET /vaults?chainId=80094&user=0x836966B09854d7a9c6C8a978ea72e0d906cBdfB4&orderBy=balance&orderDirection=desc
Filter for stable pools with minimum TVL
GET /vaults?chainId=80094&volatile=false&minimumTvl=10000
Search for a specific token
GET /vaults?chainId=80094&search=BM
Error Handling
The API returns standard HTTP status codes:
200 OK
: Request successful400 Bad Request
: Invalid parameters404 Not Found
: Resource not found500 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.
Last updated