MyStocks Partner API

curl -X POST https://mystocks.africa/api/sandbox/v1/register \
  -H "Content-Type: application/json" \
  -d '{ "businessName": "Acme", "email": "dev@acme.com" }'

{
  "apiKey": "sk_sandbox_xxxxxxxxxxxxxxxx",
  "walletBalance": 100000,
  "currency": "USD"
}

curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users \
  -H "Authorization: Bearer sk_sandbox_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_42",
    "displayName": "Jane Doe",
    "email": "jane@example.com"
  }'

{
  "subAccountId": "usr_xxxxxxxxxxxx",
  "externalId": "user_42",
  "displayName": "Jane Doe",
  "kycStatus": "NONE",
  "status": "active",
  "wallet": {
    "currency": "USD",
    "balance": 0
  }
}

curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/deposit \
  -H "Authorization: Bearer sk_sandbox_<your_key>" \
  -H "Idempotency-Key: dep_user42_001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "localAmount": 655000,
    "localCurrency": "KES",
    "fxRate": 1310,
    "note": "Mpesa ref mpesa_QHJ29SK"
  }'

{
  "message": "Deposit successful.",
  "subAccountId": "usr_xxxxxxxxxxxx",
  "amount": 500,
  "currency": "USD",
  "newSubBalance": 500,
  "newMasterBalance": 99500
}

curl "https://mystocks.africa/api/sandbox/v1/partner/stocks/SCOM.KE" \
  -H "Authorization: Bearer sk_sandbox_<your_key>"

{
  "symbol": "SCOM.KE",
  "name": "Safaricom PLC",
  "exchange": "NSE",
  "currency": "KES",
  "price": 16.5,
  "usdPrice": 0.0126,
  "change": 0.25,
  "changePct": 1.54
}

curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/trade \
  -H "Authorization: Bearer sk_sandbox_<your_key>" \
  -H "Idempotency-Key: trade_user42_001" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol":   "SCOM.KE",
    "type":     "BUY",
    "quantity": 1000
  }'

{
  "status": "FILLED",
  "orderId": "ord_xxxxxxxxxxxx",
  "subAccountId": "usr_xxxxxxxxxxxx",
  "externalId": "user_42",
  "type": "BUY",
  "symbol": "SCOM.KE",
  "quantity": 1000,
  "usdPrice": 0.0126,
  "localPrice": 16.5,
  "currency": "KES",
  "gross": 12.6,
  "fee": 0.09,
  "totalCost": 12.69,
  "newSubBalance": 487.31,
  "note": "Order filled instantly in sandbox. Production trades are PENDING until admin approval."
}

curl "https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/orders?limit=1" \
  -H "Authorization: Bearer sk_sandbox_<your_key>"

{
  "orders": [
    {
      "orderId": "ord_xxxxxxxxxxxx",
      "status": "FILLED",
      "symbol": "SCOM.KE",
      "type": "BUY",
      "quantity": 1000,
      "usdPrice": 0.0126,
      "localPrice": 16.5,
      "currency": "KES",
      "gross": 12.6,
      "fee": 0.09,
      "totalCost": 12.69,
      "filledAt": "2026-05-19T10:15:00Z"
    }
  ],
  "count": 1
}

const BASE = 'https://mystocks.africa/api/v1/partner';
const KEY  = process.env.MYSTOCKS_API_KEY;
const h    = { 'x-api-key': KEY, 'Content-Type': 'application/json' };

// 1. Create sub-account
const { subAccountId } = await fetch(`${BASE}/users`, {
  method: 'POST',
  headers: h,
  body: JSON.stringify({ externalId: 'user_42', displayName: 'Amara Diallo', email: 'amara@example.com' }),
}).then(r => r.json());

// 2. Assert KYC (after your own verification flow)
await fetch(`${BASE}/users/${subAccountId}/kyc`, {
  method: 'POST', headers: h,
  body: JSON.stringify({ status: 'VERIFIED', level: 'FULL', provider: 'Sumsub', reference: 'sum_ref_123' }),
});

