永续合约 API 参考

查询和订阅仓位、交易历史、市场借贷费率及推荐数据。

目录

• 查询
  • trade
  • trades
  • tradeHistory
  • borrowing
  • borrowings
• 订阅
  • perpTrades
  • perpTradeHistory
  • perpBorrowing
  • perpBorrowings
• 类型参考
  • PerpTrade
  • PerpTradeState
  • PerpBorrowing
  • 枚举

查询

trade

按 ID 和交易者地址获取特定交易。

签名：

trade(id: Int!, trader: String!): PerpTrade

参数：

• id：整数交易 ID。
• trader：交易者钱包地址，必填。

返回： PerpTrade，未找到则为 null。

示例：

query GetTrade {
  perp {
    trade(id: 42, trader: "nibi1abc...") {
      id
      isOpen
      isLong
      leverage
      collateralAmount
      openPrice
      closePrice
      perpBorrowing {
        baseToken { symbol }
        collateralToken { symbol }
        marketId
      }
      openBlock {
        block
        block_ts
      }
      closeBlock {
        block
        block_ts
      }
      state {
        pnlCollateral
        pnlPct
        liquidationPrice
        positionValue
      }
    }
  }
}

应用场景：

• 显示单笔交易详情。
• 追踪特定仓位状态。
• 计算当前盈亏。

---

trades

列出交易，支持筛选、分页和排序。

签名：

trades(
  where: PerpTradesFilter!
  limit: Int
  offset: Int
  order_by: PerpTradesOrder
  order_desc: Boolean
): [PerpTrade!]!

参数：

• where：必填筛选对象。
  • trader：必填地址。
  • isOpen：未平仓或已平仓。
  • perpMarketId：市场 ID。
  • perpCollateralId：抵押代币 ID。
• limit：最大结果数，默认 100。
• offset：分页跳过数量。
• order_by：仅 sequence。
• order_desc：降序，默认 false。

返回： PerpTrade 数组。

示例：获取未平仓仓位

query GetOpenPositions($trader: String!) {
  perp {
    trades(
      where: {
        trader: $trader
        isOpen: true
      }
      limit: 50
      order_desc: true
    ) {
      id
      isLong
      leverage
      collateralAmount
      openPrice
      perpBorrowing {
        baseToken { symbol }
        marketId
      }
      state {
        pnlCollateral
        pnlPct
        liquidationPrice
      }
    }
  }
}

示例：按市场筛选

query GetBTCTrades($trader: String!) {
  perp {
    trades(
      where: {
        trader: $trader
        perpMarketId: 1  # BTC market
      }
      limit: 20
    ) {
      id
      isOpen
      openPrice
      closePrice
    }
  }
}

应用场景：

• 列出用户未平仓仓位。
• 显示交易历史。
• 按市场筛选。
• 构建仓位面板。

---

tradeHistory

获取交易事件和仓位变更。

签名：

tradeHistory(
  where: PerpTradeHistoryFilter!
  limit: Int
  offset: Int
  order_by: PerpTradeHistoryOrder
  order_desc: Boolean
): [PerpTradeHistoryItem!]!

参数：

• where：必填筛选对象。
  • trader：必填地址。
• limit：最大数量，默认 100。
• offset：跳过数量。
• order_by：sequence 或 trade_id。
• order_desc：降序。

返回： PerpTradeHistoryItem 数组。

交易变更类型：

• position_opened：开仓。
• position_closed_user：用户平仓。
• position_closed_sl：触发止损。
• position_closed_tp：触发止盈。
• position_liquidated：强平。
• sl_updated：更新止损。
• tp_updated：更新止盈。
• limit_order_created：创建限价单。
• stop_order_created：创建止损入场单。
• order_triggered：执行订单。
• order_closed_user：取消订单。

示例：

query GetTradeHistory($trader: String!) {
  perp {
    tradeHistory(
      where: { trader: $trader }
      limit: 50
      order_by: sequence
      order_desc: true
    ) {
      id
      tradeChangeType
      block {
        block
        block_ts
      }
      trade {
        id
        isLong
        leverage
      }
      realizedPnlCollateral
      realizedPnlPct
    }
  }
}

应用场景：

• 活动列表。
• 仓位修改追踪。
• 已实现盈亏历史。
• 交易操作审计。

---

borrowing

获取指定市场和抵押资产的借贷详情。

签名：

borrowing(collateralId: Int!, marketId: Int!): PerpBorrowing

参数：

• collateralId：抵押代币 ID。
• marketId：市场 ID。

返回： PerpBorrowing 或 null。

示例：

query GetMarketInfo {
  perp {
    borrowing(collateralId: 1, marketId: 1) {
      marketId
      baseToken { symbol name }
      quoteToken { symbol }
      collateralToken { symbol }
      price
      oiLong
      oiShort
      oiMax
      feesPerHourLong
      feesPerHourShort
      openFeePct
      closeFeePct
      triggerOrderFeePct
      maxLeverage
      minLeverage
      minPositionSizeUSD
      visible
    }
  }
}

主要字段说明：

