Perp API

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

Table of Contents

• Perp API Reference

  • Table of Contents

  • Queries

    • trade

    • trades

    • tradeHistory

    • borrowing

    • borrowings

  • Subscriptions

    • perpTrades

    • perpTradeHistory

    • perpBorrowing

    • perpBorrowings

  • Types Reference

    • PerpTrade

    • PerpTradeState

    • PerpBorrowing

    • Enums

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

---