// 3. Deposit $100 (idempotent — safe to retry)
await fetch(`${BASE}/users/${subAccountId}/deposit`, {
  method: 'POST',
  headers: { ...h, 'Idempotency-Key': 'dep_user42_${Date.now()}' },
  body: JSON.stringify({ amount: 100, localAmount: 13100, localCurrency: 'KES', fxRate: 131 }),
});

// 4. Get live quote
const { data: quotes } = await fetch(
  `${BASE}/market/quotes?symbol=SCOM.KE`, { headers: h }
).then(r => r.json());
const { usdPrice } = quotes[0];

// 5. Place BUY order
const { orderId } = await fetch(`${BASE}/users/${subAccountId}/trade`, {
  method: 'POST',
  headers: { ...h, 'Idempotency-Key': 'trade_user42_buy_scom_${Date.now()}' },
  body: JSON.stringify({ symbol: 'SCOM.KE', type: 'BUY', cashValue: 50 }),
}).then(r => r.json());
// → 202 Accepted. orderId is PENDING, $50 + fee escrowed.

// 6. (Optional) Poll until settled — or use a webhook instead (step 7)
let order;
do {
  await new Promise(r => setTimeout(r, 10_000)); // wait 10 s
  order = await fetch(`${BASE}/users/${subAccountId}/orders/${orderId}`, { headers: h }).then(r => r.json());
} while (order.status === 'PENDING' || order.status === 'PROCESSING');

// 8. Show portfolio
const portfolio = await fetch(`${BASE}/users/${subAccountId}/portfolio`, { headers: h }).then(r => r.json());
console.log(portfolio.holdings); // [{ symbol: 'SCOM.KE', units: ..., currentValue: ... }]

const BASE = 'https://mystocks.africa/api/v1/partner';
const h    = { 'x-api-key': process.env.MYSTOCKS_API_KEY };

async function loadPortfolioScreen(subAccountId) {
  // 1. Fetch holdings + summary
  const { holdings, summary } = await fetch(
    `${BASE}/users/${subAccountId}/portfolio`, { headers: h }
  ).then(r => r.json());

  // 2. Refresh prices for all held symbols in one call
  const symbols = holdings.map(h => h.symbol).join(',');
  const { data: quotes } = await fetch(
    `${BASE}/market/quotes?symbols=${symbols}`, { headers: h }
  ).then(r => r.json());
  const priceMap = Object.fromEntries(quotes.map(q => [q.symbol, q.usdPrice]));

  // 3. Enrich holdings with live prices
  const enriched = holdings.map(holding => ({
    ...holding,
    livePrice:     priceMap[holding.symbol] ?? holding.currentUsdPrice,
    liveValue:     (priceMap[holding.symbol] ?? holding.currentUsdPrice) * holding.units,
  }));

  // 4. Dividend history
  const { dividends } = await fetch(
    `${BASE}/users/${subAccountId}/dividends?limit=10`, { headers: h }
  ).then(r => r.json());

  // 5. Upcoming dividends
  const { dividends: upcoming } = await fetch(
    `${BASE}/dividends/calendar`, { headers: h }
  ).then(r => r.json());
  const eligible = upcoming.filter(d => d.partnerEligible);

  return { summary, holdings: enriched, recentDividends: dividends, upcomingDividends: eligible };
}

// Export AUM report to CSV
const csv = await fetch(`${BASE}/report/aum?format=csv`, { headers: h }).then(r => r.text());

// Safe to ship in browser JS — pk_data_ keys are read-only
const DATA_KEY = 'pk_data_xxxxxxxxxxxxxxxx'; // from POST /api-keys/data-key
const BASE     = 'https://mystocks.africa/api/v1/partner';
const h        = { 'x-api-key': DATA_KEY };

