SDKs and Tools

Use the client source previews for transport, structured errors, request IDs, timeouts, safe retries, and webhook verification. They do not replace understanding the API contract: always read the endpoint's authentication, scope, idempotency, and lifecycle requirements.

Both clients now have a version-locked release pipeline. A signed partner-sdk-vX.Y.Z tag runs the contract suites, builds the npm and Python distributions, verifies their metadata, produces SHA-256 checksums and build provenance, publishes through npm and PyPI trusted publishing, and attaches the same artifacts to a GitHub release. Registry install commands will be added here only after that release completes successfully.

Client availability

Initialize a client

The SDK examples below are for approved pilot artifacts. Everyone else can use the equivalent raw HTTP tab today.

const BASE = "https://mystocks.africa/api/sandbox/v1/partner";
const apiKey = process.env.MYSTOCKS_API_KEY;

async function api(path, init = {}) {
return fetch(BASE + path, {
  ...init,
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", ...init.headers },
}).then(async (res) => {
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error?.message), body.error);
  return body;
});
}

Create a sub-account

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

Quote and place a trade

const quote = await api("/quote/SCOM.KE?type=BUY&quantity=10&subAccountId=" + user.subAccountId);
const order = await api("/users/" + user.subAccountId + "/trade", {
method: "POST",
headers: { "Idempotency-Key": "trade_user42_scom_001" },
body: JSON.stringify({ symbol: "SCOM.KE", type: "BUY", quantity: 10, quoteId: quote.quoteId }),
});

Verify a webhook

Always verify the exact, unparsed request bytes before decoding JSON.

const rawBody = req.body; // Buffer from express.raw({ type: "*/*" })
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const supplied = req.headers["x-mystocks-signature"] ?? "";
const valid = supplied.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(supplied), Buffer.from(expected));

API tools

Operational awareness

You do not need to poll the status page. Incidents are pushed to your registered webhooks as incident.declared / incident.resolved and streamed on GET /partner/stream. During planned maintenance the API returns 503 MAINTENANCE with a Retry-After header. See Errors for handling guidance, including read-only maintenance mode.

SDK behavior to rely on

• Reads and idempotent writes may retry transient 429, 500, 502, 503, and 504 responses.
• Non-idempotent writes are not automatically retried.
• Preserve the same Idempotency-Key when retrying a write.
• Capture X-Request-ID in logs and support tickets.
• Verify webhooks using the raw body and the x-mystocks-signature header.

Begin with Authentication and the Broker API quickstart.