# 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.

<FlowDiagram
  direction="horizontal"
  nodes={[
    { label: 'Subscribe', sublabel: 'POST /users/{userId}/subscribe', tone: 'accent' },
    { label: 'PENDING', sublabel: 'USD reserved' },
    { label: 'COMPLETED', sublabel: 'units allocated', tone: 'success' },
  ]}
/>

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

## Bonds

<MethodTag m="GET" /> `/bonds` · <MethodTag m="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", "yield": 15.8 }], "count": 1 }
```

## Funds

<MethodTag m="GET" /> `/funds` · <MethodTag m="GET" /> `/funds/{id}`

Money-market and yield funds with published redemption terms; only funds whose `redemptionType` is
`instant` credit the wallet in the redemption call. Responses include NAV per unit, yield,
distribution frequency, minimum investment, and whether the fund is open for subscriptions.

```json
{ "funds": [{ "id": "fund_mmf_africa", "name": "Africa Money Market Fund", "fundType": "MONEY_MARKET", "navPerUnit": 1.0, "annualYield": 12.5, "currency": "USD", "minInvestment": 50, "status": "OPEN", "redemptionType": "instant", "distributionFrequency": "Monthly" }], "count": 1 }
```

## Opportunities

<MethodTag m="GET" /> `/opportunities` · <MethodTag m="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"`.

<ParamTable fields={[
  { name: 'type', type: 'string', required: false, desc: '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

<MethodTag m="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`.

<ParamTable fields={[
  { name: 'assetType', type: 'string', required: true,  desc: 'BOND | FUND | OPPORTUNITY | PRE_IPO' },
  { name: 'assetId',   type: 'string', required: true,  desc: 'Firestore doc ID from the relevant list endpoint.' },
  { name: 'units',     type: 'number', required: false, desc: 'Whole units. Required for BOND and FUND.' },
  { name: 'amount',    type: 'number', required: false, desc: '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

<MethodTag m="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.

<ParamTable fields={[
  { name: 'holdingId',     type: 'string', required: true, desc: 'Sub-account holding doc ID (same as the fund doc ID).' },
  { name: 'unitsToRedeem', type: 'number', required: true, desc: 'Units to redeem. Must not exceed unlockedUnits.' },
]} />