Bonds, Funds & Fixed Income

≈ 1 day

Money-market funds, T-bills, and bonds run on a subscription model instead of exchange orders: USD is reserved at subscription, units are allocated by MyStocks, and distributions arrive as dividend.paid webhooks. Instant-redemption funds convert back to cash in one call.

The flow

Step	Endpoint / Event	What it does
1	GET /bonds · GET /funds	Browse the catalogue: yield, duration, credit rating (bonds); NAV, annualized return (funds).
2	GET /funds/{id} · GET /bonds/{id}	Full instrument detail — check status is ACTIVE before offering it.
3	POST /users/{id}/subscribe	Production: 202 PENDING with USD reserved. Sandbox: 200 FILLED. Body: { assetType: "FUND"\|"BOND", assetId, units }.
4	Track allocation	MyStocks subscription allocation becomes COMPLETED and units appear in the portfolio; this is distinct from the FILLED terminal state used by stock orders.
5	POST /users/{id}/redeem	Send { holdingId, unitsToRedeem }. Instant-redemption funds credit cash at current NAV; non-instant funds require a redemption request.
6	Webhook: dividend.paid	Interest and fund distributions arrive grouped by symbol with per-sub-account breakdowns.

Implementation

bash

# 1. Browse money-market funds
curl "https://mystocks.africa/api/v1/partner/funds" -H "x-api-key: $MYSTOCKS_API_KEY"

# 3. Subscribe 500 units for a sub-account (202 — PENDING, USD reserved)
curl -X POST "https://mystocks.africa/api/v1/partner/users/usr_abc123/subscribe" \
  -H "x-api-key: $MYSTOCKS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: sub_user42_mmf_2026-07" \
  -d '{"assetType":"FUND","assetId":"fund_mmf_africa","units":500}'

# 5. Redeem 200 units (instant-redemption funds credit the wallet immediately)
curl -X POST "https://mystocks.africa/api/v1/partner/users/usr_abc123/redeem" \
  -H "x-api-key: $MYSTOCKS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: red_user42_mmf_2026-07" \
  -d '{"holdingId":"fund_mmf_africa","unitsToRedeem":200}'

Common mistakes

—Treating subscribe like trade. There is no quoteId here — production subscriptions reserve USD at 202 and settle when MyStocks allocates; sandbox subscriptions fill immediately.
—Redeeming units that are locked in a pending redemption. The API tells you the available vs locked split — surface it in your UI.
—Crediting distributions yourself. dividend.paid means the wallet was already credited — your job is display and notification, not money movement.
—Skipping the ACTIVE check. Subscriptions to a non-ACTIVE fund or bond fail with 400.
—No Idempotency-Key on subscribe/redeem — both move money and both dedupe by key for 24 h.

Prove it in sandbox first

1.The sandbox mirrors /bonds, /funds, subscribe, and redeem with virtual funds, but subscriptions fill immediately instead of entering the production PENDING allocation lifecycle.
2.Expect 200 FILLED in sandbox. In production, expect 202 PENDING and wait for allocation before redeeming the resulting holding.

Try it in the API Tester