// Ticker widget — poll every 15 s during market hours
async function refreshTicker(symbols) {
  const { data } = await fetch(
    `${BASE}/market/quotes?symbols=${symbols.join(',')}`, { headers: h }
  ).then(r => r.json());
  return data; // [{ symbol, usdPrice, change, volume, ... }]
}

// Price chart for a single stock
async function loadChart(symbol, period = '1M') {
  const { data } = await fetch(
    `${BASE}/stocks/${symbol}/chart?period=${period}`, { headers: h }
  ).then(r => r.json());
  return data; // [{ date, close, change, changePercent }]
}

// Top movers board
async function loadMovers(exchange = 'NSE', direction = 'gainers') {
  const { data } = await fetch(
    `${BASE}/market/movers?exchange=${exchange}&direction=${direction}&limit=5`, { headers: h }
  ).then(r => r.json());
  return data;
}

// Market open/closed status
async function isMarketOpen(exchange = 'NSE') {
  const { exchanges } = await fetch(`${BASE}/market/status`, { headers: h }).then(r => r.json());
  return exchanges.find(e => e.code === exchange)?.isOpen ?? false;
}

// Company card (logo, description, fundamentals)
async function loadCompanyCard(symbol) {
  return fetch(`${BASE}/companies/${symbol}`, { headers: h }).then(r => r.json());
}

curl -X POST "https://mystocks.africa/api/v1/partner/api-keys/rotate" \
  -H "Authorization: Bearer pk_live_<current_key>"

{
  "apiKey": "pk_live_new_xxxxxxxxxxxxxxxx",
  "createdAt": "2026-06-09T10:00:00Z",
  "migrated": {
    "webhooks": 3,
    "subAccounts": 142,
    "deliveries": 0
  }
}

curl -X POST "https://mystocks.africa/api/v1/partner/api-keys/revoke" \
  -H "Authorization: Bearer <firebase-id-token>"

{
  "message": "Key revoked. Contact support@mystocks.africa to issue a replacement.",
  "revokedAt": "2026-06-09T10:05:00Z"
}

{
  "dataKey": "pk_data_xxxxxxxxxxxxxxxx",
  "maskedKey": "pk_data_xxxxxxxx...",
  "createdAt": "2026-06-09T10:00:00Z"
}

{
  "logoUrl": "https://acme.com/logo.svg",
  "smtp": {
    "host": "smtp.acme.com",
    "port": 587,
    "user": "noreply@acme.com",
    "hasPassword": true,
    "from": "noreply@acme.com"
  },
  "updatedAt": "2026-06-09T10:00:00Z"
}

curl -X POST "https://mystocks.africa/api/v1/partner/settings" \
  -H "Authorization: Bearer pk_live_<key>"

{
  "message": "Test email sent to dev@acme.com via smtp.acme.com:587."
}

{
  "etfs": [
    {
      "id": "STXEME.ZA",
      "symbol": "STXEME.ZA",
      "name": "Satrix MSCI Emerging Markets ETF",
      "exchange": "JSE",
      "currency": "ZAR",
      "price": 75,
      "usdPrice": 4.55,
      "assetType": "ETF",
      "logoUrl": "https://mystocks.africa/logos/stxeme-za.svg",
      "fundMetadata": {
        "brand": "Satrix",
        "expenseRatio": 0.38,
        "geographicalFocus": "Global Emerging Markets",
        "indexTracked": "MSCI Emerging Markets Index",
        "riskLevel": "HIGH",
        "managementStyle": "PASSIVE"
      }
    }
  ],
  "count": 1
}

