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:

1. Know the subgraph endpoint URL (sugraph-endpoint)

2. Have a basic understanding of GraphQL query syntax

3. 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

1. Query Only What You Need: Only request the fields you actually need to minimize response size.

2. Use Pagination: For large collections, always use pagination to prevent timeouts.

3. Filter Efficiently: Apply filters at the query level rather than filtering results in your application.

4. Optimize Sorting: Sort at the query level for better performance.

5. Cache Results: GraphQL responses are highly cacheable. Implement client-side caching for better performance.

6. 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.