Private Stream Events (v1.1.1)

This page documents the private WebSocket stream events for Order, Trade, and Withdraw for version 1.1.1. These events are pushed in real-time from the server to authenticated clients connected to the private ranger endpoint:

wss://dev.yimmit.com/api/v3/ranger/private

Authentication headers are required. See WebSocket Streams for connection and authentication details.

---

1. Order Event (order)

When Is It Triggered?

The order event is published to the authenticated user's private stream in the following cases:

Trigger	Description
Order Created	A new limit / stop-loss / take-profit order is submitted
Order Updated	Order state changes (e.g. pending → wait)
Order Cancelled	Order moves to cancel state
Order Completed	Order moves to done state (fully filled)

Note: market type orders only trigger the order event when their state becomes done.
Stop-loss and take-profit orders (stop_loss_limit, take_profit_limit, stop_limit) also trigger events on state changes.

Order States

State	Value	Description
pending	0	Order submitted but not yet active
wait	100	Order is active and waiting to be filled
done	200	Order has been fully executed
cancel	-100	Order has been cancelled
reject	-200	Order was rejected
under_review	-300	Order is under manual review
in_review	300	Order is currently being reviewed

WSS Response Payload

{
  "order": {
    "id": 23515,
    "market": "ethusdc",
    "kind": "bid",
    "side": "buy",
    "bid": "usdc",
    "ask": "eth",
    "ord_type": "limit",
    "price": "2021.97",
    "avg_price": "0.0",
    "state": "wait",
    "origin_volume": "0.0029",
    "remaining_volume": "0.0029",
    "executed_volume": "0.0",
    "at": 1773294648,
    "created_at": 1773294648,
    "updated_at": 1773294648,
    "trades_count": 0,
    "maker_fee": "0.0015",
    "stop_price": "0.0",
    "stop_loss_status": null,
    "price_precision": 2,
    "amount_precision": 4,
    "total_fee": "0.0"
  }
}

Payload Fields

Field	Type	Description
id	integer	Unique order ID
market	string	Market pair (e.g. btcusdt)
kind	string	bid (buy) or ask (sell)
side	string	buy or sell
bid	string	Quote currency (e.g. usdt)
ask	string	Base currency (e.g. btc)
ord_type	string	Order type: limit, market, stop_loss_limit, take_profit_limit, stop_limit
price	string	Limit price (null for market orders)
avg_price	string	Average execution price
state	string	Current order state (see table above)
origin_volume	string	Original order quantity
remaining_volume	string	Quantity still to be filled
executed_volume	string	Quantity already filled
at	integer	Unix timestamp (seconds)
created_at	integer	Unix timestamp of order creation (seconds)
updated_at	integer	Unix timestamp of last update (seconds)
trades_count	integer	Number of trades that filled this order
maker_fee	string	Maker fee rate
stop_price	string	Stop trigger price (for stop orders)
stop_loss_status	string	null
price_precision	integer	Decimal precision for price display
amount_precision	integer	Decimal precision for amount display
total_fee	string	Cumulative fee charged so far

Frontend Behaviour

When the order event is received:

• For market orders in done state → wallet balance is refreshed
• For all other orders → the open orders list and order history are updated in real-time

---

2. Trade Event (trade)

When Is It Triggered?

The trade event is published to both the maker and the taker whenever a trade is executed (i.e., two orders are matched). Each party receives a personalised payload that includes their own side and order_id.

A separate public trade event is also broadcast to all subscribers of {marketId}.trades.

Channel	Recipient	Event Key
Private (/private)	Maker of the trade	trade
Private (/private)	Taker of the trade	trade
Public (/public)	All market subscribers	{marketId}.trades

WSS Response — Private (trade)

Sent to the maker and taker separately with their own perspective:

{
  "trade": {
    "id": 789,
    "price": "50000.0",
    "amount": "0.01",
    "total": "500.0",
    "market": "btcusdt",
    "side": "buy",
    "taker_type": "buy",
    "created_at": 1741400000,
    "order_id": 23515
  }
}

Private Trade Payload Fields

Field	Type	Description
id	integer	Unique trade ID
price	string	Execution price
amount	string	Quantity traded
total	string	Total value (price × amount)
market	string	Market pair (e.g. btcusdt)
side	string	This user's side: buy or sell
taker_type	string	The taker's side: buy or sell
created_at	integer	Unix timestamp of trade execution (seconds)
order_id	integer	ID of this user's order that was matched

WSS Response — Public ({marketId}.trades)

Broadcast to all users subscribed to btcusdt.trades (or any market):

{
  "btcusdt.trades": {
    "trades": [
      {
        "tid": 789,
        "taker_type": "buy",
        "date": 1741400000,
        "price": "50000.0",
        "amount": "0.01"
      }
    ]
  }
}

Public Trade Payload Fields

Field	Type	Description
tid	integer	Unique trade ID
taker_type	string	The taker's side: buy or sell
date	integer	Unix timestamp of trade (seconds)
price	string	Execution price
amount	string	Quantity traded

