Perp API

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

Table of Contents

Queries

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

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

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

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: Leverage limits

  • minPositionSizeUSD: Minimum position size in USD

Use Cases:

  • Display market information

  • Calculate funding rates

  • Show available leverage

  • Check market capacity (OI limits)

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

Subscribe to real-time updates for perpetual trading data.

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

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

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

Subscribe to updates for all markets.

Signature:

subscription {
  perpBorrowings: [PerpBorrowingShortInfo!]!
}

Example:

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

Types Reference

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

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

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

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

Next: LP API Reference | Back to Introduction

PreviousCore ConceptsNextLiquidity Provider (LP) API

Last updated