Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Proof-labs/trading-sdk/llms.txt

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

The Proof exchange engine emits a stream of strongly-typed events each time state changes — orders fill, positions open and close, funding is applied, and accounts are liquidated. These events are delivered via the WebSocket feed at wss://api.dev.proof.trade/ws and surfaced in the SDK through client.subscribeBlocks. Every variant belongs to the ExchangeEvent discriminated union and is identified by a string type field.
All string fields in exchange events carry stringified numbers, not native numeric types. For example, price: "6675234" represents $66,752.34 (integer cents). Parse with BigInt(event.price) when arithmetic precision is required.

ExchangeEvent union type

type ExchangeEvent =
  | OrderPlacedEvent
  | OrderCancelledEvent
  | TradeExecutedEvent
  | FeesCollectedEvent
  | DepositedEvent
  | WithdrawnEvent
  | PositionUpdatedEvent
  | PositionClosedEvent
  | PriceUpdatedEvent
  | MarketCreatedEvent
  | AccountLiquidatedEvent
  | FundingAppliedEvent
  | FundingSettledEvent
  | AgentApprovedEvent
  | AgentRevokedEvent
  | MarketOrderProcessedEvent
  | OrderbookLevelUpdatedEvent;
Dispatch on event.type to narrow to a specific variant:
const unsub = client.subscribeBlocks((event: ExchangeEvent) => {
  if (event.type === "TradeExecuted") {
    const fillPrice = BigInt(event.price);        // cents → bigint
    const qty       = BigInt(event.quantity);
    console.log(
      `Fill on market ${event.market}: ${qty} contracts @ ${fillPrice} cents`,
      `maker=${event.makerOwner} taker=${event.takerOwner}`
    );
  }

  if (event.type === "FundingSettled") {
    const payment = BigInt(event.payment);
    console.log(
      payment >= 0n
        ? `Received ${payment} µUSDC funding`
        : `Paid ${-payment} µUSDC funding`
    );
  }

  if (event.type === "AccountLiquidated") {
    console.warn(`Liquidation: owner=${event.owner} market=${event.market}`);
  }
});

// Stop listening when done
unsub();

OrderPlacedEvent

Emitted when a limit order is successfully placed on the order book.
interface OrderPlacedEvent {
  type: "OrderPlaced";
  orderId: string;
  market: string;
  owner: string;
  side: string;
  price: string;
  quantity: string;
  clientOrderId: string;
}
type
"OrderPlaced"
required
Event discriminator.
orderId
string
required
Engine-assigned order ID (stringified integer, monotonically increasing within a market).
market
string
required
Market identifier as a decimal string.
owner
string
required
Hex-encoded 20-byte owner address.
side
string
required
Order side: "Buy" or "Sell".
price
string
required
Limit price in cents with 2 decimal places (e.g., "6675234" = $66,752.34).
quantity
string
required
Order quantity in integer contracts.
clientOrderId
string
required
Client-assigned order ID, or "0" when absent.

OrderCancelledEvent

Emitted when a resting order is cancelled, whether by the user, by a liquidation, or due to a TTL expiry.
interface OrderCancelledEvent {
  type: "OrderCancelled";
  orderId: string;
  market: string;
  owner: string;
  reason: string;
  originalQuantity: string;
  remainingQuantity: string;
  filledQuantity: string;
  clientOrderId: string;
}
type
"OrderCancelled"
required
Event discriminator.
orderId
string
required
Engine-assigned order ID.
market
string
required
Market identifier as a decimal string.
owner
string
required
Hex-encoded 20-byte owner address.
reason
string
required
Human-readable cancellation reason (e.g., "user_requested", "liquidation", "ttl_expired").
originalQuantity
string
required
Quantity originally accepted onto the book in integer contracts.
remainingQuantity
string
required
Quantity still resting at the moment of cancellation.
filledQuantity
string
required
Cumulative maker quantity filled before cancellation.
clientOrderId
string
required
Client-assigned order ID, or "0" when absent.

TradeExecutedEvent

Emitted when a fill is matched between a maker (resting) order and a taker (crossing) order. One TradeExecutedEvent is emitted per individual fill.
interface TradeExecutedEvent {
  type: "TradeExecuted";
  fillId: string;
  market: string;
  price: string;
  quantity: string;
  makerOrderId: string;
  makerClientOrderId: string;
  makerOwner: string;
  makerSide: string;
  takerOwner: string;
  takerClientOrderId: string;
  takerFee: string;
  makerFee: string;
}
type
"TradeExecuted"
required
Event discriminator.
fillId
string
required
Unique fill identifier for this specific match.
market
string
required
Market identifier as a decimal string.
price
string
required
Execution price in cents (2 decimal places).
quantity
string
required
Fill quantity in integer contracts.
makerOrderId
string
required
Engine-assigned order ID of the resting (maker) order.
makerClientOrderId
string
required
Maker’s client-assigned order ID, or "0" when absent.
makerOwner
string
required
Hex-encoded 20-byte address of the maker.
makerSide
string
required
Side of the maker’s order: "Buy" or "Sell".
takerOwner
string
required
Hex-encoded 20-byte address of the taker.
takerClientOrderId
string
required
Taker’s client-assigned order ID, or "0" when absent.
takerFee
string
required
Taker fee in microUSDC. Current engine emits non-negative charges.
makerFee
string
required
Maker fee in microUSDC. Current engine emits non-negative charges (rebates appear as credits via FeesCollectedEvent).

