Oracle API

Query and subscribe to token price feeds and metadata.

Table of Contents

• Queries

  • token

  • tokens

  • tokenPricesUsd

• Subscriptions

• Types Reference

Queries

token

Get details for a specific token by ID.

Signature:

token(id: Int!): Token!

Parameters:

• id: Token ID (integer)

Returns: Token object

Example:

query GetToken {
  oracle {
    token(id: 1) {
      id
      symbol
      name
      logoUrl
      tradingViewSymbol
      permissionGroup
    }
  }
}

Use Cases:

• Get token metadata

• Display token information

• Resolve token ID to symbol

---

tokens

List all available tokens with filtering and ordering.

Signature:

tokens(
  where: TokensFilter
  limit: Int
  order_by: TokensOrder
  order_desc: Boolean
): [Token!]!

Parameters:

• where: Filter object (optional)

  • name: Filter by token name (string match)

  • permissionGroup: Filter by permission group

• limit: Max results

• order_by: Sort by id, name, or permission_group

• order_desc: Sort descending

Returns: Array of Token objects

Example - List All Tokens:

query ListAllTokens {
  oracle {
    tokens(order_by: name) {
      id
      symbol
      name
      logoUrl
      tradingViewSymbol
    }
  }
}

Example - Search by Name:

query SearchToken($searchTerm: String!) {
  oracle {
    tokens(where: { name: $searchTerm }) {
      id
      symbol
      name
    }
  }
}

Example - Filter by Permission Group:

query GetPermittedTokens {
  oracle {
    tokens(where: { permissionGroup: 1 }) {
      id
      symbol
      name
    }
  }
}

Use Cases:

• Build token selector dropdown

• Search tokens by name

• List tradeable assets

• Filter by permissions

---

tokenPricesUsd query

Get current USD prices for tokens.

Signature:

tokenPricesUsd(
  where: TokenPriceUsdFilter
  limit: Int
  order_by: TokenPriceUsdOrder
  order_desc: Boolean
): [TokenPricesUsd!]!

Parameters:

• where: Filter object (optional)

  • tokenId: Filter by specific token ID

• limit: Max results

• order_by: Sort by token_id

• order_desc: Sort descending

Returns: Array of TokenPricesUsd objects

Example - Get All Prices:

query GetAllPrices {
  oracle {
    tokenPricesUsd {
      token {
        id
        symbol
        name
      }
      priceUsd
      lastUpdatedBlock {
        block
        block_ts
      }
    }
  }
}

Example - Get Specific Token Price:

query GetBTCPrice {
  oracle {
    tokenPricesUsd(where: { tokenId: 1 }) {
      token {
        symbol
      }
      priceUsd
      lastUpdatedBlock {
        block
        block_ts
      }
    }
  }
}

Example - Get Multiple Prices:

query GetPrices {
  btc: oracle {
    tokenPricesUsd(where: { tokenId: 1 }) {
      priceUsd
      lastUpdatedBlock { block_ts }
    }
  }
  eth: oracle {
    tokenPricesUsd(where: { tokenId: 2 }) {
      priceUsd
      lastUpdatedBlock { block_ts }
    }
  }
}

Key Fields:

• priceUsd: Current price in USD (float)

• lastUpdatedBlock: Block info for last price update

Use Cases:

• Display token prices

• Calculate position values

• Monitor price changes

• Verify price freshness

---

Subscriptions

Subscribe to real-time price updates.

tokenPricesUsd

Subscribe to price updates for specific or all tokens.

Signature:

subscription {
  tokenPricesUsd(where: SubTokenPriceUsdFilter): [TokenPricesUsd!]!
}

Example - Subscribe to All Prices:

subscription WatchAllPrices {
  tokenPricesUsd {
    token {
      id
      symbol
    }
    priceUsd
    lastUpdatedBlock {
      block
      block_ts
    }
  }
}

Example - Subscribe to Specific Token:

subscription WatchBTCPrice {
  tokenPricesUsd(where: { tokenId: 1 }) {
    token {
      symbol
    }
    priceUsd
    lastUpdatedBlock {
      block_ts
    }
  }
}

Use Cases:

• Real-time price tickers

• Live trading dashboards

• Price alert systems

