A trade in this system is the record of an execution — a deal that already happened on a venue (NYSE, NASDAQ, etc.). It is not an order, which is the request. Orders may be partially filled, cancelled, or rejected; trades are the fills that survived.
The four sides
When mock-fintrade composes a trade, the side field tells StarClear what to do with the customer's position. There are four:
| side | requires | effect on position |
|---|---|---|
BUY | cash (or margin BP) | opens or grows a long position |
SELL | holding the long | closes or reduces a long position |
SELL_SHORT | an APPROVED locate | opens or grows a short position |
BUY_TO_COVER | holding the short | closes or reduces a short position |
Gross vs net
The price you send is per share. The total dollar amount has two flavors:
- gross =
qty × price— what the trade is worth before fees. mock-fintrade computes this client-side and includes it in the v2 body. - net =
gross + commission— what cash actually changes hands on the customer side. SEC and TAF fees come out of this in StarClear; the server computes them and any vendor value is ignored.
Trade date vs settlement date
Two dates matter for every trade:
- trade_date (T): when the deal happened. This is what the OMS sends.
- settlement_date (T+1): when cash + shares actually change hands. For US equities since May 2024 this is one business day later, skipping weekends and market holidays. mock-fintrade lets StarClear auto-compute this — don't hand-roll it.
What StarClear does with a trade POST
- Resolves the
symbolagainst the security master (matching on ticker OR CUSIP OR ISIN). - Computes SEC + TAF fees from the regulatory schedules (server-side authoritative).
- Computes
settlement_date= T+1 skipping weekends + holidays (unless you sent one explicitly for a DTC-fail or balance-open case). - Writes a balanced journal entry to
journal_master(the back-office double-entry ledger). - Returns 201 with the trade id and journal number — or RFC-7807 problem details on rejection.
The OMS' job before the POST
A real OMS doesn't blindly POST every trade — it gates first. mock-fintrade enforces 5 of 10 gates (G1, G2, G4, G5, G10) before touching v2; the other 5 are stubs awaiting server-fed registries. See how the gates work · stub.