Query Reference

Return shapes for additional spot canister queries. These are not required for the core agent loop — load this page only when you need a specific endpoint's return type.

For core types (PollVersions, RoutingState, UserData), see Trading Overview.

Additional Spot Queries

Endpoint	Parameters	Returns
`get_market_depth(levels, tick_bucket_size)`	`levels: Nat32`, `tick_bucket_size: Nat32`	`MarketDepthResponse`
`get_transactions(?limit, ?cursor)`	optional limit and cursor	`{ data: [SpotTransactionResponse], next_cursor, has_more }`
`get_chart(interval, ?before_ts, limit)`	chart interval, optional cursor, limit	`{ data: [SpotCandle], next_cursor, has_more }`
`get_live_candle(interval)`	chart interval	Current incomplete candle
`get_pool(fee_pips)`	fee tier	Full pool state for one tier
`get_pools_overview()`	none	Summary of all active pools
`get_pool_snapshots(fee_pips, ?before_ts, limit, interval_hours)`	pool tier + pagination	Historical pool state snapshots
`get_market_snapshots(?before_ts, limit, interval_hours)`	pagination	Historical market state snapshots
`get_position(id)`	position ID	Single `PositionView` (or null)
`get_balance_sheet()`	none	Full financial invariant snapshot
`get_user_activity(?cursor, ?limit)`	optional chain cursor + limit	`{ data: [ActivityView], next_cursor, has_more }`
`get_control()`	none	Control plane state (system state, config, admin principals)
`get_lock_schedule()`	none	Liquidity lock summary
`get_hydration(interval, chart_limit, levels, tick_bucket_size)`	combined bootstrap params	Platform + user + chart + trades in one call
`get_platform(interval, levels, tick_bucket_size)`	chart interval + depth params	Platform data (candle + depth + stats)

`get_market_depth()` Return Shape

MarketDepthResponse {
  version: Nat,                          // max(platform_version, orderbook_version)
  last_trade_sqrt_price_x96: Nat,        // last trade price for display
  book_bids: [{ tick, amount, order_count }],  // aggregated limit orders (quote amounts)
  book_asks: [{ tick, amount, order_count }],  // aggregated limit orders (base amounts)
  pools: [{                              // per-pool liquidity curves
    fee_pips, tick_spacing, current_tick, sqrt_price_x96,
    liquidity, initialized_ticks: [{ tick, liquidity_net, liquidity_gross }]
  }]
}

Query Return Shapes

SpotTransactionResponse {
  id: Nat64,
  side: Side,
  timestamp: Nat64,
  base_amount: Nat,
  quote_amount: Nat,
  price_e12: Nat64,
  usd_value_e6: Nat64,
}

PoolState {
  fee_pips: Nat32,
  tick: Tick,
  tick_spacing: Nat,
  sqrt_price_x96: SqrtPriceX96,
  liquidity: Nat,
  base_reserve: Nat,
  quote_reserve: Nat,
  tvl_usd_e6: Nat,
  volume_24h_usd_e6: Nat,
  fees_24h_usd_e6: Nat,
  apr_bps: Nat,
  initialized_ticks: [{ tick: Tick, liquidity_net: Int, liquidity_gross: Nat }],
}

PoolOverview {
  fee_pips: Nat32,
  tick: Tick,
  positions: Nat,
  base_usd_e6: Nat,
  quote_usd_e6: Nat,
  volume_24h_usd_e6: Nat,
  apr_bps: Nat,
}

PositionView vs PositionViewEnhanced

get_position() returns PositionView (below). get_user().positions returns PositionViewEnhanced (shown in Trading Overview) which adds computed fields like amount_base, amount_quote, fees_base, fees_quote, usd_value_e6, fees_usd_value_e6, apr_bps. They are not interchangeable.

