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	202 — status PENDING, USD reserved. Body: { assetType: "FUND"\|"BOND", assetId, units }. Idempotency-Key required.
4	Track allocation	MyStocks allocates units at the effective NAV/price → COMPLETED, units appear in GET /users/{id}/portfolio.
5	POST /users/{id}/redeem	Instant-redemption funds: units → cash at current NAV in the same call. Non-instant funds go through a MyStocks 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: pk_live_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: pk_live_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: pk_live_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: red_user42_mmf_2026-07" \
  -d '{"assetType":"FUND","assetId":"fund_mmf_africa","units":200}'

Common mistakes

—Treating subscribe like trade. There is no quoteId here — subscriptions reserve USD at 202 and settle when MyStocks allocates, which is not instant.
—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, and the subscribe flow — subscribe with virtual funds and watch the reservation in the wallet.
2.Use GET /users/{id}/transactions to see the PENDING reservation row and the COMPLETED allocation row.

Try it in the API Tester