• oiLong / oiShort：多空 OI。
• oiMax：OI 上限。
• feesPerHourLong / feesPerHourShort：每小时借贷费率。
• openFeePct / closeFeePct：开平仓费率。
• maxLeverage / minLeverage：普通市场杠杆范围。
• minPositionSizeUSD：USD 最低仓位规模。

设有交易时段的市场中，maxLeverage 不等于非交易时段上限。检测需要归一化的留仓，使用合约非交易时段查询和 get_trade_data.needs_after_hours_trigger。

应用场景：

• 显示市场信息。
• 计算资金费率。
• 显示可用杠杆。
• 检查 OI 容量。

---

borrowings

列出全部可用市场及基本信息。

签名：

borrowings(
  where: PerpBorrowingsFilter
  limit: Int
  offset: Int
  order_by: PerpBorrowingsOrder
  order_desc: Boolean
): [PerpBorrowingShortInfo!]!

参数：

• where：可选筛选。
  • marketId：市场 ID。
  • collateralId：抵押资产 ID。
• limit：最大数量。
• offset：跳过数量。
• order_by：base_token_name。
• order_desc：降序。

返回： PerpBorrowingShortInfo 数组。

示例：

query ListMarkets {
  perp {
    borrowings(
      order_by: base_token_name
      limit: 20
    ) {
      marketId
      baseToken { symbol name logoUrl }
      quoteToken { symbol }
      collateralToken { symbol }
      visible
    }
  }
}

应用场景：

• 列出可交易市场。
• 构建市场选择器。
• 筛选显示市场。

---

订阅

订阅永续合约数据实时更新。

perpTrades

订阅指定交易者的交易更新。

签名：

subscription {
  perpTrades(where: SubPerpTradesFilter!): [PerpTrade!]!
}

示例：

subscription WatchTrades($trader: String!) {
  perpTrades(where: { trader: $trader }) {
    id
    isOpen
    leverage
    state {
      pnlCollateral
      pnlPct
    }
  }
}

---

perpTradeHistory

订阅指定交易者的交易事件。

签名：

subscription {
  perpTradeHistory(where: SubPerpTradeHistoryFilter!): [PerpTradeHistoryItem!]!
}

示例：

subscription WatchTradeEvents($trader: String!) {
  perpTradeHistory(where: { trader: $trader }) {
    id
    tradeChangeType
    realizedPnlCollateral
    block { block_ts }
  }
}

---

perpBorrowing

订阅指定市场的借贷费率更新。

签名：

subscription {
  perpBorrowing(collateralId: Int!, marketId: Int!): PerpBorrowing
}

示例：

subscription WatchMarket($collateralId: Int!, $marketId: Int!) {
  perpBorrowing(collateralId: $collateralId, marketId: $marketId) {
    price
    oiLong
    oiShort
    feesPerHourLong
    feesPerHourShort
  }
}

---

perpBorrowings

订阅全部市场更新。

签名：

subscription {
  perpBorrowings: [PerpBorrowingShortInfo!]!
}

示例：

subscription WatchAllMarkets {
  perpBorrowings {
    marketId
    baseToken { symbol }
    visible
  }
}

---

类型参考

PerpTrade

type PerpTrade {
  id: Int!
  trader: String!
  isOpen: Boolean!
  isLong: Boolean!
  tradeType: PerpTradeType!
  leverage: Float!
  collateralAmount: Int!
  openCollateralAmount: Int!
  openPrice: Float!
  closePrice: Float
  sl: Float                      # Stop loss price
  tp: Float                      # Take profit price
  perpBorrowing: PerpBorrowingShortInfo!
  openBlock: Block
  closeBlock: Block
  state: PerpTradeState
}

PerpTradeState

包含盈亏和费用的实时仓位状态。

type PerpTradeState {
  pnlCollateral: Float!
  pnlPct: Float!
  pnlCollateralAfterFees: Float!
  positionValue: Float!
  liquidationPrice: Float!
  borrowingFeeCollateral: Float!
  borrowingFeePct: Float!
  closingFeeCollateral: Float!
  closingFeePct: Float!
  remainingCollateralAfterFees: Float!
}

PerpBorrowing

完整市场信息。

type PerpBorrowing {
  marketId: Int!
  baseToken: Token!
  quoteToken: Token!
  collateralToken: Token!
  price: Float!
  oiLong: Int!
  oiShort: Int!
  oiMax: Int!
  feesPerHourLong: Float!
  feesPerHourShort: Float!
  openFeePct: Float!
  closeFeePct: Float!
  triggerOrderFeePct: Float!
  maxLeverage: Float!
  minLeverage: Float!
  minPositionSizeUSD: Int!
  visible: Boolean!
}

枚举

PerpTradeType:

• trade：市价交易。
• limit：限价单。
• stop：止损入场单。

PerpTradeChangeType:

• position_opened
• position_closed_user
• position_closed_sl
• position_closed_tp
• position_liquidated
• sl_updated
• tp_updated
• limit_order_created
• stop_order_created
• order_triggered
• order_closed_user

---