{
  "symbol": "STXEME.ZA",
  "currency": "ZAR",
  "period": "3m",
  "labels": [
    "2026-03-01",
    "2026-04-01",
    "2026-05-23"
  ],
  "opens": [
    72.8,
    73.9,
    74.6
  ],
  "highs": [
    73.9,
    74.5,
    75.2
  ],
  "lows": [
    72.5,
    73.4,
    74.3
  ],
  "prices": [
    73.5,
    74.2,
    75
  ],
  "volumes": [
    12000,
    18500,
    24000
  ],
  "priceHistory": [
    {
      "date": "2026-03-01T00:00:00.000Z",
      "open": 72.8,
      "high": 73.9,
      "low": 72.5,
      "price": 73.5,
      "close": 73.5,
      "usdPrice": 4.45,
      "volume": 12000
    },
    {
      "date": "2026-04-01T00:00:00.000Z",
      "open": 73.9,
      "high": 74.5,
      "low": 73.4,
      "price": 74.2,
      "close": 74.2,
      "usdPrice": 4.5,
      "volume": 18500
    },
    {
      "date": "2026-05-23T19:59:41.000Z",
      "open": 74.6,
      "high": 75.2,
      "low": 74.3,
      "price": 75,
      "close": 75,
      "usdPrice": 4.55,
      "volume": 24000
    }
  ]
}

{
  "data": [
    {
      "symbol": "SCOM.KE",
      "name": "Safaricom PLC",
      "exchange": "NSE",
      "currency": "KES",
      "price": 16.5,
      "usd_price": 0.0126,
      "change": 0.25,
      "change_pct": 0.015385,
      "volume": 4210000,
      "bid": null,
      "ask": null,
      "market_status": "OPEN"
    },
    {
      "symbol": "GLD.ZA",
      "name": "NewGold Issuer ETF",
      "exchange": "JSE",
      "currency": "ZAR",
      "price": 410,
      "usd_price": 24.85,
      "change": -1.5,
      "change_pct": -0.003643,
      "volume": 0,
      "bid": null,
      "ask": null,
      "market_status": "OPEN"
    }
  ],
  "not_found": [
    "INVALID_XYZ"
  ],
  "meta": {
    "request_id": "4a3f9c1e-7b2d-4e8a-9f06-1c5d3e2b7a04",
    "timestamp": "2026-06-04T09:42:00.000Z"
  }
}

{
  "data": [
    {
      "symbol": "EABL.KE",
      "name": "East African Breweries",
      "exchange": "NSE",
      "currency": "KES",
      "price": 185,
      "usd_price": 1.423077,
      "change": 10,
      "change_pct": 0.057143,
      "volume": 312000,
      "market_status": "OPEN"
    },
    {
      "symbol": "SCOM.KE",
      "name": "Safaricom PLC",
      "exchange": "NSE",
      "currency": "KES",
      "price": 16.5,
      "usd_price": 0.126923,
      "change": 0.5,
      "change_pct": 0.03125,
      "volume": 4210000,
      "market_status": "OPEN"
    }
  ],
  "meta": {
    "exchange": "NSE",
    "direction": "gainers",
    "total_count": 48,
    "page": 1,
    "per_page": 5,
    "has_next": true
  }
}

{
  "data": [
    {
      "exchange": "NSE",
      "date": "2026-06-01",
      "reason": "Madaraka Day"
    },
    {
      "exchange": "NSE",
      "date": "2026-10-10",
      "reason": "Utamaduni Day"
    },
    {
      "exchange": "NSE",
      "date": "2026-10-20",
      "reason": "Mashujaa Day"
    },
    {
      "exchange": "NSE",
      "date": "2026-12-12",
      "reason": "Jamhuri Day"
    },
    {
      "exchange": "NSE",
      "date": "2026-12-25",
      "reason": "Christmas Day"
    },
    {
      "exchange": "NSE",
      "date": "2026-12-26",
      "reason": "Boxing Day"
    }
  ],
  "count": 6,
  "from": "2026-06-06",
  "to": "2026-12-31",
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-06T10:00:00Z",
    "exchange": "NSE"
  }
}

