Query Guide
Introduction
This guide provides examples and best practices for querying the Kodiak Islands subgraph using GraphQL. Whether you're building a dashboard, analysis tool, or integrating with another application, these queries will help you extract the data you need.
Getting Started
To query the Kodiak Islands subgraph, you'll need to:
Know the subgraph endpoint URL (sugraph-endpoint)
Have a basic understanding of GraphQL query syntax
Use a GraphQL client (like Apollo Client) or make HTTP requests to the endpoint
Basic Query Structure
All GraphQL queries for the Kodiak Islands subgraph follow this basic structure:
query {
entity(where: { filter conditions }) {
field1
field2
nestedEntity {
nestedField1
nestedField2
}
}
}Common Query Examples
1. Protocol Overview
Get basic information about the protocol:
query {
kodiakIslandProtocols {
id
totalValueLockedUSD
cumulativeTotalFeesUSD
totalPoolCount
}
}2. List All Vaults
Retrieve all vaults with basic information:
query {
kodiakVaults(first: 100) {
id
name
symbol
totalValueLockedUSD
inputToken {
id
symbol
decimals
}
outputToken {
id
symbol
decimals
}
manager
managerFee
createdTimestamp
}
}3. Get Vault Details
Get detailed information about a specific vault:
query {
kodiakVault(id: "0x1234567890abcdef1234567890abcdef12345678") {
id
name
symbol
totalValueLockedUSD
cumulativeTotalFeesUSD
cumulativeLpFeesUSD
cumulativeManagerFeesUSD
inputTokenBalance
outputTokenSupply
pricePerShare
volumeUSD
weeklyVolumeUSD
weeklyFeesEarnedUSD
lowerTick
upperTick
apr {
averageApr
}
_token0 {
symbol
}
_token1 {
symbol
}
_token0Amount
_token1Amount
_token0AmountUSD
_token1AmountUSD
}
}4. Recent Deposits
Query recent deposit events for a specific vault:
query {
kodiakDeposits(
first: 10
orderBy: timestamp
orderDirection: desc
where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
) {
id
timestamp
from
amount
amountUSD
amount0
amount1
}
}5. Recent Withdrawals
Query recent withdrawal events for a specific vault:
query {
kodiakWithdraws(
first: 10
orderBy: timestamp
orderDirection: desc
where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
) {
id
timestamp
to
amount
amountUSD
}
}6. Daily Vault Performance
Query daily snapshots for a vault to analyze performance over time:
query {
kodiakVaultDailySnapshots(
first: 30
orderBy: timestamp
orderDirection: desc
where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
) {
id
timestamp
totalValueLockedUSD
dailyTotalFeesUSD
dailyLpFeesUSD
dailyManagerFeesUSD
volumeUSD
volumeToken0
volumeToken1
apr
pricePerShare
lowerTick
upperTick
}
}7. Protocol Usage Metrics
Query daily protocol usage metrics:
query {
kodiakUsageMetricsDailySnapshots(
first: 30
orderBy: timestamp
orderDirection: desc
) {
id
timestamp
dailyActiveUsers
cumulativeUniqueUsers
dailyTransactionCount
dailyDepositCount
dailyWithdrawCount
totalPoolCount
}
}8. Protocol Financial Metrics
Query daily protocol financial metrics:
query {
kodiakFinancialsDailySnapshots(
first: 30
orderBy: timestamp
orderDirection: desc
) {
id
timestamp
totalValueLockedUSD
dailyLpFeesUSD
dailyManagerFeesUSD
dailyTotalFeesUSD
}
}9. Strategy Changes
Track strategy changes for a specific vault:
query {
kodiakStrategyChanges(
first: 20
orderBy: timestamp
orderDirection: desc
where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
) {
id
timestamp
lowerTick
upperTick
}
}10. Vault APR History
Query APR history for a vault:
query {
kodiakVaultDailySnapshots(
first: 90
orderBy: timestamp
orderDirection: desc
where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
) {
timestamp
apr
}
}Filtering and Sorting
Time-Based Filtering
Filter snapshots within a specific time range:
query {
kodiakVaultDailySnapshots(
where: {
timestamp_gte: "1640995200" # Jan 1, 2022
timestamp_lt: "1672531200" # Jan 1, 2023
}
) {
timestamp
totalValueLockedUSD
dailyTotalFeesUSD
}
}Value-Based Filtering
Filter vaults by TVL:
query {
kodiakVaults(
where: {
totalValueLockedUSD_gt: "1000000" # > $1M TVL
}
) {
id
name
totalValueLockedUSD
}
}Sorting Results
Sort vaults by TVL in descending order:
query {
kodiakVaults(
orderBy: totalValueLockedUSD
orderDirection: desc
) {
id
name
totalValueLockedUSD
}
}Pagination
For large result sets, use pagination with first and skip:
query {
kodiakVaults(
first: 20 # Get 20 records
skip: 20 # Skip first 20 records (for page 2)
orderBy: totalValueLockedUSD
orderDirection: desc
) {
id
name
totalValueLockedUSD
}
}Advanced Queries
Get User Activity Across Vaults
Find all deposits and withdrawals for a specific user:
query {
deposits: kodiakDeposits(
where: { from: "0xuser_address_here" }
) {
timestamp
vault {
id
name
}
amountUSD
}
withdraws: kodiakWithdraws(
where: { to: "0xuser_address_here" }
) {
timestamp
vault {
id
name
}
amountUSD
}
}Compare Multiple Vaults
Compare performance metrics for multiple vaults:
query {
vault1: kodiakVault(id: "0xvault1_address_here") {
id
name
totalValueLockedUSD
weeklyFeesEarnedUSD
apr {
averageApr
}
}
vault2: kodiakVault(id: "0xvault2_address_here") {
id
name
totalValueLockedUSD
weeklyFeesEarnedUSD
apr {
averageApr
}
}
}Best Practices
Query Only What You Need: Only request the fields you actually need to minimize response size.
Use Pagination: For large collections, always use pagination to prevent timeouts.
Filter Efficiently: Apply filters at the query level rather than filtering results in your application.
Optimize Sorting: Sort at the query level for better performance.
Cache Results: GraphQL responses are highly cacheable. Implement client-side caching for better performance.
Handle Time Data Correctly: Remember that timestamps are in seconds since Unix epoch.
Error Handling
The subgraph may return errors for various reasons:
Invalid query syntax
Non-existent entities or fields
Server timeouts for complex queries
Always implement proper error handling in your application to handle these cases gracefully.
Real-World Use Cases
Building a Dashboard
For a vault performance dashboard, you might combine protocol metrics with vault-specific data:
query DashboardData {
protocol: kodiakIslandProtocols(first: 1) {
totalValueLockedUSD
totalPoolCount
}
vaults: kodiakVaults(
first: 10
orderBy: totalValueLockedUSD
orderDirection: desc
) {
id
name
totalValueLockedUSD
apr {
averageApr
}
}
recentActivity: kodiakDeposits(
first: 5
orderBy: timestamp
orderDirection: desc
) {
timestamp
vault {
name
}
amountUSD
}
}Historical Analysis
For analyzing a vault's performance over time:
query VaultHistoricalAnalysis($vaultId: ID!, $days: Int!) {
dailySnapshots: kodiakVaultDailySnapshots(
first: $days
orderBy: timestamp
orderDirection: desc
where: { vault: $vaultId }
) {
timestamp
totalValueLockedUSD
dailyTotalFeesUSD
dailyLpFeesUSD
dailyManagerFeesUSD
volumeUSD
apr
}
}With these query examples and best practices, you should be well-equipped to extract valuable data from the Kodiak Islands subgraph for your applications.
Last updated