Introduction
The Octolit trading platform exposes six integration surfaces. They share one host, one JSON error shape and one way of thinking about keys and scopes.
#The surfaces
Partner API
34 operations under /api/external/v1. Company-level keys for brokers and partners: clients, accounts, SSO, money, trading on behalf, MT links, market data.
Trading API
22 operations under /api/open/v1. Client-level keys: a trader's own accounts, orders, positions, history, quotes and bars.
WebSocket stream
wss://…/rt/v1/ws - trading quotes and account events for Trading API keys. Tickets, limits, every message.
FIX 4.4
QUOTE and TRADE sessions over TLS. Logon, orders, cancels, replaces, status, positions, reject reasons.
Webhooks
17 signed events pushed to your HTTPS endpoint with retries over 24 hours.
Single sign-on
Inbound JWT (your platform signs) and outbound one-time login links (you ask, we sign).
Account
3 operations · Partner API
Clients
3 operations · Partner API
Users
4 operations · Partner API
Single sign-on
6 operations · Partner API
Trading accounts
4 operations · Partner API
Money
1 operations · Partner API
MT links
3 operations · Partner API
Market
3 operations · Partner API
Trading on behalf
7 operations · Partner API
Account
3 operations · Trading API
Market
5 operations · Trading API
Trading
11 operations · Trading API
Stream
1 operations · Trading API
Meta
2 operations · Trading API
#Conventions
| Host | https://api.your-brand.com stands for the API host of your Octolit installation. Both APIs and the WebSocket live on it; FIX uses the same host on port 5201. |
|---|---|
| Transport | HTTPS only. Requests and responses are application/json, UTF-8. Send Content-Type: application/json on every request with a body. |
| Keys | Header X-Api-Key (Partner) or X-API-Key (Trading), or Authorization: Bearer <key>. Never put a key in a URL. Authentication → |
| Timestamps | ISO 8601 in UTC with microseconds, e.g. 2026-11-11T09:30:00.000000Z. Webhook headers and WebSocket frames use Unix time (seconds or milliseconds, as documented). |
| Money & prices | Decimal numbers in the account or symbol currency. Order quantity is in lots or units (lots × contract size). |
| Ids | Platform ids are integers (trading_account_id, position_id). Your ids are strings: external_id (1-191 chars, letters, digits, . _ @ : + -) and client_order_id (1-64 chars, letters, digits, _ - : .). |
| Paging | List endpoints take limit and a cursor or updated_since and answer with next / has_more as documented per endpoint. |
| Errors | Non-2xx answers are { "error": { "code", "message", "details" } }. The code is stable; the message is for humans. Errors → |
| Idempotency | Money posting needs an idempotency_key; orders need a client_order_id; PUT /users is idempotent by external_id. Retrying is always safe. |
#Brand switches
Every surface is optional and switched per brand in the Octolit CRM (Settings › Brand settings). A call to a switched-off surface answers 403 with a code that names the switch:
| Switch | Off answers | Covers |
|---|---|---|
| Partner API | brand_disabled | Every Partner API call that touches the brand's users |
| Single sign-on | sso_disabled | Inbound JWT sign-in and outbound login links |
| Trading webhooks | no delivery | trade.*, margin.call, stop.out, demo.first_trade |
| Money posting | insufficient_scope | POST /users/{external_id}/transactions |
| Trending instruments | trending_disabled | GET …/trending on both APIs |
| Trading API | open_api_disabled (details.reason) | Every /api/open/v1 call, the WebSocket and FIX |
company_inactive) and a brand can be switched off (brand_inactive). Reads and writes both answer 403 then. #Versioning
Both APIs are at v1 and the version is part of the path. Additive changes (new fields, new events, new optional parameters) ship without a version bump and are listed in the changelog. Your code should ignore unknown JSON fields and unknown webhook event types. Breaking changes would get a new path prefix and a long overlap.
The OpenAPI documents are the contract: download them or fetch the live copy from your host (GET /api/external/v1/openapi.yaml, GET /api/open/v1/openapi.json).