• Chart updates

---

userBalances

Subscribe to user balance updates across all tokens.

Signature:

subscription {
  userBalances(where: SubUserBalancesFilter!): [Balance!]!
}

Example:

subscription WatchUserBalances($user: String!) {
  userBalances(where: { user: $user }) {
    amount
    token_info {
      symbol
      decimals
      bank_denom
      erc20_contract_address
      logo
      name
      type
    }
  }
}

Use Cases:

• Track wallet balances

• Monitor account changes

• Real-time portfolio updates

• Display available funds

---

Types Reference

Token

type Token {
  id: Int!
  symbol: String!
  name: String!
  logoUrl: String
  tradingViewSymbol: String
  permissionGroup: Int!
}

Field Details:

• id: Unique token identifier

• symbol: Token ticker (e.g., "BTC", "ETH")

• name: Full token name (e.g., "Bitcoin", "Ethereum")

• logoUrl: URL to token logo image

• tradingViewSymbol: Symbol for TradingView charts

• permissionGroup: Access/trading permission level

---

TokenPricesUsd

type TokenPricesUsd {
  token: Token
  priceUsd: Float!
  lastUpdatedBlock: Block!
}

Field Details:

• token: Associated token metadata

• priceUsd: Current USD price

• lastUpdatedBlock: Last price update info

  • block: Block height

  • block_ts: Timestamp (RFC3339 format)

---

Balance

type Balance {
  amount: String!
  token_info: TokenInfo!
}

---

TokenInfo

Detailed token information for balances.

type TokenInfo {
  bank_denom: String!
  symbol: String!
  name: String!
  decimals: Int!
  logo: String
  type: TokenType!
  erc20_contract_address: String!
}

TokenType Enum:

• bank: Native Cosmos SDK token

• erc20: ERC20 token on EVM

---

Working with Prices

Price Freshness

Always check when price was last updated:

const now = Date.now()
const lastUpdate = new Date(lastUpdatedBlock.block_ts).getTime()
const ageSeconds = (now - lastUpdate) / 1000

if (ageSeconds > 60) {
  console.warn('Price may be stale')
}

Price Formatting

// Format price with appropriate decimals
const formatPrice = (priceUsd) => {
  if (priceUsd >= 1000) {
    return priceUsd.toFixed(2)
  } else if (priceUsd >= 1) {
    return priceUsd.toFixed(4)
  } else {
    return priceUsd.toFixed(6)
  }
}

Calculate Position Value

// Calculate position value in USD
const positionValueUsd = (collateralAmount, priceUsd, decimals) => {
  const actualAmount = collateralAmount / (10 ** decimals)
  return actualAmount * priceUsd
}

Balance Conversion

// Convert balance amount string to number
const getBalanceValue = (balance) => {
  const amount = parseFloat(balance.amount)
  return amount / (10 ** balance.token_info.decimals)
}

---

Best Practices

Caching Prices

// Cache prices for short periods to reduce queries
const priceCache = new Map()
const CACHE_TTL = 5000 // 5 seconds

const getCachedPrice = async (tokenId) => {
  const cached = priceCache.get(tokenId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.price
  }
  
  const price = await fetchPrice(tokenId)
  priceCache.set(tokenId, { price, timestamp: Date.now() })
  return price
}

Handling Multiple Tokens

// Batch query multiple prices efficiently
const query = `
  query GetMultiplePrices($tokenIds: [Int!]!) {
    oracle {
      prices: tokenPricesUsd(limit: 100) {
        token { id symbol }
        priceUsd
      }
    }
  }
`

// Filter client-side for needed tokens
const relevantPrices = data.oracle.prices.filter(p => 
  tokenIds.includes(p.token.id)
)

Subscription Management

// Manage price subscription lifecycle
let priceSubscription

const subscribeToPrices = (tokenIds) => {
  // Unsubscribe from previous
  if (priceSubscription) {
    priceSubscription.unsubscribe()
  }
  
  // Subscribe to new set
  priceSubscription = client.subscribe({
    query: PRICE_SUBSCRIPTION,
    variables: { tokenIds }
  }).subscribe({
    next: (data) => updatePrices(data),
    error: (err) => console.error(err)
  })
}