Order & Money Lifecycles
Every state, transition, and webhook for the Partner API's order and money flows — market orders, resting LIMIT/STOP orders, deposits/withdrawals, master top-up and payout, KYC, and fund/bond subscription — extracted from the platform code, not idealized.
Every state, every transition, and the webhook each one fires — extracted from the platform code, not idealized. Terminal states are colored: green settles, red releases funds back.
Market order
The default order type. Funds (cost + fees) are escrowed at placement; live market orders target a fill within 5 minutes during exchange hours.
| From | Trigger | To | Webhook |
|---|---|---|---|
| — | POST /users/{userId}/trade (quoteId + Idempotency-Key; cost + fees escrowed) | PENDING | order.pending |
| PENDING | Live fill completes (large orders may need a second approval first) | COMPLETED | order.filled (+ trade.settled alias) |
| PENDING | Live fill rejects — escrow refunded | REJECTED | order.rejected (+ trade.rejected alias) |
| PENDING | DELETE /users/{userId}/orders/{orderId} — escrow refunded | CANCELLED | order.cancelled |
| PENDING | Expiry cron: DAY order older than 24 h, or GTD past expiresAt — escrow refunded | CANCELLED (EXPIRED) | order.cancelled |
NoteSandbox orders simulate the automatic MyStocks internal-book path and settle instantly. PROCESSING appears in the status enum for historical orders but is no longer written.
Resting order (LIMIT / STOP / STOP_LIMIT)
Placeable even while the market is closed. BUY escrows at the trigger price; SELL reserves the units. A price cron promotes it when the latest 15-minute-delayed exchange observation crosses the trigger during market hours.
| From | Trigger | To | Webhook |
|---|---|---|---|
| — | POST /users/{userId}/trade with orderType LIMIT/STOP/STOP_LIMIT (no quoteId needed) | WORKING | — |
| WORKING | PATCH /users/{userId}/orders/{orderId} — modify price/quantity; escrow/reservation adjusted by the delta | WORKING | order.replaced |
| WORKING | Latest 15-minute-delayed exchange observation crosses the trigger while the exchange is open | PENDING | order.triggered, then order.pending |
| WORKING | DELETE /users/{userId}/orders/{orderId} — escrow/reservation released | CANCELLED | order.cancelled |
| WORKING | GTD expiry (expiresAt) — escrow/reservation released | CANCELLED (EXPIRED) | order.cancelled |
| PENDING | Follows the market-order lifecycle from here | COMPLETED / REJECTED / CANCELLED | see market order |
Sub-account deposit & withdrawal
Single-step ledger moves between your master wallet and a sub-account wallet — no pending state, the webhook fires immediately.
| From | Trigger | To | Webhook |
|---|---|---|---|
| — | POST /users/{userId}/deposit — master debited, sub-account credited atomically | done | deposit.confirmed |
| — | POST /users/{userId}/withdraw — sub-account debited, master credited | done | withdraw.confirmed |
| — | Withdraw exceeding withdrawableUsd (settlement holds enabled) | rejected with 400 UNSETTLED_FUNDS | — |
Master top-up
You remit to the MyStocks bank account and register the transfer; an admin confirms receipt before your master wallet is credited.
| From | Trigger | To | Webhook |
|---|---|---|---|
| — | POST /topup with amount + remittanceProofUrl | PENDING | — |
| PENDING | MyStocks admin confirms the bank remittance | APPROVED | topup.confirmed |
| PENDING | Admin rejects (no matching remittance) | REJECTED | — |
NoteWhile a remittance is in flight, an admin-set credit line (creditLimitUsd) can keep sub-account deposits flowing — see GET /float.
Master payout
Moves money from your master wallet back to your bank. The amount is locked at request time so it cannot be double-spent while the wire is prepared.
| From | Trigger | To | Webhook |
|---|---|---|---|
| — | POST /payout — amount locked against the master balance | PENDING | — |
| PENDING | MyStocks admin sends the wire and confirms | COMPLETED | — |
| PENDING | Admin rejects — lock released back to the master balance | REJECTED | — |
KYC status
You run KYC on your side and assert the outcome. Trading and money movement stay blocked until the sub-account is VERIFIED.
| From | Trigger | To | Webhook |
|---|---|---|---|
| NONE / PENDING / VERIFIED / REJECTED | POST /users/{userId}/kyc with status NONE | PENDING | VERIFIED | REJECTED and level NONE | BASIC | FULL — REJECTED requires reasonCode and reason | as asserted | kyc.updated |
| not VERIFIED | Any trade or money-movement call | rejected with 403 KYC_REQUIRED | — |
Fund & bond subscription / redemption
Subscriptions reserve USD immediately and settle when MyStocks allocates units. Instant-redemption funds convert units back to cash in one call.
| From | Trigger | To | Webhook |
|---|---|---|---|
| — | POST /users/{userId}/subscribe (FUND, BOND, OPPORTUNITY, PRE_IPO) — USD reserved | PENDING | — |
| PENDING | MyStocks allocates units at the effective NAV/price | COMPLETED | — |
| PENDING | Allocation rejected — reserved USD released | REJECTED | — |
| COMPLETED | POST /users/{userId}/redeem on an instant-redemption fund — units converted to cash at current NAV in the same call | redeemed | — |
| COMPLETED | Redemption on a non-instant fund | requires a MyStocks redemption request | — |
NoteInterest and dividend distributions on held funds/bonds are pushed via dividend.paid.
Was this page useful?
Your signal helps us tighten partner onboarding docs.
Last updated on
Trading Fees and Regulatory Charges
Explain base fees, partner markup, execution totals, and reporting fields consistently in a customer trading experience.
Trading
Place BUY and SELL orders for your master account or any sub-account. MARKET orders use quoteId; LIMIT/STOP orders rest without quotes. Covers order types, time-in-force, history, cancellation, ledger, and portfolio.