Concepts & Glossary

Your business — the account behind a full API key (pk_live_ / sk_sandbox_). A partner owns one master wallet, any number of sub-accounts, webhooks, and pricing configuration. Your tier sets rate limits and scopes.

See: Authentication

An end user of your app, created with POST /users using your own externalId — your internal user ID, which doubles as the idempotency key (or POST /auto-register, which takes the same value as its uid field). Each sub-account has an isolated USD trading wallet and portfolio under your master account, identified by a usr_ id.

See: Sub-Accounts

Your partner-level USD balance. Funded by POST /topup (bank remittance, admin-confirmed); it is the source of every sub-account deposit and receives funds back on withdrawals. POST /payout moves money out to your bank.

See: Fund Flow

Your funding headroom: availableToFundUsd = master balance + credit line − pending top-ups. GET /float reports it; the float.low webhook fires when the balance crosses your threshold (PATCH /float). An admin-set creditLimitUsd can let sub-account deposits run the master balance negative while your remittance is in flight.

See: Fund Flow

The sub-account’s own USD wallet. Deposits credit it, BUY orders escrow from it (price + fees at order time), and SELL proceeds land in it once the trade settles.

An order is the instruction — BUY or SELL, market or LIMIT/STOP/STOP_LIMIT — and carries the status lifecycle (PENDING, WORKING, PROCESSING, COMPLETED/FILLED, REJECTED, CANCELLED). An execution is a fill report attached to the order (GET /orders/{id}/executions); one order can settle through one or more executions.

See: Trading

The settled units of one instrument inside a sub-account portfolio, with cost basis and current value (GET /users/{id}/portfolio). Fractional units are tracked natively.

A FIFO parcel of units from a single acquisition, with its own per-unit cost basis and acquisition date (GET /users/{id}/tax-lots). Disposals are matched to lots oldest-first to compute realized gains for CGT statements (GET /users/{id}/gains).

See: Reports

Exchange finality, N business days after a fill — EGX settles on T+2; the other supported exchanges settle on T+3. SELL proceeds remain unsettled until the settlement date and are excluded from withdrawable cash until then.

What a sub-account can trade versus withdraw right now: buyingPowerUsd includes unsettled SELL proceeds, withdrawableUsd excludes them (GET /users/{id}/buying-power). Platforms with settlement holds enabled reject over-withdrawals with 400 UNSETTLED_FUNDS.

See: Trading

An issuer event that changes holdings without a trade: split, rights issue, bonus, merger, delisting, or symbol change. Pushed via the corporateaction.declared webhook with the affected sub-accounts and their units — apply it or cached quantities go stale.

See: Webhooks

A cash distribution per share held. Credited to sub-account trading wallets and pushed via the dividend.paid webhook, grouped by symbol with a per-sub-account distributions array.

See: Webhooks

Sub-account orders can be placed by cashValue instead of quantity, producing fractional units. Holdings, tax lots, and dividend distributions all track fractional units.

A unique header value that makes money-movement and account state-changing POSTs safe to retry: duplicates are deduplicated for 24 hours and replay the original response; a concurrent duplicate returns 409 until the first request completes. Required (not optional) on deposit, withdraw, trade, topup, payout, KYC assertion, subscribe, redeem, and webhook creation — those return 400 MISSING_IDEMPOTENCY_KEY without it.

See: Authentication

One attempt to POST an event to your endpoint, signed with x-mystocks-signature. Delivery is at-least-once with up to 6 attempts on an exponential back-off (immediate to 2 h) — dedupe by event id and treat handlers as idempotent.

See: Webhooks