Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.raze.bot/llms.txt

Use this file to discover all available pages before exploring further.

GraphQL surface for the perp data model. Mirrors the /api/sol/perp/* REST endpoints field-for-field. All *UsdE6 and price/size integers are native ClickHouse UInt64 returned as Int64-safe values (divide by 1,000,000 for USD-scaled fields). Timestamps are millis-since-epoch. marketId is always <venue>:<SYMBOL>-PERP (e.g. jup:SOL-PERP). Today only jup is supported.

​
perpMarkets

List supported perp markets with last-24h volume and trade counts.

​
Arguments

NameTypeRequiredDescription
venueStringnoFilter to one venue (e.g. "jup"). Defaults to all.

​
Return type

type PerpMarket {
  marketId: String!
  venue: String!
  asset: String!
  volume24hUsd: Int!
  trades24h: Int!
}
volume24hUsd is in USDC e6 (Jupiter size_usd_delta convention).

​
Example

query { perpMarkets(venue: "jup") { marketId asset volume24hUsd trades24h } }

​
perpCandles

OHLCV candles per market and timeframe. Backed by perp_ohlcv_{1s,1m,5m,15m,1h,4h,1d}.

​
Arguments

NameTypeRequiredDescription
marketIdString!yesjup:SOL-PERP etc.
timeframeStringnoOne of 1s, 1m (default), 5m, 15m, 1h, 4h, 1d.
limitIntnoDefault 100, max 2000.
fromStringnoInclusive lower bound, ms-since-epoch as a string.
toStringnoInclusive upper bound, ms-since-epoch as a string.

​
Return type

type PerpCandle {
  timestamp: Int!     # ms since epoch
  open: Float!
  high: Float!
  low: Float!
  close: Float!
  volumeUsd: Float!   # USD (decimal, NOT e6)
  tradeCount: Int!
}

​
Example

query {
  perpCandles(marketId: "jup:SOL-PERP", timeframe: "1m", limit: 60) {
    timestamp open close volumeUsd
  }
}

​
perpOi

Per-minute open-interest series sampled from perp_positions. Read this alongside perpCandles to overlay long/short OI on the chart.

​
Arguments

NameTypeRequiredDescription
marketIdString!yes
limitIntnoDefault 100, max 2000.
fromStringnoMs-since-epoch as string.
toStringnoMs-since-epoch as string.

​
Return type

type PerpOiPoint {
  timestamp: Int!
  longOiUsdE6: Int!
  shortOiUsdE6: Int!
  positionCount: Int!
}

​
perpTrades

Recent fills (taker prints) on a market, newest first.

​
Arguments

NameTypeRequiredDescription
marketIdString!yes
limitIntnoDefault 100, max 1000.
fromStringnoMs-since-epoch.
toStringnoMs-since-epoch.

​
Return type

type PerpTrade {
  timestamp: Int!
  slot: Int!
  signature: String!
  signer: String!
  side: String!     # "long" | "short"
  size: Int!        # USDC e6
  price: Int!       # USDC e6 per unit base asset
  fee: Int!         # USDC e6
}

​
perpLiquidations

Liquidation events on a market, newest first.

​
Arguments

NameTypeRequiredDescription
marketIdString!yes
limitIntnoDefault 100, max 1000.
fromStringno
toStringno

​
Return type

type PerpLiquidation {
  timestamp: Int!
  slot: Int!
  signature: String!
  signer: String!       # liquidated wallet
  positionPubkey: String!
  side: String!
  sizeClosed: Int!      # USDC e6
  oraclePrice: Int!     # USDC e6
  fee: Int!             # USDC e6
}

​
perpMarketOrders

Pending or historical trigger orders on a market — feeds the orderbook view. Aggregates the multi-row perp_orders event log per orderId via argMax. Excludes orders whose underlying position has been liquidated or fully closed.

​
Arguments

NameTypeRequiredDescription
marketIdString!yes
stateStringnoopen (default), filled, cancelled, all.
limitIntnoDefault 100, max 2000.

​
Return type

type PerpOrder {
  orderId: String!         # position_request PDA
  owner: String!
  marketId: String!
  venue: String!
  positionPubkey: String!
  kind: String!            # "limit" | "take_profit" | "stop_loss"
  side: String!
  state: String!           # "open" | "updated" | "filled" | "cancelled"
  sizeUsd: Int!            # USDC e6
  collateral: Int!
  triggerPrice: Int!       # USDC e6
  triggerAbove: Boolean!
  entirePosition: Boolean!
  createdSlot: Int!
  createdTs: Int!
  updatedSlot: Int!
  updatedTs: Int!
  lastSignature: String!
}
triggerAbove encodes the comparison direction: true = fire when oracle ≥ triggerPrice, false = fire when oracle ≤ triggerPrice. The combination with side derives whether the order is a TP or SL.

​
perpWalletPositions

Open positions for one wallet. Latest row per position_pubkey from perp_positions FINAL where is_open = 1.

​
Arguments

NameTypeRequiredDescription
addressString!yesWallet pubkey, ≥ 32 chars.

​
Return type

type PerpPosition {
  marketId: String!
  venue: String!
  positionPubkey: String!
  side: String!
  size: Int!            # USDC e6
  entryPrice: Int!      # USDC e6
  collateral: Int!      # USDC e6
  unrealizedPnl: Int!   # USDC e6, signed
  slot: Int!
  snapshotTs: Int!      # ms since epoch
  isOpen: Boolean!
}
These are derived snapshots from streaming events. For a live RPC truth-path read, use the trading-side oracle path; this query intentionally returns ClickHouse-derived state.

​
perpWalletTrades

Fills for one wallet across every market.

​
Arguments

NameTypeRequiredDescription
addressString!yes
limitIntnoDefault 100, max 1000.
fromStringno
toStringno

​
Return type

type PerpWalletTrade {
  timestamp: Int!
  marketId: String!
  venue: String!
  signature: String!
  side: String!
  size: Int!
  price: Int!
  fee: Int!
  positionPubkey: String!
}

​
perpWalletLiquidations

Liquidation events for one wallet across every market.

​
Arguments

NameTypeRequiredDescription
addressString!yes
limitIntnoDefault 100, max 1000.
fromStringno
toStringno

​
Return type

type PerpWalletLiquidation {
  timestamp: Int!
  slot: Int!
  marketId: String!
  venue: String!
  signature: String!
  positionPubkey: String!
  side: String!
  sizeClosed: Int!
  oraclePrice: Int!
  fee: Int!
}

​
perpWalletOrders

Pending or historical trigger orders for one wallet. Same PerpOrder shape as perpMarketOrders.

​
Arguments

NameTypeRequiredDescription
addressString!yes
stateStringnoopen (default), filled, cancelled, all.
limitIntnoDefault 100, max 1000.

​
Example

query {
  perpWalletOrders(address: "62ThHC1rs2GUfa8J4Qjcj5GD2MSL2d65pcJtenNieDnm", state: "open") {
    orderId marketId kind side triggerPrice sizeUsd entirePosition updatedTs
  }
}

​
perpWalletPnl

Per-(market, venue) volume and fees aggregate for one wallet. Sourced from the _mv_perp_wallet_positions materialized view.

​
Arguments

NameTypeRequiredDescription
addressString!yes

​
Return type

type PerpWalletPnl {
  marketId: String!
  venue: String!
  longSize: Int!         # USDC e6, total long-side size traded
  shortSize: Int!        # USDC e6
  volumeUsdE6: Int!
  feesPaidE6: Int!
  grossPnlE6: Int!       # 0 — pending real PnL field decoding
  netPnlE6: Int!         # currently -feesPaidE6 (placeholder)
  firstFillTs: Int!
  lastFillTs: Int!
}
grossPnlE6 is intentionally 0 until the parser surfaces realized PnL; netPnlE6 exposes only the negative-fees component to make this state explicit. Don’t display either as “PnL” until both fields are populated.

​
Combined example

A single round trip pulling everything a position dashboard needs: 
query Dashboard($wallet: String!) {
  positions: perpWalletPositions(address: $wallet) {
    marketId side size entryPrice unrealizedPnl
  }
  orders: perpWalletOrders(address: $wallet, state: "open") {
    orderId marketId kind side triggerPrice
  }
  pnl: perpWalletPnl(address: $wallet) {
    marketId volumeUsdE6 feesPaidE6
  }
  recentFills: perpWalletTrades(address: $wallet, limit: 20) {
    timestamp marketId side size price
  }
}