Learn these once instead of per endpoint.

A small number of rules hold everywhere. Every item on this page is something that breaks a naive client, so it is worth reading before you write a model class rather than after.

Money and quantities are strings

Never parse a monetary value into a float. Not in your ORM, not in your serialiser, not “just for the chart”. Floating-point arithmetic silently corrupts money, and in a regulated context that is a reportable error rather than a rounding curiosity.

# Python
from decimal import Decimal
balance = Decimal(response["cash_balance"])      # right
balance = float(response["cash_balance"])        # wrong, and it will bite you

// TypeScript
import { Decimal } from "decimal.js";
const balance = new Decimal(response.cash_balance);  // right
const balance = Number(response.cash_balance);       // wrong

The API does not normalise what you send

A quantity posted as "1.5" is stored as "1.5" and returned as "1.5" on every subsequent read — not "1.50000000". The precisions above describe values the platform computes; values you supply come back exactly as written. Trailing zeros are your responsibility. Compare as decimals, never as strings.

Currency is explicit — under two different field names

Currency is never implied, but the field name depends on the object:

Reading currency off an account returns nothing. ISO 4217 three-letter codes throughout; USD, GBP and EUR are supported.

Typed security identifiers — on the trading surface

On orders, positions, tax lots and settlements there is no bare symbol field. A security is an object:

{ "type": "ticker", "value": "AAPL" }
{ "type": "cusip",  "value": "037833100" }
{ "type": "isin",   "value": "US0378331005" }

Identifiers

Every entity id is a prefixed ULID — a type prefix, an underscore, and 26 Crockford base-32 characters. ULIDs rather than UUIDs because they sort lexicographically by creation time and are URL-safe with no escaping.

acct_01HV4Y2K3M5N8P9QR2ST4UVWXY

Timestamps

Always UTC. Fractional precision and suffix are not uniform across services, so parse with a conformant ISO 8601 parser rather than pattern-matching:

All three are valid ISO 8601 UTC and any conformant parser handles them. A regex expecting Z or exactly nine digits will not. For ordering, sort by ULID rather than by timestamp — it is monotonic by construction and immune to precision differences.

Pagination — four shapes

GET /api/v1/baas/accounts?page=1&page_size=100

{
  "items":     [ ... ],
  "total":     412,
  "page":      1,
  "page_size": 100
}

page is 1-indexed. Parameter names are not uniform either — most endpoints take page/page_size, some take limit/offset, and a few accept no paging parameters while still returning a page_size key. A defensive accessor costs one line:

def rows(body):
    if isinstance(body, list):
        return body
    for key in ("items", "clients", "results", "data"):
        if isinstance(body.get(key), list):
            return body[key]
    raise ValueError(f"unrecognised list shape: {sorted(body)[:8]}")

Errors — detail has three shapes

Errors are FastAPI-standard, which means detail is a string, a list, or an object depending on why the request failed. Type-check it before indexing.

{ "detail": "Account acct_01HV4Y... not found." }

{
  "detail": [
    { "type": "missing", "loc": ["body", "security"], "msg": "Field required" }
  ]
}

{
  "detail": {
    "message": "Order rejected by compliance checks.",
    "failed_checks": [
      { "check": "account_active", "reason": "Account ... is PENDING; must be ACTIVE." }
    ]
  }
}

d = response.json()["detail"]
if   isinstance(d, str):  reason = d
elif isinstance(d, list): reason = "; ".join(e["msg"] for e in d)
else:                     reason = d.get("message", str(d))

Rate limits

Idempotency

Idempotency support is per-endpoint, not platform-wide. There is no global Idempotency-Key header. Where it exists it is an explicit field in the request body. The safe general pattern: capture the ids the API returns, and have your retry logic check for existence before re-posting.

Versioning

Every path is under /v1. There is no /v2 and no deprecation in flight. Additive changes — new response fields, new optional request fields — ship inside v1 without notice, so your client must ignore unknown fields rather than failing to deserialise them. Breaking changes get a new version prefix.

Positions are derived, not stored

One architectural fact that changes how to read the API: positions and balances are folded from an immutable transaction ledger rather than held as mutable rows. The ledger is append-only — corrections are new entries, never edits, enforced at the database level rather than by convention. A position that looks wrong is a symptom; the ledger is the source of truth, and it is queryable.