# Bonds & Funds

> Beyond equities — fixed-income instruments (government bonds, T-bills, Eurobonds, commercial papers), money-market and yield funds with fund-specific redemption terms, and curated private-credit and pre-IPO opportunities. Subscribe and redeem via sub-account endpoints.

Beyond equities, the Partner API provides access to fixed-income instruments, open-ended funds, and
curated private-market opportunities. All subscriptions and redemptions are handled via sub-account
endpoints.

1\. Subscribe: POST /users/{userId}/subscribe

2\. PENDING: USD reserved

3\. COMPLETED: units allocated

The full transition table is in [Order & Money Lifecycles](/partners/docs/lifecycles).

## Bonds

`GET` `/bonds` · `GET` `/bonds/{id}`

List all available fixed-income instruments — government bonds, T-bills, Eurobonds, infrastructure
bonds, and commercial papers. Filter by `?instrumentType=TREASURY_BILL` (or `BOND | EUROBOND |
COMMERCIAL_PAPER | INFRASTRUCTURE_BOND`), `?currency=`, or `?exchange=`.

```bash
curl "https://mystocks.africa/api/v1/partner/bonds?instrumentType=TREASURY_BILL" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "bonds": [{ "id": "ke-treasury-91", "symbol": "KE91T", "name": "Kenya 91-Day T-Bill", "instrumentType": "TREASURY_BILL", "couponRate": 15.8, "maturityDate": "2026-09-01", "pricePerUnit": 100, "currency": "KES", "minInvestment": 50000, "status": "ACTIVE", "currentYield": 15.8 }], "count": 1 }
```

## Funds

`GET` `/funds` · `GET` `/funds/{id}`

The list returns active published managed funds, using the same catalogue in Sandbox and Live.
Sandbox subscriptions and balances remain virtual. Filter with `category` and `currency`, for example
`GET /funds?category=SPECIAL_FUND&currency=USD`. ETFs use the separate `/etfs` endpoint.

`pricePerUnit` is in the fund currency; `yieldApy` is a decimal fraction (`0.125` means 12.5%),
not a guaranteed return or YTD performance. `region` is a descriptive label, not an ISO country code.
Unavailable fields are null. Do not assume `country`, `nav`, `navUsd` or performance history is present.
Get the fund detail to review redemption terms: only `redemptionType: "instant"` credits the wallet
in the redemption call. Other terms must not be presented as instant liquidity.

```json
{ "funds": [{ "id": "example-managed-fund", "name": "Example Managed Fund", "operator": "Example Manager", "category": "SPECIAL_FUND", "pricePerUnit": 1.0, "yieldApy": 0.125, "currency": "USD", "minInvestment": 50, "region": "Pan-African/Global", "status": "ACTIVE" }], "count": 1 }
```

## Opportunities

`GET` `/opportunities` · `GET` `/opportunities/{id}`

Curated private-credit deals and pre-IPO allocations, merged from both collections and sorted newest
first. Each deal exposes target return, minimum commitment, risk level, and funding progress. The
detail route resolves by document ID or URL slug. Subscribe via `POST /users/{userId}/subscribe` with
`assetType: "OPPORTUNITY"` or `"PRE_IPO"`.

type (string, optional): OPPORTUNITY | PRE\_IPO. Omit for all types.

```bash
curl "https://mystocks.africa/api/v1/partner/opportunities?type=PRE_IPO" \
  -H "Authorization: Bearer pk_live_<key>"
```

```json
{ "opportunities": [{ "id": "TREEPZ-PRE-IPO", "assetType": "PRE_IPO", "name": "Treepz — Pre-IPO Round", "slug": "treepz-pre-ipo", "description": "Ghana-based intercity bus platform targeting a secondary listing on the NSE in Q2 2027.", "minInvestment": 500, "targetAmount": 3000000, "currentRaised": 900000, "expectedReturn": 0.45, "riskLevel": "HIGH", "currency": "USD", "status": "OPEN", "expectedExitDate": "2027-06-30" }], "count": 1 }
```