PositionView {
  position_id: PositionId,
  owner: Principal,
  fee_pips: Nat32,
  tick_lower: Tick,
  tick_upper: Tick,
  liquidity: Nat,
  fee_growth_inside_base_last_x128: Nat,
  fee_growth_inside_quote_last_x128: Nat,
  uncollected_fees_base: Nat,
  uncollected_fees_quote: Nat,
  locked_until: ?Nat64,
}

BalanceSheet {
  is_balanced: Bool,
  drift_base: Int,
  drift_quote: Int,
  expected_base: Nat,
  expected_quote: Nat,
  assets: AssetsBreakdown,             // { total, base_balance, quote_balance }
  liabilities: LiabilitiesBreakdown,   // { total, total_base, total_quote, available_*, orders_*, triggers_*, pool_reserves_*, pending_*, orders_output_* }
  equity: EquityBreakdown,             // { total, total_base, total_quote, available_*, pool_fees_*, book_fees_*, op_fees_*, fees_paid_*, withdrawn_* }
  protocol_equity: ProtocolEquitySummary,  // { available, pool_fees, book_fees, op_fees, withdrawn, fees_paid } — each is (Nat, Nat) tuple (base, quote)
  net_tracking: NetTracking,           // { net_external_base/quote, net_swap_base/quote, net_lp_base/quote, total_net_base/quote }
  users_debug: AllUsersDebug,          // aggregate user stats
  pool_invariants: { all_pools_healthy: Bool, unhealthy_pools: [Nat32], pools: [PoolInvariantStatus] },
}

ActivityView {
  activity_id: Nat64,
  activity_type: ActivityType,
  timestamp_ms: Nat64,
  quote_usd_e12: Nat64,
  details: ActivityDetails,
}

// ActivityType variants:
//   #order_batch | #order_filled | #order_partial | #order_cancelled | #order_modified
//   #trigger_batch | #trigger_fired | #trigger_cancelled
//   #lp_opened | #lp_increased | #lp_decreased | #lp_closed | #lp_fees_collected | #lp_transferred | #lp_locked
//   #swap | #transfer_in | #transfer_out

// ActivityDetails — one of:
//   #order:    { order_id, side, tick, locked_input, input_spent, output_received, fees_paid, immediate_or_cancel, created_at_ms }
//   #trigger:  { trigger_id, side, trigger_tick, limit_tick, trigger_type, input_amount, immediate_or_cancel, created_at_ms, resulting_order_id: ?Nat64 }
//   #liquidity: { position_id, fee_pips, tick_lower, tick_upper, tick_at_event, liquidity_delta, amount_base, amount_quote }
//   #position_transfer: { position_id, fee_pips, tick_lower, tick_upper, liquidity, counterparty: Principal, direction: #sent | #received }
//   #batch:    { item_count, swap_count, total_base_locked, total_quote_locked, op_fee_token: #base | #quote, op_fee_amount, base_price_usd_e12, quote_price_usd_e12 }
//   #transfer: { token: #base | #quote, amount, direction: #inbound | #outbound, ledger_principal, ledger_fee, block_index: ?Nat64, token_price_usd_e12 }

FrozenControl {
  system_state: SystemState,
  market_initialized: Bool,
  timer_running: Bool,
  base: { fee: Nat, decimals: Nat8, ledger: Principal },
  quote: { fee: Nat, decimals: Nat8, ledger: Principal },
  maker_fee_pips: Nat32,
  taker_fee_pips: Nat32,
  maker_rebate_pips: Nat32,
  pool_protocol_fee_pips: Nat,
  instruction_budget: Nat64,
  cycles_threshold: Nat,
  max_entries_per_user: Nat,
  max_positions_per_user: Nat,
  max_route_pool_inputs: Nat,
  min_usd_value: Nat,
  min_pool_quote_liquidity_e6: Nat,
  users: Nat,
  pools: Nat,
  positions: Nat,
  orders_live: Nat,
  triggers_live: Nat,
  this_principal: Principal,
  oracle_principal: Principal,
  indexer_principal: Principal,
  registry_principal: Principal,
  treasury_principal: ?Principal,
  admin_principals: [Principal],
}