---

3. Withdraw Event (withdraw)

When Is It Triggered?

The withdraw event is published to the authenticated user's private stream whenever the withdrawal's state changes through the AASM state machine:

AASM Event	From State	To State	WSS Published?
accept	prepared	accepted	✅ Yes
cancel	prepared, accepted, skipped	canceled	✅ Yes
reject	to_reject, accepted, confirming, under_review	rejected	✅ Yes
process	accepted, skipped, errored, failed	processing	✅ Yes
dispatch	processing, under_review	confirming	✅ Yes
done	deposited, accepted	succeed (fiat only)	✅ Yes
success	confirming, deposited, errored, under_review	succeed	✅ Yes

Withdraw States

State	Description
prepared	Withdrawal requested, awaiting acceptance
accepted	Accepted and funds locked
processing	Being sent on-chain
confirming	Transaction submitted, waiting for block confirmations
under_review	Flagged for manual review
succeed	Withdrawal completed successfully
canceled	Cancelled by the user
rejected	Rejected by admin
failed	Processing failed
errored	A processing error occurred
skipped	Temporarily skipped (will be retried)

WSS Response Payload

{
  "withdraw": {
    "id": 55,
    "currency": "usdt",
    "amount": "3.0",
    "fee": "1.2",
    "blockchain_txid": "de9723b3-97e3-43fa-adab-5aa0ec5208d6",
    "type": "Withdraws::Coin",
    "state": "processing",
    "protocol": "sepolia",
    "blockchain_key": "eth-testnet",
    "transaction_type": "external",
    "tid": "TID731049B2E6",
    "rid": "0x76dcd3dafb5f7229542f0580d9c5a1612486a42b",
    "created_at": "2026-03-12 05:51:23 UTC",
    "updated_at": "2026-03-12 05:51:25 UTC"
  }
}

Payload Fields

Field	Type	Description
id	integer	Unique withdrawal ID
currency	string	Currency code (e.g. usdt, btc)
amount	string	Withdrawal amount (after fee deduction)
fee	string	Network/withdrawal fee
blockchain_txid	string	null
type	string	Withdraws::Coin (crypto) or Withdraws::Fiat (fiat)
state	string	Current state (see table above)
protocol	string	Blockchain protocol (e.g. ERC20, TRC20, sepolia)
blockchain_key	string	Blockchain network key (e.g. eth-mainnet, eth-testnet)
transaction_type	string	external or internal
tid	string	Internal transaction ID
rid	string	Recipient wallet address
created_at	string	ISO 8601 timestamp of creation
updated_at	string	ISO 8601 timestamp of last update

Frontend Notifications

The frontend shows toast notifications based on the withdrawal state:

State	Notification Type	Message
submitted	🔵 Info	Withdrawal submitted
succeed	✅ Success	Withdrawal completed
rejected	❌ Error	Withdrawal failed
failed	❌ Error	Withdrawal failed

All state changes also update the withdrawal history list in real-time via the Redux store.

---

Summary Table

Event Key	Channel	Endpoint	Triggered By	Frontend Action
order	Private	/private	Order created / updated / cancelled / filled	Updates open orders & order history in real-time
trade	Private	/private	Trade matched (sent to maker & taker)	Updates personal trade list
{marketId}.trades	Public	/public	Trade matched (broadcast to all)	Updates public market trade feed
withdraw	Private	/private	Withdrawal state transition	Updates withdrawal history + shows toast notification
balance	Private	/private	Deposit accepted, Withdrawal success, or Trade fill	Updates wallet balances

---

4. Balance Event (balance)

When Is It Triggered?

The balance event is published to the user's private stream whenever their account balance changes due to the following actions:

Trigger	Description
Deposit Accepted	When a deposit moves to the accepted state
Withdrawal Success	When a withdrawal moves to the succeed state
Trade Execution	When an order is filled (partial or full) during trading
Internal Transfer	When funds are moved between accounts or via internal transfers

WSS Response Payload

{
  "balance": {
    "currency": "btc",
    "balance": "1.50000000",
    "locked": "0.50000000",
    "prev_pnl": {
      "aval_balance": "1.45000000",
      "currency_price": "50000.0"
    },
    "net_inflow": 0.05,
    "precision": 8,
    "currency_usdt": "51000.0",
    "currency_icon": "https://example.com/icons/btc.png",
    "currency_type": "coin",
    "currency_name": "Bitcoin"
  }
}

Payload Fields

Field	Type	Description
currency	string	Currency ID (e.g. btc, usdt)
balance	string	Available (free) balance
locked	string	Locked balance (e.g. in open orders)
prev_pnl	object	Previous 24h PNL data
prev_pnl.aval_balance	string	null
prev_pnl.currency_price	string	null
net_inflow	float	Net inflow for the current period
precision	integer	Decimal precision for this currency
currency_usdt	string	Current price of the currency in USDT
currency_icon	string	URL to the currency icon
currency_type	string	coin or fiat
currency_name	string	Full name of the currency