> For the complete documentation index, see [llms.txt](https://docs.kumbaya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kumbaya.xyz/developers/resources/indexer.md). # Hasura Indexer Kumbaya runs a public **Hasura GraphQL** endpoint - the layer you query - on top of an **Envio** indexer that ingests every Uniswap V3 event *and* every Kumbaya launchpad event on MegaETH and publishes it as queryable data. | Field | Value | | ------------ | --------------------------------------------------- | | **Endpoint** | `https://ql.kumbaya.xyz/v1/graphql` | | **Auth** | None - public, read-only | | **Networks** | MegaETH mainnet (chain `4326`) and testnet (`6343`) | > The indexer's source code is not public. You consume the GraphQL API directly. Schema introspection is enabled - point your IDE/codegen tools at the URL above to explore. ## Entity catalogue ### Core (V3) entities | Entity | What it is | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Factory` | Per-chain factory state (pool count, total volume) | | `Bundle` | Per-chain ETH/USD price bundle (used to derive USD prices) | | `Token` | Current token state - `priceUSD`, `lastSwapTimestamp`, `totalValueLockedUSD`, `volumeUSD`, `derivedETH` | | `Pool` | Pool state. Includes `firePool` (boolean) and `fireToken` (relationship) for launchpad-originated pools, and `poisonedPool` (boolean) for invalid launchpad configs. Also `feeProtocol0` and `feeProtocol1` (0 or 2..10) | | `Tick` | Per-tick liquidity bookkeeping | | `RawPosition` | Pool-level liquidity position | | `UserPosition` | NFT-level LP position (NonfungiblePositionManager-owned) | | `Transaction` | Per-tx envelope for related events | | `Mint` / `Burn` / `Swap` / `Collect` | Per-event records | ### Time-series aggregates | Entity | Resolution | Purpose | | ---------------------------------------------------------------------------------- | --------------- | --------------------------- | | `TokenMinuteData` | 1m | Token price/volume snapshot | | `TokenHourData` | 1h | Token snapshot | | `TokenDayData` | 1d | Token snapshot | | `PoolHourData` / `PoolDayData` / `PoolWeekData` / `PoolMonthData` / `PoolYearData` | Hourly → yearly | Pool aggregates | | `UniswapHourData` / `UniswapDayData` | Hourly / daily | Chain-wide totals | ### Launchpad-specific entities | Entity | What it is | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `FireToken` | Per-launch state - see fields below. Includes graduation progress, market cap, fees collected, time-windowed buy/sell counts, velocity | | `FirePosition` | Per-position record inside a bonding-curve pool | | `FireFeeClaim` | Pre-grad fee-claim events (`FireGraduator.claimFees`) | | `FireSkim` | Per-buy skim events (`FireToken.Skimmed`) | | `FireVestingRelease` | On-token vesting unlocks (`FireToken.releaseVested`) | | `FuelDeposit` / `FuelGift` / `FuelWithdrawal` / `FuelBurn` | Lifecycle of credits in `FuelVault` | | `FuelCreatorBucket` | Current per-creator-per-token bucket state (liquid + vested + unlocked flag) | | `FireStreamNFT` | The graduated-NFT custody record | | `FireStreamFeeDistribution` / `FireStreamBeneficiaryPayment` | Post-grad fee distributions and per-recipient payouts | | `FireUser` / `FireUserParticipation` | Per-user / per-user-per-token aggregates (tokens created, pools participated, total volume, realized PnL) | | `VestedUnlock` | When a creator's pre-grad vested gifts unlocked at graduation | | `FireMigration` | Position migration events | ### Notable `FireToken` fields ```graphql type FireToken { address: Bytes creator: Bytes # the on-chain ignite() caller pool: Pool # nested relationship totalSupply: BigInt skimBps: Int tickLower: Int tickUpper: Int isToken0: Boolean # Graduation graduated: Boolean readyToGraduate: Boolean # tick crossed boundary, condition not yet recorded graduatedAt: BigInt graduationConditionRecordedAt: BigInt graduationProgress: Int # 0..100 graduationTargetNumeraire: BigDecimal totalNumeraireCollected: BigDecimal fuelBurnTime: BigInt # when unclaimed user credits become burnable fuelBurned: Boolean # Metrics volumeUSD: BigDecimal marketCapUSD: BigDecimal feesCollectedUSD: BigDecimal lastSwapAt: BigInt # Time-windowed activity buysLast30m: Int buysLast1h: Int sellsLast30m: Int sellsLast1h: Int buyVelocity: BigDecimal # ratio of buys this hour vs last sellVelocity: BigDecimal tokensBoughtLast1h: BigDecimal tokensSoldLast1h: BigDecimal netTokenFlowLast1h: BigDecimal buyToSellRatio1h: BigDecimal buyerCount: Int } ``` The time-windowed counters are exactly what powers the launchpad feed's "trending" sort and "heating up" sections. ## ID conventions Most entities use **`address-chainId`** composite IDs, e.g. `0xabc...-4326`. Use that format anywhere you reference an entity by id. ## Examples ### Latest token swaps ```graphql query LatestSwaps($poolId: String!, $limit: Int!) { Swap( where: { pool_id: { _eq: $poolId } } order_by: { timestamp: desc } limit: $limit ) { id timestamp sender recipient amount0 amount1 amountUSD sqrtPriceX96 tick transaction { id } } } ``` ### 24h price change ```graphql query TokensWithHistory($chainId: Int!, $targetPeriodStart: Int!, $minTvl: String!) { TokenHourData( where: { chainId: { _eq: $chainId } periodStartUnix: { _eq: $targetPeriodStart } token: { totalValueLockedUSD: { _gt: $minTvl } } } ) { priceUSD token { address symbol priceUSD lastSwapTimestamp } } } ``` `targetPeriodStart` = `Math.floor((now - 86400) / 3600) * 3600`. ### Newest launches ```graphql query NewLaunches($chainId: Int!, $since: BigInt!, $limit: Int!) { FireToken( where: { chainId: { _eq: $chainId } createdAt: { _gte: $since } } order_by: { createdAt: desc } limit: $limit ) { address creator createdAt graduationProgress marketCapUSD pool { id firePool poisonedPool } } } ``` ### "Heating up" - recent activity buckets ```graphql query HeatingUp($chainId: Int!) { FireToken( where: { chainId: { _eq: $chainId } graduated: { _eq: false } buysLast1h: { _gte: 5 } } order_by: { buyVelocity: desc } limit: 20 ) { address creator graduationProgress marketCapUSD buysLast1h buysPrev1h buyVelocity sellsLast1h sellVelocity } } ``` ## Calling from JavaScript Plain `fetch` works: ```ts const res = await fetch('https://ql.kumbaya.xyz/v1/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query: `query { Token(where: { chainId: { _eq: 4326 } }, limit: 5) { address symbol priceUSD } }`, }), }) const { data } = await res.json() ``` Codegen-friendly SDKs (`graphql-request`, `urql`, `apollo`) work without modification. ## Live subscriptions Hasura supports GraphQL **subscriptions** over WebSocket. Useful for agents watching new launches, swaps, or graduation events: ```graphql subscription OnNewSwap($poolId: String!) { Swap( where: { pool_id: { _eq: $poolId } } order_by: { timestamp: desc } limit: 1 ) { id timestamp amount0 amount1 amountUSD } } ``` ## When to use the indexer vs. the Exchange API | Use the **indexer** for | Use the [**Exchange API**](/developers/apis/exchange-api.md) for | | --------------------------------------------------- | ---------------------------------------------------------------------- | | Custom analytics, joins, aggregations | Curated UI data: pool list, trending tokens, headline stats | | Historical time-series at minute or hour resolution | Quote pricing for a swap | | Live subscriptions on raw events | Anything with caching / rate-limit-friendly defaults | | Anything outside the curated REST endpoints | The hosted `/api/v1/quote` endpoint when you don't want to run the SOR | ## Notes * Hasura's nested `where` clauses become SQL JOINs - feel free to filter on nested fields. * `*_aggregate` queries are available for `count`, `sum`, `avg`, etc. * Pagination: prefer cursor-style on `timestamp` or `id` rather than large `offset` values. * The `Pool.poisonedPool` flag marks launchpad-originated pools that were launched with non-canonical params and aren't price-tracked. Filter by `poisonedPool: { _eq: false }` if you only want healthy pools.