{
  "data": [
    {
      "code": "NSE",
      "name": "Nairobi Securities Exchange",
      "country": "Kenya",
      "currency": "KES",
      "timezone": "Africa/Nairobi",
      "open": "09:00",
      "close": "15:00",
      "settlement": "T+3",
      "isOpen": true,
      "status": "OPEN"
    },
    {
      "code": "NGX",
      "name": "Nigerian Exchange Group",
      "country": "Nigeria",
      "currency": "NGN",
      "timezone": "Africa/Lagos",
      "open": "10:00",
      "close": "14:30",
      "settlement": "T+3",
      "isOpen": false,
      "status": "CLOSED"
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-09T10:00:00Z"
  }
}

{
  "data": [
    {
      "date": "2026-06-02",
      "open": null,
      "high": null,
      "low": null,
      "close": 16.25,
      "volume": 3820000,
      "ohlc_available": false
    },
    {
      "date": "2026-06-03",
      "open": 16.3,
      "high": 16.75,
      "low": 16.1,
      "close": 16.5,
      "volume": 4210000,
      "ohlc_available": true
    }
  ],
  "meta": {
    "symbol": "SCOM.KE",
    "exchange": "NSE",
    "from": "2026-06-01",
    "to": "2026-06-06",
    "interval": "1d",
    "request_id": "req_def456",
    "timestamp": "2026-06-09T10:00:00Z"
  }
}

X-RateLimit-Limit: 100        # your tier's request ceiling per minute
X-RateLimit-Remaining: 43    # requests remaining in the current window
X-RateLimit-Reset: 1751400060  # Unix timestamp (seconds) when the window resets
Retry-After: 17              # seconds until the window resets (only set on 429 responses)

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Tier: starter (100 req/min). Resets in 17s."
  }
}

async function fetchWithBackoff(url, options, retries = 3) {
  const res = await fetch(url, options);
  if (res.status === 429 && retries > 0) {
    const reset = Number(res.headers.get('X-RateLimit-Reset'));
    const delay = Math.max(reset * 1000 - Date.now(), 1000);
    await new Promise(r => setTimeout(r, delay));
    return fetchWithBackoff(url, options, retries - 1);
  }
  return res;
}

async function fetchAllOrders(apiKey) {
  const orders = [];
  let cursor = null;

  do {
    const url = new URL('https://mystocks.africa/api/v1/partner/orders');
    url.searchParams.set('limit', '200');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res  = await fetch(url, { headers: { 'x-api-key': apiKey } });
    const page = await res.json();

    orders.push(...page.orders);
    cursor = page.nextCursor;     // null on the last page
  } while (cursor);

  return orders;
}

{
  "stocks": [
    {
      "id": "SCOM.KE",
      "symbol": "SCOM.KE",
      "name": "Safaricom PLC",
      "exchange": "NSE",
      "currency": "KES",
      "sector": "Telecommunications",
      "assetType": "STOCK",
      "listingStatus": "ACTIVE",
      "price": 16.5,
      "usdPrice": 0.0126,
      "change": 0.25,
      "changePct": 1.54,
      "volume": 4210000,
      "logoUrl": "https://mystocks.africa/logos/scom-ke.svg",
      "lastPriceUpdate": "2026-06-04T09:45:00Z"
    }
  ],
  "count": 1,
  "hasMore": true,
  "nextCursor": "cursor_abc"
}

{
  "id": "SCOM.KE",
  "symbol": "SCOM.KE",
  "name": "Safaricom PLC",
  "exchange": "NSE",
  "currency": "KES",
  "sector": "Telecommunications",
  "assetType": "STOCK",
  "listingStatus": "ACTIVE",
  "price": 16.5,
  "usdPrice": 0.0126,
  "change": 0.25,
  "changePct": 1.54,
  "open": 16.2,
  "dayHigh": 16.75,
  "dayLow": 16.1,
  "previousClose": 16.25,
  "volume": 4210000,
  "logoUrl": "https://mystocks.africa/logos/scom-ke.svg",
  "lastPriceUpdate": "2026-06-04T09:45:00Z"
}

{
  "symbol": "SCOM.KE",
  "pulse": [
    {
      "id": "pulse_abc",
      "title": "Safaricom H1 profit up 14%",
      "summary": "Safaricom posted KES 23.4bn net profit for H1 2026, driven by M-PESA revenue growth.",
      "source": "MyStocks Africa",
      "publishedAt": "2026-06-03T08:00:00Z",
      "url": "https://mystocks.africa/market-intel/safaricom-h1-2026"
    }
  ],
  "count": 1
}

