Settlement API

Transaction history and audit trail endpoints.

Get Settlement History

Retrieve transaction history for audit purposes.

Endpoint: get_settlement_history(limit: nat64, offset: nat64) -> Result<vec SettlementRecord> (query)

Response

type SettlementRecord = record {
  id: nat64;
  account_id: nat64;
  subaccount_id: nat8;
  asset: text;
  blockchain: Blockchain;
  quantity: int;
  balance_after: opt nat;
  source: SettlementSource;
  related_order_id: opt nat64;
  related_trade_id: opt nat64;
  description: text;
  timestamp: nat64;
};

Settlement Sources

Category	Sources
Deposits & Withdrawals	Deposit, Withdrawal
Order Lifecycle	OrderPlacement, OrderCancellation, TradeFill, PartialFillUnlock
Fees	TradingFeesMaker, TradingFeesTaker, TradingFeesSystem
PnL Realization	RealizePnlManual, RealizePnlAutoClose, RealizePnlAccountThreshold
Liquidation & Risk	LiquidationOnBook, FundingPayment, CollateralConversion
Administrative	AdminAdjustment, ReconciliationAdjustment

Example

const result = await backend.get_settlement_history(100n, 0n)
if ('Ok' in result) {
  result.Ok.forEach((record) => {
    const change = record.quantity >= 0n ? '+' : ''
    console.log(`${record.timestamp}: ${change}${record.quantity} ${record.asset}`)
    console.log(`  ${record.description}`)
  })
}

Get Settlements by Source

Filter settlement records by transaction type.

Endpoint: get_settlements_by_source(source: SettlementSource, limit: nat64) -> Result<vec SettlementRecord> (query)

Example

// Get all trade fills
const result = await backend.get_settlements_by_source(
  { TradeFill: null },
  50n
)

// Get all fee deductions
const fees = await backend.get_settlements_by_source(
  { TradingFeesTaker: null },
  50n
)

Get Settlements by Time Range

Query settlement records within a specific time period.

Endpoint: get_settlements_by_time(from: nat64, to: nat64, limit: nat64) -> Result<vec SettlementRecord> (query)

Example

const now = BigInt(Date.now())
const dayAgo = now - 24n * 60n * 60n * 1000n

const result = await backend.get_settlements_by_time(dayAgo, now, 100n)
if ('Ok' in result) {
  console.log(`${result.Ok.length} settlements in last 24h`)
}

Use Cases

Reconciliation

// Get all deposits
const deposits = await backend.get_settlements_by_source({ Deposit: null }, 1000n)

// Sum deposits by asset
const totals = new Map()
deposits.Ok.forEach(d => {
  const current = totals.get(d.asset) || 0n
  totals.set(d.asset, current + d.quantity)
})

Trade Analysis

// Get trade fills for analysis
const trades = await backend.get_settlements_by_source({ TradeFill: null }, 100n)

// Calculate total volume
let volume = 0n
trades.Ok.forEach(t => {
  volume += t.quantity > 0n ? t.quantity : -t.quantity
})

Fee Tracking

// Track all fees paid
const makerFees = await backend.get_settlements_by_source(
  { TradingFeesMaker: null },
  1000n
)
const takerFees = await backend.get_settlements_by_source(
  { TradingFeesTaker: null },
  1000n
)