Sai Keeper GraphQL queries

Supporting reference for sai-perps.

GitHub source ↗Original Markdown ↓
On this page Overview

Use this reference for indexed, app-facing Sai data: perp positions and history, SLP Vault history, Oracle prices, referral analytics, and live subscriptions. For live protocol state or contract-owned values, use sai-contracts.md instead.

Source and endpoints

The source of truth is the GraphQL schema in directory $HOME/ki/sai-keeper/graphql/graph/. File $HOME/ki/sai-website/webapp/config/chain.ts builds the deployed endpoint with path /query.

NetworkHTTPWebSocket
Mainnethttps://sai-keeper.nibiru.fi/querywss://sai-keeper.nibiru.fi/query
Testnet2https://sai-keeper.testnet-2.nibiru.fi/querywss://sai-keeper.testnet-2.nibiru.fi/query

The host root serves the GraphQL playground. Verify a public deployment before assuming that its schema has caught up with the local Keeper commit.

Query domains

The root Query type exposes domain objects: oracle, perp, lp, referral, appVersion, saiPoints, and explorer. Scope fields under their domain rather than querying them at the root.

DomainKey fieldsNotes
perptrade, trades, tradeHistory, borrowing, borrowings, statsUserPortfolio, traderFeeTierProgressIndexed trades, market borrowing state, and portfolio/fee-tier summaries. trades(where:) requires a trader address.
lpvaults, depositHistory, withdrawRequests, vaultStats, epochDurationDaysIndexed vault and LP history; not a replacement for live vault accounting.
oracletokens, token, tokenPricesUsdApp-indexed token metadata and prices. Use lastUpdatedBlock to assess freshness.
referralreferralCodes, referralTrades, referralRedemption, referralRedemptionTrader, referralClaims, referralStatsHistorical referral data keyed by referrer or trader.

There is no GraphQL fee root domain or fields such as feeTransactions in the current schema. For fee details, use Perp trade history fields such as openingFeeUsd and closingFeeUsd, contract fee queries, or database references as appropriate.

Filters, order, and units

  • Perp query field trades uses PerpTradesFilter, whose required trader field can be narrowed by perpMarketId, perpCollateralId, and isOpen.
  • Perp query field tradeHistory uses PerpTradeHistoryFilter, whose required trader field returns the trader’s indexed mutations.
  • Lists accept their schema-defined order_by, order_desc, limit, and offset arguments. Do not assume that an order enum applies to another domain.
  • Many contract-sized values are GraphQL Int base units, including Perp trade collateral and open interest. Exceptions are deliberate: table Balance exposes amount as a string, and USD/price/percentage fields commonly use GraphQL Float.
  • GraphQL type Token does not expose decimal metadata. Table Balance includes token_info.decimals when a wallet or Sai balance subscription is relevant.

Subscriptions

The current Subscription type provides exactly these fields:

FieldRequired filter or arguments
tokenPricesUsdOptional SubTokenPriceUsdFilter (tokenId)
perpTradesSubPerpTradesFilter! (trader)
perpTradeHistorySubPerpTradeHistoryFilter! (trader)
perpBorrowingsNone
perpBorrowingmarketId, collateralId
lpVaultsNone
lpDepositHistorySubLpDepositHistoryFilter! (depositor, vault)
lpWithdrawRequestsSubLpWithdrawRequestsFilter! (depositor, vault)
userBalancesSubUserBalancesFilter! (user)
userInfoSubUserFilter! (user)

No lpDeposits subscription exists in the current schema. For a user’s vault state, query the LP history/request fields or read live contract state according to the fact being requested.

Example queries

query OpenTrades($trader: String!) {
  perp {
    trades(where: { trader: $trader, isOpen: true }) {
      id
      collateralAmount
      leverage
      isLong
      state { positionValue liquidationPrice }
    }
  }
}
query ReferralHistory($referrer: String!) {
  referral {
    referralCodes(referrer: $referrer) { code active uniqueTraders volumeUSD }
    referralRedemption(referrer: $referrer) { trader code active block { block block_ts } }
  }
}