{
  "articles": [
    {
      "id": "intel_ngx_q2",
      "title": "NGX Q2 2026 Market Wrap",
      "summary": "NGX All-Share Index gained 4.2% in Q2 led by banking and cement sectors.",
      "slug": "ngx-q2-2026-market-wrap",
      "category": "macro",
      "symbols": [],
      "exchange": "NGX",
      "imageUrl": null,
      "source": "MyStocks Africa",
      "sourceUrl": null,
      "publishedAt": "2026-06-01T08:00:00Z",
      "createdAt": "2026-06-01T07:30:00Z"
    }
  ],
  "count": 1
}

{
  "id": "intel_ngx_q2",
  "title": "NGX Q2 2026 Market Wrap",
  "summary": "NGX All-Share Index gained 4.2% in Q2.",
  "body": "<p>Full article content here...</p>",
  "slug": "ngx-q2-2026-market-wrap",
  "category": "macro",
  "symbols": [
    "DANGCEM.NG",
    "GTCO.NG"
  ],
  "exchange": "NGX",
  "imageUrl": null,
  "source": "MyStocks Africa",
  "sourceUrl": null,
  "author": "MyStocks Research",
  "tags": [
    "NGX",
    "Q2",
    "equities"
  ],
  "publishedAt": "2026-06-01T08:00:00Z",
  "createdAt": "2026-06-01T07:30:00Z",
  "updatedAt": null
}

{
  "subAccountId": "usr_abc123",
  "externalId": "user_42",
  "displayName": "Jane Doe",
  "email": "jane@example.com",
  "kycStatus": "NONE",
  "kycLevel": "NONE",
  "status": "active",
  "walletBalance": 0
}

curl -X PATCH "https://mystocks.africa/api/v1/partner/users/usr_abc123" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{"status":"frozen"}'

{
  "message": "Deposit successful.",
  "subAccountId": "usr_abc123",
  "amount": 500,
  "currency": "USD",
  "newSubBalance": 500,
  "newMasterBalance": 99500
}

{
  "message": "Withdrawal successful.",
  "subAccountId": "usr_abc123",
  "amount": 200,
  "currency": "USD",
  "newSubBalance": 300,
  "newMasterBalance": 99700
}

curl -X POST "https://mystocks.africa/api/v1/partner/users/usr_abc123/kyc" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{"status":"VERIFIED","level":"BASIC","reference":"kyc_session_88721"}'

{
  "message": "KYC status updated.",
  "subAccountId": "usr_abc123",
  "kycStatus": "VERIFIED",
  "kycLevel": "BASIC"
}

{
  "symbol": "SCOM.KE",
  "name": "Safaricom PLC",
  "exchange": "NSE",
  "currency": "KES",
  "type": "BUY",
  "quantity": 500,
  "localPrice": 16.5,
  "usdPrice": 0.127306,
  "gross": 63.65,
  "baseFee": 0.48,
  "partnerMarkupFee": 0,
  "fee": 0.48,
  "totalCost": 64.13,
  "walletBalance": 1250,
  "sufficientFunds": true,
  "feeRate": 0.75,
  "note": "This is a quote only. No order has been placed."
}

{
  "status": "PENDING",
  "orderId": "ord_abc123",
  "subAccountId": "usr_abc123",
  "externalId": "user_42",
  "type": "BUY",
  "symbol": "SCOM.KE",
  "quantity": 1000,
  "priceAtOrder": 16.5,
  "usdPriceAtOrder": 0.0126,
  "gross": 12.6,
  "baseFee": 0.09,
  "partnerMarkupFee": 0,
  "fee": 0.09,
  "totalCost": 12.69,
  "note": "Order is pending admin approval. Funds reserved from sub-account wallet."
}

