Skip to main content

​
Overview

Connect to receive real-time updates about your trading activity, including order status changes, position updates, and balance changes.
To avoid ambiguity, we denote the smallest possible multiple of USDC (0.000001 USDC) as one uusdc, which stands for µUSDC (micro-USDC).

​
Connection

wss://api.bison.markets/ws/evm/{userAddress}
​
userAddress
string
required
Your Ethereum wallet address (with 0x prefix)

​
Example Connection

const userAddress = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266";
const ws = new WebSocket(
  `wss://api.bison.markets/ws/evm/${userAddress}`
);

ws.onopen = () => {
  console.log("Connected to user events");
  
  // Send heartbeat every 30 seconds
  setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({ type: "ping" }));
    }
  }, 30000);
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  // Ignore ping/pong messages
  if (data.type === "ping" || data.type === "pong") {
    return;
  }
  
  console.log("Received event:", data);
  handleEvent(data);
};

ws.onerror = (error) => {
  console.error("WebSocket error:", error);
};

ws.onclose = () => {
  console.log("Connection closed");
  // Implement reconnection logic here
};

​
Event Types

The User Events WebSocket streams the following event types:

​
Order Events

Fired when a new order is placed.
{
  "type": "order_placed",
  "orderId": "abc123xyz",
  "marketId": "KXBTC-100K-DEC31",
  "action": "buy",
  "side": "yes",
  "number": 10,
  "priceUusdc": 750000
}
​
type
string
Always "order_placed"
​
orderId
string
Unique identifier for the order
​
marketId
string
Market ticker for the order
​
action
string
Either "buy" or "sell"
​
side
string
Either "yes" or "no"
​
number
number
Number of contracts
​
priceUusdc
number
Price per contract in µUSDC (microUSDC, 6 decimals)
Fired when an order is filled (fully or partially).
{
  "type": "order_filled",
  "orderId": "abc123xyz",
  "marketId": "KXBTC-100K-DEC31",
  "action": "buy",
  "side": "yes",
  "number": 10,
  "priceUusdc": 750000
}
Fields are the same as order_placed.
Fired when an order is cancelled.
{
  "type": "order_cancelled",
  "orderId": "abc123xyz",
  "marketId": "KXBTC-100K-DEC31",
  "action": "buy",
  "side": "yes",
  "number": 10,
  "priceUusdc": 750000
}
Fields are the same as order_placed.

​
Market Events

Fired when a market opens for trading.
{
  "type": "market_opened",
  "marketId": "KXBTC-100K-DEC31"
}
​
type
string
Always "market_opened"
​
marketId
string
Market ticker that opened
Fired when a market closes for trading.
{
  "type": "market_closed",
  "marketId": "KXBTC-100K-DEC31"
}
Fields are the same as market_opened.
Fired when a market is settled with a final result.
{
  "type": "market_settled",
  "marketId": "KXBTC-100K-DEC31",
  "result": "yes"
}
​
type
string
Always "market_settled"
​
marketId
string
Market ticker that settled
​
result
string
Settlement result: "yes" or "no"

​
Balance Events

Fired when USDC is deposited into your Bison account.
{
  "type": "usdc_deposited",
  "userAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "uusdcAmount": 1000000,
  "newBalanceUusdc": 5000000
}
​
type
string
Always "usdc_deposited"
​
userAddress
string
Your Ethereum address
​
uusdcAmount
number
Amount deposited in µUSDC (1 USDC = 1,000,000 µUSDC)
​
newBalanceUusdc
number
Your new total balance in µUSDC
Fired when USDC is withdrawn from your Bison account.
{
  "type": "usdc_withdrawn",
  "userAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "uusdcAmount": 500000,
  "newBalanceUusdc": 4500000
}
Fields are the same as usdc_deposited.

​
Position Events

Fired when you withdraw position tokens from the exchange to your wallet as ERC-20 tokens.
{
  "type": "position_minted",
  "userAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "marketId": "KXBTC-100K-DEC31",
  "side": "yes",
  "number": 10
}
​
type
string
Always "position_minted"
​
userAddress
string
Your Ethereum address
​
marketId
string
Market ticker for the position
​
side
string
Position side: "yes" or "no"
​
number
number
Number of position tokens minted
Fired when you deposit position tokens from your wallet back to the exchange.
{
  "type": "position_burned",
  "userAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "marketId": "KXBTC-100K-DEC31",
  "side": "yes",
  "number": 5
}
Fields are the same as position_minted.