User Events - Bison API

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), and denote the smallest possible multiple of a contract (0.01 contract) as one ccontract (centicontract).User-facing USDC balances are specified as fixed-point strings (e.g. "1.2625" for USDC). Contract quantities in the API and SDK are specified as integer ccontracts strings (e.g. "1050" for 10.50 contracts at precision 2).

Connection

wss://api.bison.markets/ws/evm/{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

order_placed

Fired when a new order is placed.

{
  "type": "order_placed",
  "orderId": "abc123xyz",
  "marketId": "KXBTC-100K-DEC31",
  "action": "buy",
  "side": "yes",
  "ccontracts": "1000",
  "priceUusdc": "750000"
}

string

Always "order_placed"

string

Unique identifier for the order

string

Market ticker for the order

string

Either "buy" or "sell"

string

Either "yes" or "no"

string

Number of cContracts (integer string)

string

Price per contract in µUSDC (microUSDC, 6 decimals)

order_filled

Fired when an order is filled (fully or partially).

{
  "type": "order_filled",
  "orderId": "abc123xyz",
  "marketId": "KXBTC-100K-DEC31",
  "action": "buy",
  "side": "yes",
  "ccontracts": "1000",
  "priceUusdc": "750000"
}

Fields are the same as order_placed.

order_cancelled

Fired when an order is cancelled.

{
  "type": "order_cancelled",
  "orderId": "abc123xyz",
  "marketId": "KXBTC-100K-DEC31",
  "action": "buy",
  "side": "yes",
  "ccontracts": "1000",
  "priceUusdc": "750000"
}

Fields are the same as order_placed.

Market Events

market_opened

Fired when a market opens for trading.

{
  "type": "market_opened",
  "marketId": "KXBTC-100K-DEC31"
}

string

Always "market_opened"

string

Market ticker that opened

market_closed

Fired when a market closes for trading.

{
  "type": "market_closed",
  "marketId": "KXBTC-100K-DEC31"
}

Fields are the same as market_opened.

market_settled

Fired when a market is settled with a final result.

{
  "type": "market_settled",
  "marketId": "KXBTC-100K-DEC31",
  "result": "yes"
}

string

Always "market_settled"

string

Market ticker that settled

string

Settlement result: "yes" or "no"

Balance Events

usdc_deposited

Fired when USDC is deposited into your Bison account.

{
  "type": "usdc_deposited",
  "userAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "uusdcAmount": "1000000",
  "newBalanceUusdc": "5000000"
}

string

Always "usdc_deposited"

string

Your Ethereum address

string

Amount deposited in µUSDC (1 USDC = 1,000,000 µUSDC)

string

Your new total balance in µUSDC

usdc_withdrawn

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

position_minted

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",
  "ccontracts": "1000"
}

string

Always "position_minted"

string

Your Ethereum address

string

Market ticker for the position

string

Position side: "yes" or "no"

string

Number of position tokens minted (integer string)

position_burned

Fired when you deposit position tokens from your wallet back to the exchange.

{
  "type": "position_burned",
  "userAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "marketId": "KXBTC-100K-DEC31",
  "side": "yes",
  "ccontracts": "500"
}

Fields are the same as position_minted.

​Overview

​Connection

​Example Connection

​Event Types

​Order Events

​Market Events

​Balance Events

​Position Events

Overview

Connection

Example Connection

Event Types

Order Events

Market Events

Balance Events

Position Events