{
  "orders": [
    {
      "id": "ord_abc123",
      "symbol": "SCOM.KE",
      "name": "Safaricom PLC",
      "exchange": "NSE",
      "type": "BUY",
      "status": "COMPLETED",
      "quantity": 1000,
      "priceAtOrder": 16.5,
      "usdPriceAtOrder": 0.0126,
      "totalAmount": 12.69,
      "feeAmount": 0.09,
      "currency": "USD",
      "localCurrency": "KES",
      "rejectionCode": null,
      "rejectionReason": null,
      "settledAt": "2026-06-04T11:30:00Z",
      "createdAt": "2026-06-04T09:45:00Z"
    }
  ],
  "count": 1,
  "hasMore": false,
  "nextCursor": null
}

{
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "DEPOSIT",
      "status": "COMPLETED",
      "direction": "CREDIT",
      "amount": 500,
      "currency": "USD",
      "description": "Partner deposit",
      "reference": "dep_riven_user_42_1743152580",
      "createdAt": "2026-06-01T10:00:00Z",
      "settledAt": "2026-06-01T10:00:01Z"
    },
    {
      "id": "txn_xyz789",
      "type": "INVEST",
      "status": "PENDING",
      "direction": "DEBIT",
      "amount": 64.13,
      "currency": "USD",
      "description": "BUY SCOM.KE x500",
      "reference": "ord_def456",
      "createdAt": "2026-06-04T09:45:00Z",
      "settledAt": null
    }
  ],
  "count": 2,
  "hasMore": false,
  "nextCursor": null
}

{
  "walletBalance": 487.31,
  "totalValue": 512.31,
  "holdings": [
    {
      "symbol": "SCOM.KE",
      "name": "Safaricom PLC",
      "quantity": 1000,
      "avgCostUsd": 0.01269,
      "currentPriceUsd": 0.0126,
      "marketValue": 12.6,
      "unrealizedPnl": -0.09,
      "currency": "KES"
    }
  ]
}

{
  "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": [
    {
      "id": "fund_mmf_africa",
      "name": "Africa Money Market Fund",
      "fundType": "MONEY_MARKET",
      "navPerUnit": 1,
      "annualYield": 12.5,
      "currency": "USD",
      "minInvestment": 50,
      "status": "OPEN",
      "redemptionType": "instant",
      "distributionFrequency": "Monthly"
    }
  ],
  "count": 1
}

{
  "opportunities": [
    {
      "id": "TREEPZ-PRE-IPO",
      "assetType": "PRE_IPO",
      "name": "Treepz — Pre-IPO Round",
      "slug": "treepz-pre-ipo",
      "symbol": null,
      "issuer": null,
      "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",
      "maturityDate": null,
      "expectedExitDate": "2027-06-30",
      "createdAt": "2026-05-01T10:00:00Z"
    }
  ],
  "count": 1
}

{
  "id": "TREEPZ-PRE-IPO",
  "assetType": "PRE_IPO",
  "name": "Treepz — Pre-IPO Round",
  "slug": "treepz-pre-ipo",
  "symbol": null,
  "issuer": null,
  "description": "Ghana-based intercity bus platform with 250+ routes 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",
  "maturityDate": null,
  "expectedExitDate": "2027-06-30",
  "createdAt": "2026-05-01T10:00:00Z"
}

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

curl "https://mystocks.africa/api/v1/partner/account" \
  -H "Authorization: Bearer pk_live_<key>"

{
  "masterWalletBalance": 94500,
  "totalAum": 45230.5,
  "subAccountCount": 142,
  "currency": "USD"
}

{
  "id": "tup_abc123",
  "amount": 10000,
  "currency": "USD",
  "status": "PENDING",
  "reference": "wire_TXN987654",
  "createdAt": "2026-06-09T10:00:00Z"
}

{
  "id": "pay_abc123",
  "amount": 5000,
  "currency": "USD",
  "status": "PENDING",
  "reference": "payout_REF123",
  "createdAt": "2026-06-09T10:00:00Z"
}

