# Contract guarantees

> Canonical runtime promises for currency, freshness, retention, rate limits, and sandbox behavior.

# Contract guarantees

This page is the canonical summary of the guarantees that partners can safely build against. The OpenAPI specification is the executable reference for paths, schemas, and headers; this page explains the cross-cutting promises that apply across those operations. If a guide disagrees with this page or the specification, report the drift before relying on it.

## Currency and wallets

Every partner and sub-account wallet is **USD-denominated**. Local-currency deposits and withdrawals expose the applied FX rate and fee in the transaction response, but they do not create a second wallet currency. Record the returned rate and amount in your own audit trail.

## Market-data freshness

African equity prices are supplied by the exchanges on a **15-minute-delayed** basis. The Partner API
is pull-based and targets a **15-minute refresh cadence** during the published coverage window;
end-of-day values are finalized after the exchange close. `delayMinutes` is the feed delay,
`refreshIntervalSeconds` is the API refresh target, and `asOf` is the actual observation timestamp.
MyStocks holds full market-data rights for every supported exchange. SSE and webhook events provide
state changes, not tick-by-tick prices. Every listed equity has EOD data; reported OHLCV and history
depth vary by instrument, so follow the chart quality metadata.

## Retention and delivery

| Record or behavior | Contracted default |
| --- | ---: |
| Idempotency responses and request fingerprints | 24 hours |
| Webhook delivery logs | 90 days |
| Partner API audit events | 365 days |
| Webhook retry window | Up to 6 attempts, ending with the 2-hour back-off attempt |

An idempotent replay with the same key and the same request fingerprint returns the original response. Reusing a key with a different request is a conflict. Webhook consumers must deduplicate by `eventId`, acknowledge quickly, and use the deliveries endpoint to reconcile failures.

## Rate-limit headers

Every authenticated sandbox and production response exposes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. A `429` response also includes `Retry-After`. Limits use a one-minute sliding window and requests are not queued.

## Sandbox and production

Sandbox uses `https://mystocks.africa/api/sandbox/v1/partner` with `sk_sandbox_` keys. Registration and reset are the only root-level sandbox utilities: `POST /api/sandbox/v1/register` and `POST /api/sandbox/v1/reset`. Sandbox accounts receive virtual USD funds (currently $100,000), trades use accelerated simulated settlement, and no real money moves. The canonical deterministic lifecycle tools for new integrations are under `/api/sandbox/v1/partner/test-tools/*` and use the sandbox key.

The production-base `/api/v1/partner/test-tools/*` surface is restricted legacy compatibility for approved partners testing virtual events against live webhook configuration. It never places production trades or moves real funds. Deprecated `/sandbox/*` aliases must not be used in new integrations.

Production uses `https://mystocks.africa/api/v1/partner` with `pk_live_` keys and real settlement workflows. Complete the [go-live checklist](/partners/docs/going-live) before requesting production access.

## Linked references

- [Authentication and idempotency](/partners/docs/auth)
- [Rate limits](/partners/docs/rate-limits)
- [Market data](/partners/docs/market-data)
- [FX and local-currency trading](/partners/docs/fx-model)
- [Paper/demo trading](/partners/docs/paper-demo-trading)
- [Webhooks](/partners/docs/webhooks)
- [Privacy, retention, and residency](/partners/docs/privacy-compliance)