FeesCollectedEvent

Emitted alongside each TradeExecutedEvent to provide a per-fill fee summary. Both events arrive in the same block.
interface FeesCollectedEvent {
  type: "FeesCollected";
  market: string;
  takerOwner: string;
  takerFee: string;
  makerOwner: string;
  makerFee: string;
}
type
"FeesCollected"
required
Event discriminator.
market
string
required
Market identifier as a decimal string.
takerOwner
string
required
Hex-encoded 20-byte address of the taker.
takerFee
string
required
Taker fee in microUSDC (signed).
makerOwner
string
required
Hex-encoded 20-byte address of the maker.
makerFee
string
required
Maker fee in microUSDC (signed).

DepositedEvent

Emitted when USDC is credited to an account (via ConfirmDeposit or the legacy Deposit action).
interface DepositedEvent {
  type: "Deposited";
  owner: string;
  amount: string;
  newBalance: string;
}
type
"Deposited"
required
Event discriminator.
owner
string
required
Hex-encoded 20-byte owner address.
amount
string
required
Deposited amount in microUSDC (6 decimal places).
newBalance
string
required
Account balance after the deposit in microUSDC.

WithdrawnEvent

Emitted when USDC is debited from an account.
interface WithdrawnEvent {
  type: "Withdrawn";
  owner: string;
  amount: string;
  newBalance: string;
}
type
"Withdrawn"
required
Event discriminator.
owner
string
required
Hex-encoded 20-byte owner address.
amount
string
required
Withdrawn amount in microUSDC (6 decimal places).
newBalance
string
required
Account balance after the withdrawal in microUSDC.

PositionUpdatedEvent

Emitted when a position is opened or when its size or entry price changes due to a fill. Reflects the position state after the mutation.
interface PositionUpdatedEvent {
  type: "PositionUpdated";
  owner: string;
  market: string;
  side: string;
  entryPrice: string;
  size: string;
}
type
"PositionUpdated"
required
Event discriminator.
owner
string
required
Hex-encoded 20-byte owner address.
market
string
required
Market identifier as a decimal string.
side
string
required
Position side: "Buy" = long, "Sell" = short.
entryPrice
string
required
Weighted-average entry price in cents (2 decimal places) after the fill.
size
string
required
Absolute position size in integer contracts after the fill.

PositionClosedEvent

Emitted when a position is fully closed (size reaches zero).
interface PositionClosedEvent {
  type: "PositionClosed";
  owner: string;
  market: string;
  realizedPnl: string;
}
type
"PositionClosed"
required
Event discriminator.
owner
string
required
Hex-encoded 20-byte owner address.
market
string
required
Market identifier as a decimal string.
realizedPnl
string
required
Realized PnL in microUSDC (signed). Positive = profit, negative = loss.

PriceUpdatedEvent

Emitted when the oracle price is updated for a market.
interface PriceUpdatedEvent {
  type: "PriceUpdated";
  market: string;
  price: string;
}
type
"PriceUpdated"
required
Event discriminator.
market
string
required
Market identifier as a decimal string.
price
string
required
New oracle price in cents (2 decimal places).

MarketCreatedEvent

Emitted when a new perpetual market is registered on the exchange.
interface MarketCreatedEvent {
  type: "MarketCreated";
  market: string;
  imBps: string;
  mmBps: string;
  takerFeeBps: string;
  makerFeeBps: string;
  fundingIntervalMs: string;
  maxFundingRateBps: string;
}
type
"MarketCreated"
required
Event discriminator.
market
string
required
Market identifier as a decimal string.
imBps
string
required
Initial margin requirement in basis points.
mmBps
string
required
Maintenance margin requirement in basis points.
takerFeeBps
string
required
Taker fee rate in basis points.
makerFeeBps
string
required
Maker fee rate in basis points.
fundingIntervalMs
string
required
Funding payment interval in milliseconds. "0" = funding disabled.
maxFundingRateBps
string
required
Maximum absolute funding rate per interval in basis points.

AccountLiquidatedEvent

Emitted when an account is liquidated because its maintenance margin falls below the required threshold.
interface AccountLiquidatedEvent {
  type: "AccountLiquidated";
  owner: string;
  market: string;
  side: string;
  size: string;
  markPrice: string;
  realizedPnl: string;
}
type
"AccountLiquidated"
required
Event discriminator.
owner
string
required
Hex-encoded 20-byte address of the liquidated account.
market
string
required
Market identifier as a decimal string.
side
string
required
Side of the liquidated position: "Buy" or "Sell".
size
string
required
Liquidated position size in integer contracts.
markPrice
string
required
Mark price at the time of liquidation in cents (2 decimal places).
realizedPnl
string
required
Realized PnL from the liquidation in microUSDC (signed).