## Subscribe

`POST` `/users/{userId}/subscribe`

Subscribe a sub-account to a bond, fund, private deal, or pre-IPO. The sub-account must be
KYC-verified. Funds are escrowed immediately; the position appears in the portfolio once confirmed.
Requires an `Idempotency-Key`.

assetType (string, required): BOND | FUND | OPPORTUNITY | PRE\_IPO

assetId (string, required): Firestore doc ID from the relevant list endpoint.

units (number, optional): Whole units. Required for BOND and FUND.

amount (number, optional): USD commitment. Required for OPPORTUNITY and PRE\_IPO.

```bash
curl -X POST "https://mystocks.africa/api/v1/partner/users/usr_abc123/subscribe" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Idempotency-Key: sub_usr_abc123_001" \
  -H "Content-Type: application/json" \
  -d '{"assetType":"FUND","assetId":"fund_mmf_africa","units":500}'
```

## Redeem

`POST` `/users/{userId}/redeem`

Redeem fund units back to the sub-account wallet. For funds with `redemptionType: "instant"`, proceeds
credit immediately. Units in a lock-up period cannot be redeemed — check `unlockedUnits` in the
portfolio response first.

holdingId (string, required): Sub-account holding doc ID (same as the fund doc ID).

unitsToRedeem (number, required): Units to redeem. Must not exceed unlockedUnits.

## Catalogue field conventions

Bonds use `instrumentType`, `currency` and `exchange` filters; `country` and `type` are not bond filters. Coupon, current-yield and yield-to-maturity rates are percentage points (`15.8` means 15.8%). Missing values are `null`.

Funds use `category` and `currency`, not `type`. The list and detail share canonical `operator`, `pricePerUnit`, `yieldApy`, `minInvestment`, `region`, `legalStructure` and `logo` fields. Legacy `manager` and `nav` records are normalized without inventing returns or currency conversions. The response `count` is a sibling of `funds`.

Opportunities accept `type=ALL`, `PRE_IPO` or `OPPORTUNITY`; omitting the filter means ALL. Unknown types return 400. Responses use `assetType`, `expectedReturn`, `maturityDate` and `expectedExitDate`, with unknown values null. An expected return is an instrument-specific estimate, not a guaranteed return; consult the offering terms for its convention.

## Sandbox subscription and redemption acceptance

Use the reference app subscription form for whole-unit bond and fund requests or USD opportunity/pre-IPO commitments. Select an ID from the corresponding environment's catalogue. Sandbox opportunities, including PRE\_IPO fixtures, use the Sandbox opportunity catalogue; production PRE\_IPO uses the live offerings collection.

Fund prices are converted from the stated instrument currency using configured FX. A valid explicit `navUsd` is already USD. Missing NAV, currency or required FX returns `PRICE_UNAVAILABLE`; there is no $1 fallback. Read minimums in their stated currency.

Wallet reservation and holding changes occur atomically. Concurrent requests with different idempotency keys cannot overspend the wallet. Production subscription orders remain PENDING for the existing approval workflow; they do not create filled holdings at request time. Sandbox subscriptions simulate a fill and emit `order.filled`.

Only available FUND units can be redeemed by this route. Sandbox redemption atomically reduces units and credits the wallet, retains proportional remaining cost basis, and emits `wallet.credited`. Concurrent redemptions cannot credit the same units twice. Frozen or closed accounts cannot subscribe or redeem. These simulations do not certify provider settlement or live fund terms.

## Portfolio and valuation acceptance

A filled Sandbox subscription must appear in the customer portfolio, AUM and reconciliation before the workflow is considered accepted. Funds use stored NAV; bonds use stored unit prices; private commitments are reported at commitment cost, not an invented market quote. Missing optional catalogue fields are persisted as null. Invalid or unavailable pricing fails explicitly. Subscription minimums remain enforced.

Sandbox fills are virtual. Live subscriptions remain pending until the relevant operational allocation/approval; a pending request is not custody or market execution proof. Test redemption according to the fund's actual terms; instant redemption is not available for every product.
