The commissions and prices used here are fictional and do not imply anything about the actual
setup on the live exchange.
What is Self Trade Prevention?
Self Trade Prevention (or STP) prevents orders of users, or the user's tradeGroupId to match
against their own.
What defines a self-trade?
A self-trade can occur in either scenario:
The order traded against the same account.
The order traded against an account with the same tradeGroupId.
What happens when STP is triggered?
There are five possible modes for what the system does when an order would create a self-trade.
NONE - This mode exempts the order from self-trade prevention. Accounts or Trade group IDs will
not be compared, no orders will be expired, and the trade will occur.
EXPIRE_TAKER - This mode prevents a trade by immediately expiring the taker order's remaining
quantity.
EXPIRE_MAKER - This mode prevents a trade by immediately expiring the potential maker order's
remaining quantity.
EXPIRE_BOTH - This mode prevents a trade by immediately expiring both the taker and the potential
maker orders' remaining quantities.
DECREMENT - This mode increases the prevented quantity of both orders by the amount of the
prevented match. The smaller of the two orders will expire, or both if they have the same quantity.
TRANSFER - If orders are from the same account, then the behavior is the same as DECREMENT. If
orders are from different accounts with the same tradeGroupId, then in addition to the behavior of
DECREMENT, the last prevented quantity and its notional are transferred between the two
accounts.
STP behavior is typically determined by the STP mode of the taker order only. The exception is
that for STP TRANSFER to occur, both the maker and taker orders must specify STP mode TRANSFER.
If the taker order specifies STP mode TRANSFER, but the maker order specifies a different STP
mode, then the STP behavior is DECREMENT.
Different accounts with the same tradeGroupId are considered part of the same "trade group".
Orders submitted by members of a trade group are eligible for STP according to the taker-order's STP
mode.
A user can confirm if their accounts are under the same tradeGroupId from the API either from
GET /api/v3/account (REST API) or account.status (WebSocket API) for each account.
The field is also present in the response for GET /api/v3/preventedMatches (REST API) or
myPreventedMatches (WebSocket API).
If the value is -1, then the tradeGroupId has not been set for that account, so the STP may only
take place between orders of the same account.
What is a Prevented Match?
When a self-trade is prevented, a prevented match is created. The orders in the prevented match have
their prevented quantities increased and one or more orders expire.
This is not to be confused with a trade, as no orders will match.
This is a record of what orders could have self-traded.
This can be queried through the endpoint GET /api/v3/preventedMatches on the REST API or
myPreventedMatches on the WebSocket API.
This is a sample of the output request for reference:
Code
[ { symbol: "BTCDUSDT", //Symbol of the orders preventedMatchId: 8, //Identifies the prevented match of the expired order(s) for the symbol. takerOrderId: 12, //Order Id of the Taker Order makerOrderId: 10, //Order Id of the Maker Order tradeGroupId: 1, //Identifies the Trade Group Id. (If the account is not part of a trade group, this will be -1.) selfTradePreventionMode: "EXPIRE_BOTH", //STP mode that expired the order(s). price: "50.00000000", //Price at which the match occurred. takerPreventedQuantity: "1.00000000", //Taker's remaining quantity before the STP. Only appears if the STP mode is EXPIRE_TAKER, EXPIRE_BOTH or DECREMENT. makerPreventedQuantity: "10.00000000", //Maker's remaining quantity before the STP. Only appears if the STP mode is EXPIRE_MAKER, EXPIRE_BOTH, or DECREMENT. transactTime: 1663190634060, //Time the order(s) expired due to STP. },];
What is "prevented quantity?"
STP events expire quantity from open orders. The STP modes EXPIRE_TAKER, EXPIRE_MAKER, and
EXPIRE_BOTH expire all remaining quantity on the affected orders, resulting in the entire open
order being expired.
Prevented quantity is the amount of quantity that is expired due to STP events for a particular
order. User stream execution reports for orders involved in STP may have these fields:
B is present for execution type TRADE_PREVENTION, and is the quantity expired due to that
individual STP event.
A is the cumulative quantity expired due to STP over the lifetime of the order. For
EXPIRE_TAKER, EXPIRE_MAKER, and EXPIRE_BOTH modes this will always be the same value as B.
API responses for orders which expired due to STP will also have a preventedQuantity field,
indicating the cumulative quantity expired due to STP over the lifetime of the order.
While an order is open, the following equation holds true:
Code
original order quantity - executed quantity - prevented quantity = quantity available for further execution
When an order's available quantity goes to zero, the order will be removed from the order book and
the status will be one of EXPIRED_IN_MATCH, FILLED, or EXPIRED.
How do I know which symbol uses STP?
Symbols may be configured to allow different sets of STP modes and take different default STP modes.
defaultSelfTradePreventionMode - Orders will use this STP mode if the user does not provide one on
order placement.
allowedSelfTradePreventionModes - Defines the allowed set of STP modes for order placement on that
symbol.
For example, if a symbol has the following configuration:
Scenario E - A user has an order on the book with EXPIRE_MAKER, and then sends a new order with
EXPIRE_TAKER which would match with the existing order.
Result: The existing order expires with the status EXPIRED_IN_MATCH, due to STP. The new order
also expires but with status EXPIRED, due to low liquidity on the order book.
