本页面的翻译由 LLM 生成。如果你发现翻译有误,请在 GitHub 上提交 issue 告诉我们。

预言机 API 参考

查询和订阅代币价格源及元数据。

查询

token

按 ID 获取代币详情。

签名：

token(id: Int!): Token!

参数：

id：整数代币 ID。

返回： Token。

示例：

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

应用场景：

获取元数据。
显示代币信息。
从 ID 查找符号。

tokens

列出全部可用代币，支持筛选和排序。

签名：

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

参数：

where：可选筛选。
- name：名称字符串匹配。
- permissionGroup：权限组。
limit：最大数量。
order_by：id、name 或 permission_group。
order_desc：降序。

返回： Token 数组。

示例：列出全部代币

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

示例：按名称搜索

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

示例：按权限组筛选

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

应用场景：

构建代币选择器。
按名称搜索。
列出可交易资产。
按权限筛选。

tokenPricesUsd 查询

获取代币当前 USD 价格。

签名：

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

参数：

where：可选筛选。
- tokenId：代币 ID。
limit：最大数量。
order_by：oracle_token_id。
order_desc：降序。

返回： TokenPricesUsd 数组。

示例：获取全部价格

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

示例：获取特定代币价格

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

示例：获取多个价格

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

主要字段：

priceUsd：当前 USD 价格，浮点数。
lastUpdatedBlock：最近更新的区块信息。

应用场景：

显示价格。
计算仓位价值。
监控价格变化。
验证价格时效。

类型参考

Token

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

字段说明：

id：唯一标识。
symbol：BTC、ETH 等代码。
name：Bitcoin、Ethereum 等全名。
logoUrl：标识图片 URL。
tradingViewSymbol：TradingView 图表代码。
permissionGroup：访问、交易权限级别。

TokenPricesUsd

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

字段说明：

token：关联代币元数据。
priceUsd：当前 USD 价格。
lastUpdatedBlock：最近更新信息。
- block：区块高度。
- block_ts：RFC3339 时间。

Balance

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

TokenInfo

余额所用的详细代币信息。

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

TokenType 枚举：

bank：Cosmos SDK 原生代币。
erc20：EVM 的 ERC20。

处理价格

价格时效

务必检查价格的最近更新时间。

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')
}

价格格式

// 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 in USD
const positionValueUsd = (collateralAmount, priceUsd, decimals) => {
  const actualAmount = collateralAmount / (10 ** decimals)
  return actualAmount * priceUsd
}

余额转换

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

最佳实践

缓存价格

// 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
}

处理多个代币

// 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)
)

订阅管理

// 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)
  })
}

预言机 API 参考

目录

查询

token

tokens

tokenPricesUsd 查询

订阅

tokenPricesUsd

userBalances

类型参考

Token

TokenPricesUsd

Balance

TokenInfo

处理价格

价格时效

价格格式

计算仓位价值

余额转换

最佳实践

缓存价格

处理多个代币

订阅管理