Kodiak Finance
  • OVERVIEW
    • 🐻‍❄️Introducing Kodiak
    • 🐻Kodiak x Berachain
    • ✉️Contact Us
    • 🍯Kodiak Contracts
  • 🅱️Kodiak-Boyco
  • PROTOCOL
    • 🔃DEX
      • Swaps
      • Liquidity Provision
      • Trading Fees
    • 🏝️Islands
      • Island Liquidity Provision
      • Sweetened Islands
      • Auto-BGT
    • 🐼Panda Factory
  • 🪙Tokenomics
    • Kodiak Pre-TGE Rewards
  • 🧠User Guide
    • Launch a Token Launch on Panda Factory
    • Trading on Panda Factory
    • Swap
    • Create a V2 Position
    • Create a V3 Position
    • Add/Stake Islands Liquidity
    • Migrating to a Reward Vault
    • Deploying new Permissonless Islands
    • Deploying and Configuring a Kodiak Farm
    • Add your token
  • Add Your Project to the Ecosystem
  • 👨‍💻Developers
    • 🐼Panda
      • Technical Integration Guide
      • Subgraph
        • Entity Reference
        • Query Guide
        • Advanced Usage Guide
      • Smart Contract Reference
        • Panda Factory
        • Panda Pool
        • Panda Token
      • Api
    • Farms
      • Technical Integration Guide
      • Smart Contract Reference
    • 🌴Kodiak Islands
      • Technical Integration Guide
        • Understanding Token Deposit Ratio
      • Subgraph
        • Entity Reference
        • Query Guide
        • Advanced Usage Guide
      • Smart Contract Reference
        • Kodiak Island Factory
        • Kodiak Island
        • Kodiak Island Router
      • Api
    • 💰Pricing with Subgraph
    • 💱Quotes
    • Backend
  • 🛡️SECURITY
    • 🔍Audits
  • ℹ️Informational
    • 📜Terms of Use
    • 🔏Privacy Policy
    • TradingView Advanced License
Powered by GitBook
On this page
  1. Developers
  2. Kodiak Islands

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)


PreviousKodiak Island RouterNextPricing with Subgraph

Last updated 1 month ago

For support or questions regarding the API, join our Discord community at .

👨‍💻
🌴
https://discord.gg/kodiak