LiquidityLockSummary {
  total_position_count: Nat,
  locked_position_count: Nat,
  total_locked_base: Nat,
  total_locked_quote: Nat,
  total_unlocked_base: Nat,
  total_unlocked_quote: Nat,
  total_locked_base_usd_e6: Nat,
  total_locked_quote_usd_e6: Nat,
  total_unlocked_base_usd_e6: Nat,
  total_unlocked_quote_usd_e6: Nat,
  schedule: [LockScheduleEntry],
}

LockScheduleEntry {
  position_id: PositionId,
  fee_pips: Nat32,
  liquidity: Nat,
  amount_base: Nat,
  amount_quote: Nat,
  base_usd_e6: Nat,
  quote_usd_e6: Nat,
  locked_until_ms: Nat64,
}

PlatformData {
  // Price & fees
  reference_tick: ?Tick,
  last_book_tick: ?Tick,
  last_trade_tick: ?Tick,
  last_trade_sqrt_price_x96: ?SqrtPriceX96,
  current_price_usd_e12: Nat,
  quote_usd_rate_e12: Nat,
  maker_fee_pips: Nat32,
  taker_fee_pips: Nat32,
  maker_rebate_pips: Nat32,
  price_change_24h_bps: Int,
  // Stats
  users: Nat,
  orders_live: Nat,
  triggers_live: Nat,
  total_positions: Nat,
  total_transactions: Nat64,
  liquidity: Nat,
  volume_24h_usd_e6: Nat,
  // Depth (USD)
  book_depth_base_usd_e6: Nat,
  book_depth_quote_usd_e6: Nat,
  pool_depth_base_usd_e6: Nat,
  pool_depth_quote_usd_e6: Nat,
  // Nested
  candle: CandleData,                   // current candle for requested interval
  market_depth: MarketDepthResponse,     // full depth snapshot
}

HydrateResponse {
  versions: PollVersions,
  user: UserData,                        // same as get_user() return
  platform: PlatformData,               // same as get_platform() return
  chart: { data: [SpotCandle], next_cursor: ?Nat64, has_more: Bool },
  recent_trades: { data: [SpotTransactionResponse], next_cursor: ?Nat64, has_more: Bool },
}

MarketSnapshotView {
  timestamp: Nat64,
  users: Nat,
  orders_live: Nat,
  triggers_live: Nat,
  total_positions: Nat,
  total_transactions: Nat64,
  reference_price_e12: Nat,
  quote_usd_rate_e12: Nat,
  base_custody: Nat,
  quote_custody: Nat,
  pool_base_reserve: Nat,
  pool_quote_reserve: Nat,
  book_open_interest_base: Nat,
  book_open_interest_quote: Nat,
  trigger_locked_base: Nat,
  trigger_locked_quote: Nat,
  protocol_equity_base: Nat,
  protocol_equity_quote: Nat,
  book_volume_quote: Nat,
  book_volume_usd_e6: Nat,
  book_fees_usd_e6: Nat,
  pool_volume_quote: Nat,
  pool_volume_usd_e6: Nat,
  pool_fees_usd_e6: Nat,
}
// Returned wrapped: { data: [MarketSnapshotView], next_cursor: ?Nat64, has_more: Bool }

PoolSnapshotView {
  timestamp: Nat64,
  base_reserve: Nat,
  quote_reserve: Nat,
  volume_quote: Nat,
  volume_usd_e6: Nat,
  fees_usd_e6: Nat,
}
// Returned wrapped: { data: [PoolSnapshotView], next_cursor: ?Nat64, has_more: Bool }

Additional Spot Queries​

get_market_depth() Return Shape​

Query Return Shapes​

Additional Spot Queries

`get_market_depth()` Return Shape

Query Return Shapes