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.

Placed

POST /users/{id}/trade

quoteId consumed→

PENDING

escrow held

fill target: 5 min→

COMPLETED

units in portfolio

From	Trigger	To	Webhook
—	POST /users/{id}/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/{id}/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 skip the dealing desk 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 live price crosses the trigger during market hours.

Placed

orderType + limitPrice/stopPrice

escrow / reservation→

WORKING

resting — waiting for trigger

price crosses trigger→

PENDING

in the dealing desk

desk approves→

COMPLETED

limit price honored

From	Trigger	To	Webhook
—	POST /users/{id}/trade with orderType LIMIT/STOP/STOP_LIMIT (no quoteId needed)	WORKING	—
WORKING	PATCH /users/{id}/orders/{orderId} — modify price/quantity; escrow/reservation adjusted by the delta	WORKING	order.replaced
WORKING	Live price crosses the trigger while the exchange is open (checked every ~2 min)	PENDING	order.triggered, then order.pending
WORKING	DELETE /users/{id}/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.

Master wallet

deposit / withdraw→

Sub-account wallet

From	Trigger	To	Webhook
—	POST /users/{id}/deposit — master debited, sub-account credited atomically	done	deposit.confirmed
—	POST /users/{id}/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.

Registered

POST /topup

remittanceProofUrl→

PENDING

remittance in flight

admin confirms receipt→

APPROVED

master wallet 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.

Requested

POST /payout

lock taken→

PENDING

amount locked

admin processes→

COMPLETED

wire sent

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.

NONE

default at creation

POST /users/{id}/kyc→

PENDING

checks running

POST /users/{id}/kyc→

VERIFIED

trading unlocked

From	Trigger	To	Webhook
NONE / PENDING / VERIFIED	POST /users/{id}/kyc with status NONE \| PENDING \| VERIFIED and level NONE \| BASIC \| FULL — any re-assertion is allowed	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.

Subscribed

POST /users/{id}/subscribe

funds reserved→

PENDING

USD reserved (202)

MyStocks allocates→

COMPLETED

units allocated

From	Trigger	To	Webhook
—	POST /users/{id}/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/{id}/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.