無期限先物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
    }
  }
}

用途：

• 対応市場一覧。
• 市場選択UI。
• 表示市場の絞り込み。

---

サブスクリプション

無期限先物データのリアルタイム更新を購読します。

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

---