API & Integration
Conventions that apply across every section of these docs. Read this once and the rest of the API behaves predictably.
Endpoint
One GraphQL endpoint, always POST:
https://platform-api.tradepost.co/graphql
Authenticate with your API key in the X-API-Key header — see Authentication.
Schema introspection is disabled. These docs are the schema reference; every operation and type you can call is documented here.
Casing
Everything is camelCase — input fields, output fields, enum-carrying field names. What you send is what you get back: allInPrice in, allInPrice out.
Errors
Two distinct layers, and robust integrations check both:
| Layer | Shape | Meaning |
|---|---|---|
| Payload error | { error: { message, code } } inside the operation's payload | The request was valid and authenticated; the operation failed for a domain reason (ORDER_SUBMISSION_NOT_FOUND, SIGMAFILL_MANAGED, DUPLICATE_REFERENCE, …). data is present; the payload's entity field is null |
| Top-level error | errors: [...] at the response root | Auth failures, malformed queries, or unexpected server errors. Unexpected failures are masked with a request ID — include it when contacting support@tradepost.co |
Domain error codes are stable strings — branch on code, not on message text.
Data conventions
- Money is integer USD cents, everywhere.
allInPrice: 450is $4.50 - BigInt fields (large aggregates like
openValueCents) serialize as JSON strings - IDs are UUIDs
- Timestamps are ISO 8601 with timezone, UTC
externalReferenceId— your own identifier, echoed back on reads and usable as a lookup and bulk-cancel handle. Unique per account where enforced (strategy groups); treat it as your idempotency key
Pagination
Two styles, by section:
| Style | Where | Mechanics |
|---|---|---|
| Keyset cursor | Order submissions, order executions | Pass pageInfo.endCursor back as pagination.after until hasNextPage is false. Stable under concurrent writes |
| Limit/offset | Catalog, strategies, keys | pagination: { limit, offset } with totalCount in the response |
Lean reads
List queries return lean rows by default; anything expensive is behind an opt-in include flag (includeProductData, includeChildBidOrAsk, includeTotals, includeStrategies, …). Each flag has a real query cost — ask only for what you render.
Forward compatibility
New fields may be added to any response or event payload at any time. Parse tolerantly: ignore unknown fields rather than rejecting them.
In this section
- Authentication — keys, the
X-API-Keyheader, auth failure shapes - Webhooks — durable server-to-server event delivery
- Real-time — websocket streaming