Conventions

Cross-cutting wire conventions that hold across all three APIs. Anything product-specific lives in that product's reference.

Envelopes

Two envelope styles exist — know which API you're talking to:

APIs	Success	Error
Photon, Meadow	{"success": true, "data": …, "timestamp": "…"}	{"success": false, "error": {code, message, category, details?, traceId}, "timestamp"}
Vector	{"code": 0, "data": …, "message": "success"}	{"code": <http status>, "message": "…", "data": null}

Photon has two deliberate exceptions that return bare (un-enveloped) bodies: Health and Register webhooks.

Identifiers

Transaction, quote, and order ids are 24 hexadecimal characters (68fa3450539a3c9d28bbca33) — string-typed, time-prefixed so they sort roughly by creation. Treat them as opaque.

Timestamps

RFC 3339 UTC with exactly millisecond precision and a literal Z: 2026-07-29T14:31:16.309Z. Quote expiries in Meadow (expiresAt) are the exception: Unix seconds as an integer.

Amounts

Token amounts, shares, wei values, and balances are base-10 integer strings in the asset's smallest unit — "25000000" is 25 USDC, "1" is one wei. Never floats, never hex. USD figures (costUSD, feeUsd, estimatedCostUSD) are the one deliberate exception: JSON numbers.

Chain ids

Chain ids are unsigned 64-bit integers serialized as JSON numbers. EVM chains use their standard ids; non-EVM chains are addressed by platform-assigned numeric ids (Solana devnet is 10100001).

Warning

Some ids exceed 2^53 — Starknet's is 23448594291968336 — which JavaScript's Number silently corrupts to …334. Parse chain ids with BigInt-safe handling if you touch non-EVM ids. The float-mangled Starknet alias is accepted on input as a courtesy, but emit the canonical value.

Status vocabularies

Flow	States
Photon relay	NOT_PICKED_UP → PENDING → EXECUTED \| FAILED \| NEEDS_TO_BE_RETRIED
Vector cross-chain /status	pending → src_confirmed → completed \| failed
Vector /gasless/status	pending → submitted → executed \| failed
Meadow order	relaying → confirmed \| failed

Statuses are exact strings — match them case-sensitively.

Booleans in query strings

GET endpoints that take flags (e.g. Get transaction status's includeReceipt) expect the strings "true" or "1" — a bare boolean in a query string has no meaning in HTTP.

Error codes

The stable error table — AUTH_001–RESOURCE_003, plus PAYMENT_REQUIRED — is shared by Photon and Meadow and documented once: Error codes. Vector's numeric envelope carries its HTTP status instead.