FundingAppliedEvent

Emitted once per funding interval when periodic funding is settled across a market. Provides the market-wide funding rate and updated cumulative index.
interface FundingAppliedEvent {
  type: "FundingApplied";
  market: string;
  fundingRateBps: string;
  cumulativeFunding: string;
  timestampMs: string;
}
type
"FundingApplied"
required
Event discriminator.
market
string
required
Market identifier as a decimal string.
fundingRateBps
string
required
Funding rate for this interval in basis points (signed). Positive = longs pay shorts; negative = shorts pay longs.
cumulativeFunding
string
required
Cumulative funding index after this application (signed). Used to compute per-position accrued funding.
timestampMs
string
required
Block timestamp in milliseconds at which funding was applied.

FundingSettledEvent

Emitted once per open position when funding is settled. Follows the market-level FundingAppliedEvent in the same block.
interface FundingSettledEvent {
  type: "FundingSettled";
  owner: string;
  market: string;
  payment: string;
}
type
"FundingSettled"
required
Event discriminator.
owner
string
required
Hex-encoded 20-byte owner address.
market
string
required
Market identifier as a decimal string.
payment
string
required
Funding payment in microUSDC (signed). Positive = received (credit to account), negative = paid (debit from account).

AgentApprovedEvent

Emitted when an owner approves a delegate agent wallet to trade on their behalf. The agent can place and cancel orders but cannot withdraw or move funds.
interface AgentApprovedEvent {
  type: "AgentApproved";
  owner: string;
  agent: string;
  agentPubkey: string;
}
type
"AgentApproved"
required
Event discriminator.
owner
string
required
Hex-encoded 20-byte address of the account granting delegation.
agent
string
required
Hex-encoded 20-byte derived address of the agent wallet.
agentPubkey
string
required
Hex-encoded 32-byte Ed25519 public key of the agent.

AgentRevokedEvent

Emitted when an owner revokes a previously approved agent wallet.
interface AgentRevokedEvent {
  type: "AgentRevoked";
  owner: string;
  agent: string;
  agentPubkey: string;
}
type
"AgentRevoked"
required
Event discriminator.
owner
string
required
Hex-encoded 20-byte address of the account revoking the delegation.
agent
string
required
Hex-encoded 20-byte derived address of the revoked agent wallet.
agentPubkey
string
required
Hex-encoded 32-byte Ed25519 public key of the revoked agent.

MarketOrderProcessedEvent

Emitted exactly once at the end of every market-order transaction that passes envelope validation, regardless of how many fills occurred. This is the authoritative fill-status signal for market orders.
interface MarketOrderProcessedEvent {
  type: "MarketOrderProcessed";
  market: string;
  owner: string;
  side: string;
  requestedQuantity: string;
  filledQuantity: string;
  clientOrderId?: string;
}
Use filledQuantity to determine the outcome of your market order:
ConditionMeaning
filledQuantity == requestedQuantityFully filled
0 < filledQuantity < requestedQuantityPartial fill; IOC remainder was dropped
filledQuantity == "0"No fills — no counterparty available, or all were rejected by self-match prevention
Without this event, callers would need to count downstream TradeExecutedEvent emissions and could not distinguish “no counterparty” from “events arrived in a different stream view.”
type
"MarketOrderProcessed"
required
Event discriminator.
market
string
required
Market identifier as a decimal string.
owner
string
required
Hex-encoded 20-byte address of the market order submitter.
side
string
required
Side of the original market order: "Buy" or "Sell".
requestedQuantity
string
required
Quantity originally requested in integer contracts.
filledQuantity
string
required
Quantity actually filled before the IOC drop in integer contracts.
clientOrderId
string
Client-assigned order ID of the IOC, market-order, or close-position request. Absent when no clientOrderId was provided.

OrderbookLevelUpdatedEvent

Emitted after every mutation to a price level in the order book. Carries the absolute post-mutation state (not a delta), so listeners can maintain a local book snapshot by overwriting the level on every event.
interface OrderbookLevelUpdatedEvent {
  type: "OrderbookLevelUpdated";
  market: string;
  side: string;
  price: string;
  totalQuantity: string;
  orderCount: string;
}
type
"OrderbookLevelUpdated"
required
Event discriminator.
market
string
required
Market identifier as a decimal string.
side
string
required
Book side: "Buy" (bids) or "Sell" (asks).
price
string
required
Price level in microUSDC.
totalQuantity
string
required
Total resting quantity at this price level after the mutation in integer contracts. A value of "0" means the level has been cleared.
orderCount
string
required
Number of resting orders at this price level after the mutation.

Build docs developers (and LLMs) love