A handful of conventions the entire API follows. Internalize these once
and every response stops surprising you.
Amounts: micro-USDC as strings
Every USDC amount in the API is in micro-USDC (µUSDC).
Stored as BigInt, returned as decimal strings in JSON:
Why strings: JSON numbers are double-precision floats — they lose
precision above 2⁵³. A high-throughput operator running for a month
can blow past that comfortably. Strings keep the wire format honest.
To display: divide by 1_000_000. To do math: parse to BigInt in your
language of choice and stay there until you’re rendering to a human.
Factors: basis points
Pricing factors and fee splits are in basis points (bps). 10000
is 1.0×. 1500 is 15%. Same integer-arithmetic discipline as the
amounts — no float drift in the settlement math.
platformFeeBps is the canonical wire form; the human-readable
supplyFactor/demandFactor floats are convenience output only. If
you ever need to reproduce the math, divide bps by 10000.
Consistency: ZedTokens
The authorization graph is in SpiceDB (Zanzibar). Writes are eventually
consistent on its log. To avoid the “I just created a workspace but
listing its keys says I don’t have access” race, the API returns a
ZedToken on every authz-relevant write — surfaced in the response
body as consistencyToken and in the X-Lx-Consistency-Token
response header.
Echo it back on the next call:
You don’t have to echo it — without it, SpiceDB defaults to fully
consistent reads (slower, always correct). The token is the
read-your-writes hint.
The token is opaque base64. Don’t try to parse it; just pass it
through.
Auth: two transports, one principal
The guard dispatches on which one it sees: Bearer lxxn_* →
sha256-keyed API-key lookup; lx_session cookie → constant-time
HMAC verify. See Authentication.
API-key endpoints declare a required scope (or set of scopes). When a
list is declared, the caller passes if their key holds any one of
them. Surfaced as INSUFFICIENT_SCOPE (403) with the missing scope
list quoted in the message.
Wallet-session callers always bypass scope. Their authority is workspace
membership in SpiceDB.
Response envelope
Success:
Error:
The code is the stable machine-readable handle — branch on it. The
detail field carries operation-specific context (which session,
which scope, which state) for diagnostics.
See Errors for the full catalog.
Geography
Lat/lng are passed as JSON numbers in WGS84 (EPSG:4326), the GPS
standard. Stored server-side as PostGIS geography(Point, 4326).
Geofence radii are in meters.
Time
ISO-8601 UTC strings everywhere outbound. The API accepts the same
format inbound. Durations are seconds. 
