Raze.bot Developers

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 perpetuals with last-24h volume and trade counts.

Arguments

Name	Type	Required	Description
`venue`	`String`	no	Filter 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

Name	Type	Required	Description
`marketId`	`String!`	yes	`jup:SOL-PERP` etc.
`timeframe`	`String`	no	One of `1s`, `1m` (default), `5m`, `15m`, `1h`, `4h`, `1d`.
`limit`	`Int`	no	Default 100, max 2000.
`from`	`String`	no	Inclusive lower bound, ms-since-epoch as a string.
`to`	`String`	no	Inclusive 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

Name	Type	Required	Description
`marketId`	`String!`	yes
`limit`	`Int`	no	Default 100, max 2000.
`from`	`String`	no	Ms-since-epoch as string.
`to`	`String`	no	Ms-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

Name	Type	Required	Description
`marketId`	`String!`	yes
`limit`	`Int`	no	Default 100, max 1000.
`from`	`String`	no	Ms-since-epoch.
`to`	`String`	no	Ms-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

Name	Type	Required	Description
`marketId`	`String!`	yes
`limit`	`Int`	no	Default 100, max 1000.
`from`	`String`	no
`to`	`String`	no

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

Name	Type	Required	Description
`marketId`	`String!`	yes
`state`	`String`	no	`open` (default), `filled`, `cancelled`, `all`.
`limit`	`Int`	no	Default 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

Name	Type	Required	Description
`address`	`String!`	yes	Wallet 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

Name	Type	Required	Description
`address`	`String!`	yes
`limit`	`Int`	no	Default 100, max 1000.
`from`	`String`	no
`to`	`String`	no

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

Name	Type	Required	Description
`address`	`String!`	yes
`limit`	`Int`	no	Default 100, max 1000.
`from`	`String`	no
`to`	`String`	no

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

Name	Type	Required	Description
`address`	`String!`	yes
`state`	`String`	no	`open` (default), `filled`, `cancelled`, `all`.
`limit`	`Int`	no	Default 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

Name	Type	Required	Description
`address`	`String!`	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
  }
}

​perpMarkets

​Arguments

​Return type

​Example

​perpCandles

​Arguments

​Return type

​Example

​perpOi

​Arguments

​Return type

​perpTrades

​Arguments

​Return type

​perpLiquidations

​Arguments

​Return type

​perpMarketOrders

​Arguments

​Return type

​perpWalletPositions

​Arguments

​Return type

​perpWalletTrades

​Arguments

​Return type

​perpWalletLiquidations

​Arguments

​Return type

​perpWalletOrders

​Arguments

​Example

​perpWalletPnl

​Arguments

​Return type

​Combined example

`perpMarkets`

Arguments

Return type

Example

`perpCandles`

Arguments

Return type

Example

`perpOi`

Arguments

Return type

`perpTrades`

Arguments

Return type

`perpLiquidations`

Arguments

Return type

`perpMarketOrders`

Arguments

Return type

`perpWalletPositions`

Arguments

Return type

`perpWalletTrades`

Arguments

Return type

`perpWalletLiquidations`

Arguments

Return type

`perpWalletOrders`

Arguments

Example

`perpWalletPnl`

Arguments

Return type

Combined example