curl https://mystocks.africa/api/v1/partner/users/usr_abc123/watchlist \
  -H "x-api-key: pk_live_KEY"

{
  "data": [
    {
      "assetId": "scom_ke_01",
      "symbol": "SCOM.KE",
      "name": "Safaricom PLC",
      "exchange": "NSE",
      "sourceType": "LISTED_STOCK",
      "price": 16.25,
      "usdPrice": 0.1258,
      "change": 1.56,
      "currency": "KES",
      "addedAt": "2026-06-06T08:00:00Z"
    }
  ],
  "count": 1,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-06T08:01:00Z"
  }
}

curl -X POST https://mystocks.africa/api/v1/partner/users/usr_abc123/watchlist \
  -H "x-api-key: pk_live_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"SCOM.KE"}'

{
  "assetId": "scom_ke_01",
  "symbol": "SCOM.KE",
  "name": "Safaricom PLC",
  "exchange": "NSE",
  "addedAt": "2026-06-06T08:00:00Z",
  "meta": {
    "request_id": "req_abc124",
    "timestamp": "2026-06-06T08:00:00Z",
    "symbol": "SCOM.KE"
  }
}

curl -X DELETE https://mystocks.africa/api/v1/partner/users/usr_abc123/watchlist/SCOM.KE \
  -H "x-api-key: pk_live_KEY"

curl -X POST "https://mystocks.africa/api/v1/partner/webhooks" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/mystocks",
    "events": ["order.filled","order.rejected","deposit.confirmed","kyc.updated"],
    "secret": "my-signing-secret-min-16-chars"
  }'

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/mystocks",
  "events": [
    "order.filled",
    "order.rejected",
    "deposit.confirmed",
    "kyc.updated"
  ],
  "status": "active"
}

{
  "event": "order.filled",
  "timestamp": "2026-06-06T10:32:00Z",
  "data": {
    "...": "event-specific fields — see reference below"
  }
}

# Fire a test.event delivery immediately
curl -X POST "https://mystocks.africa/api/v1/partner/webhooks/wh_abc123/test" \
  -H "Authorization: Bearer pk_live_<key>"

# Inspect delivery log
curl "https://mystocks.africa/api/v1/partner/webhooks/wh_abc123/deliveries?limit=10" \
  -H "Authorization: Bearer pk_live_<key>"

{
  "deliveries": [
    {
      "id": "del_abc",
      "eventId": "evt_abc123",
      "event": "order.filled",
      "status": 200,
      "duration": 142,
      "attemptedAt": "2026-06-04T11:30:01Z",
      "success": true
    },
    {
      "id": "del_def",
      "eventId": "evt_def456",
      "event": "deposit.confirmed",
      "status": 503,
      "duration": 8000,
      "attemptedAt": "2026-06-04T10:00:00Z",
      "success": false,
      "nextRetryAt": "2026-06-04T10:05:00Z"
    }
  ],
  "count": 2,
  "hasMore": false,
  "nextCursor": null
}

curl "https://mystocks.africa/api/v1/partner/sla" \
  -H "Authorization: Bearer pk_live_<key>"

{
  "status": "OPERATIONAL",
  "tier": "starter",
  "incidents": [],
  "maintenance": [
    {
      "id": "mnt_abc123",
      "title": "NGX data feed upgrade",
      "scheduledStart": "2026-06-15T02:00:00Z",
      "scheduledEnd": "2026-06-15T04:00:00Z",
      "affectedServices": [
        "market-data"
      ],
      "status": "SCHEDULED"
    }
  ],
  "services": [
    {
      "name": "Market Data",
      "status": "OPERATIONAL"
    },
    {
      "name": "Order Execution",
      "status": "OPERATIONAL"
    },
    {
      "name": "Webhooks",
      "status": "OPERATIONAL"
    },
    {
      "name": "Sub-Accounts",
      "status": "OPERATIONAL"
    }
  ],
  "checkedAt": "2026-06-09T10:00:00Z"
}