Skip to content
Sai

Perp API Reference

Query and subscribe to perpetual trading data including positions, trade history, market borrowing rates, and referrals.

Table of Contents

Section titled “Table of Contents”

Queries

Section titled “Queries”

trade

Section titled “trade”

Get a specific trade by ID and trader address.

Signature:

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

Parameters:

  • id: Trade ID (integer)
  • trader: Trader’s wallet address (required)

Returns: PerpTrade object or null if not found

Example:

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

Use Cases:

  • Display single trade details
  • Track specific position status
  • Calculate current PnL

trades

Section titled “trades”

List trades with filtering, pagination, and ordering.

Signature:

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

Parameters:

  • where: Filter object (required)
    • trader: Trader address (required)
    • isOpen: Filter by open/closed status
    • perpMarketId: Filter by market ID
    • perpCollateralId: Filter by collateral token ID
  • limit: Max results (default: 100)
  • offset: Skip results for pagination
  • order_by: Sort field (sequence only)
  • order_desc: Sort descending (default: false)

Returns: Array of PerpTrade objects

Example - Get Open Positions:

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

Example - Filter by Market:

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

Use Cases:

  • List user’s open positions
  • Display trading history
  • Filter by specific markets
  • Build position dashboard

tradeHistory

Section titled “tradeHistory”

Get trade events and position changes.

Signature:

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

Parameters:

  • where: Filter object (required)
    • trader: Trader address (required)
  • limit: Max results (default: 100)
  • offset: Skip results
  • order_by: Sort by sequence or trade_id
  • order_desc: Sort descending

Returns: Array of PerpTradeHistoryItem objects

Trade Change Types:

  • position_opened: New position created
  • position_closed_user: User closed position
  • position_closed_sl: Stop loss triggered
  • position_closed_tp: Take profit triggered
  • position_liquidated: Position liquidated
  • sl_updated: Stop loss updated
  • tp_updated: Take profit updated
  • limit_order_created: Limit order placed
  • stop_order_created: Stop order placed
  • order_triggered: Order executed
  • order_closed_user: Order cancelled

Example:

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

Use Cases:

  • Build activity feed
  • Track position modifications
  • Calculate realized PnL history
  • Audit trade actions

borrowing

Section titled “borrowing”

Get detailed borrowing information for a specific market and collateral.

Signature:

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

Parameters:

  • collateralId: Collateral token ID
  • marketId: Market ID

Returns: PerpBorrowing object or null

Example:

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

Key Fields Explained:

  • oiLong / oiShort: Open interest for longs/shorts
  • oiMax: Maximum allowed open interest
  • feesPerHourLong / feesPerHourShort: Borrowing rate (per hour)
  • openFeePct / closeFeePct: Opening/closing fee percentages
  • maxLeverage / minLeverage: Standard market leverage limits
  • minPositionSizeUSD: Minimum position size in USD

For scheduled markets, maxLeverage is not the same as the after-hours effective leverage cap. If your integration needs to detect carried positions that require after-hours normalization, use the perp contract’s after-hours queries and get_trade_data.needs_after_hours_trigger.

Use Cases:

  • Display market information
  • Calculate funding rates
  • Show available leverage
  • Check market capacity (OI limits)

borrowings

Section titled “borrowings”

List all available markets with basic information.

Signature:

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

Parameters:

  • where: Filter object (optional)
    • marketId: Filter by market ID
    • collateralId: Filter by collateral ID
  • limit: Max results
  • offset: Skip results
  • order_by: Sort by base_token_name
  • order_desc: Sort descending

Returns: Array of PerpBorrowingShortInfo objects

Example:

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

Use Cases:

  • List all tradeable markets
  • Build market selector
  • Filter visible markets

Subscriptions

Section titled “Subscriptions”

Subscribe to real-time updates for perpetual trading data.

perpTrades

Section titled “perpTrades”

Subscribe to trade updates for a specific trader.

Signature:

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

Example:

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

perpTradeHistory

Section titled “perpTradeHistory”

Subscribe to trade events for a specific trader.

Signature:

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

Example:

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

perpBorrowing

Section titled “perpBorrowing”

Subscribe to borrowing rate updates for a specific market.

Signature:

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

Example:

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

perpBorrowings

Section titled “perpBorrowings”

Subscribe to updates for all markets.

Signature:

subscription {
  perpBorrowings: [PerpBorrowingShortInfo!]!
}

Example:

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

Types Reference

Section titled “Types Reference”

PerpTrade

Section titled “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

Section titled “PerpTradeState”

Real-time position state with PnL and fees.

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

PerpBorrowing

Section titled “PerpBorrowing”

Complete market information.

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

Enums

Section titled “Enums”

PerpTradeType:

  • trade: Market trade
  • limit: Limit order
  • stop: Stop order

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