# Partner API Specification

> September 2026 B2B specification, integration fundamentals, product reference, and clarifications for the current online API contract.

The September 2026 **MyStocks Partner API & Developer Platform Specification** brings together eight commercial API products, their endpoint inventory, error vocabulary, webhook events, and integration requirements.

[Download PartnerAPI.pdf (339 pages)](/docs/PartnerAPI.pdf) · [Browse all eight products](/partners/docs/api-products) · [Open API Reference](/partners/docs/api-reference)

## Environments and authentication

| Environment | Base URL | Standard API key prefix |
| --- | --- | --- |
| Production | `https://mystocks.africa/api/v1/partner` | `pk_live_` |
| Sandbox | `https://mystocks.africa/api/sandbox/v1/partner` | `sk_sandbox_` |

Send API credentials using `Authorization: Bearer` or `x-api-key`. Read-only data keys, OAuth client credentials, and Firebase-authenticated console operations have distinct scopes and requirements. Follow the [authentication guide](/partners/docs/auth) and each operation's security definition in the [API Reference](/partners/docs/api-reference).

Use [sandbox and paper trading](/partners/docs/paper-demo-trading) for integration testing. Check the product catalog's sandbox column before calling an operation: production-only endpoints and unsupported stubs are not fully simulated.

## Request safety and operational contracts

| Topic | Online guidance |
| --- | --- |
| Idempotency | [Authentication](/partners/docs/auth) and [contract guarantees](/partners/docs/contract-guarantees): mutation requirements, bootstrap exceptions, 24-hour replay retention, and payload mismatch handling. |
| Rate limits | [Tier quotas and response headers](/partners/docs/rate-limits): Starter 100, Growth 500, and Enterprise 2,000 requests per minute, with contracted custom limits where applicable. |
| HTTP errors and dealing-desk rejections | [Errors](/partners/docs/errors): distinguish synchronous request failures from asynchronous order rejection reasons. |
| Webhook signatures and retries | [Webhooks](/partners/docs/webhooks): event directory, raw-body HMAC-SHA256 verification, delivery logs, and retry behavior. |
| Event streams | [Server-Sent Events](/partners/docs/sse-events): connection limits, heartbeats, replay, and reconnection. |
| Production readiness | [Going live](/partners/docs/going-live), [controlled production pilot](/partners/docs/controlled-production-pilot), and [general availability](/partners/docs/general-availability). |

## Product and endpoint reference

The [product catalog](/partners/docs/api-products) covers all 194 operations across 148 route paths. Every product page includes method, path, operation ID, purpose, sandbox availability, and links to its implementation guides. The [interactive reference](/partners/docs/api-reference) contains request and response schemas, parameters, examples, and status codes.

The PDF's additional discovery and infrastructure section is separate from this inventory. Use [OpenAPI JSON](/openapi.json) or [OpenAPI YAML](/openapi.yaml) for public schema discovery. Partner brand discovery supports the hosted tenant experience; scheduler workers are operated by MyStocks and require internal credentials.

## Clarifications for the PDF edition

The downloadable PDF is preserved as supplied. Use the following current online guidance when integrating:

| PDF wording or example | Online contract clarification |
| --- | --- |
| OpenAPI 3.0.3 / API version 1.0.0 | The published machine-readable specification declares OpenAPI **3.1.0**, API version **1**. Use the version declared in the downloaded schema. |
| `partners.mystock.africa` and tenant examples with `mystock.africa` | The partner domain is `partners.mystocks.africa`; tenant domains use `mystocks.africa`. The documentation is also available at `https://mystocks.africa/partners/docs`. |
| OAuth JWT and `sec_live_` secret examples | Follow the [OAuth client credentials guide](/partners/docs/auth): the client secret is the API key; returned access tokens use `ms_oauth_` and expire after 15 minutes. Do not infer a JWT format. |
| Every operation has strict sandbox parity | Per-operation OpenAPI metadata and the product catalogs identify sandbox availability and unsupported stubs. |
| Every mutation requires idempotency with no exceptions | Credential bootstrap and recovery operations have documented exceptions. See [authentication](/partners/docs/auth). |
| `x-ratelimit-reset` is in milliseconds | `X-RateLimit-Reset` is a Unix timestamp in **seconds**; `Retry-After` is also in seconds. |
| Per-second burst allowances | Use the published [minute quotas and concurrent stream limits](/partners/docs/rate-limits); the PDF's burst figures are not a separate documented entitlement. |
| Real-time market intelligence or order book analytics | African equity quotes are **15-minute delayed**. Webhooks and SSE carry account and market-status events, not streaming price ticks or Level-2 depth. See [market data](/partners/docs/market-data). |
| Six webhook retries across two hours | The retry schedule contains six attempts including the initial attempt, with scheduled retry delays. See [webhook delivery semantics](/partners/docs/webhooks); do not treat two hours as a guaranteed total delivery window. |
| Generated sample values | Treat examples as illustrative; required fields, enums, eligibility, authentication, and response status codes come from the operation contract. |

For signature verification, use the [webhook guide's examples](/partners/docs/webhooks), including malformed-signature handling, rather than calling `timingSafeEqual` on unchecked buffers of potentially unequal length.

## Appendices and implementation resources

- **Exchanges, hours, and settlement:** use [market data and exchange calendars](/partners/docs/etfs-and-charts), market-status responses, and the [trade lifecycle](/partners/docs/lifecycles). The PDF's typical-hours table does not account for holidays or instrument-specific settlement.
- **KYC:** follow [sub-account onboarding](/partners/docs/sub-accounts) and [KYC, AML, and sanctions](/partners/docs/kyc-aml-sanctions). Confirm applicable limits and evidence requirements during onboarding; do not interpret the PDF's tier table as automatic approval or an unlimited trading entitlement.
- **SDKs and tooling:** use [SDKs and developer tools](/partners/docs/sdks-tools) for supported package names and installation instructions, and the [API Tester](/partners/docs/api-tester) for requests.
- **Support:** contact `support@mystocks.africa` or use the [partner support workflow](/partners/docs/team-access-support).