Specification v0.4 (draft)

Note

You are reading specification v0.4, the current draft. Earlier drafts: v0.3, v0.2, v0.1. See the changelog.

Status: draft. Published 2026-11-14 for feedback. v0.4 adds order forms beyond limit and market: stops, trailing stops, notional orders, brackets and other order groups, listed options and spreads, replace and option exercise. This version documents behaviour that exists in the reference implementation. Anything marked planned is defined in name only and is not implemented.

Scope

The specification defines:

• the Intent, Mandate, Decision, ExecutionReport and Evidence objects,
• how decisions are signed and verified,
• the order state machine,
• error codes,
• the venue adapter contract between an executor and a venue,
• bindings that carry these objects over a transport.

It does not define trading strategy, order routing between venues, fiat payments, or how a mandate is negotiated with the user. Mandate issuance is implementation-specific.

Conventions

The key words MUST, MUST NOT, SHOULD and MAY are used as described in RFC 2119.

• Money and quantities are decimal strings. "0.01", never 0.01. A JSON number in a money or quantity field MUST be rejected, so values never pass through a binary float.
• At most 9 decimal places. qty, limit_price and reference_price MUST have at most 9 digits after the decimal point. A value with more is a 400 error (APEX_4011). It MUST NOT be rounded. Finer precision is the venue’s: the instrument’s lot and tick, and the venue adapter’s own checks.
• Timestamps are RFC 3339 in UTC with a Z suffix.
• Canonical JSON is used for everything that is signed or hashed: object keys sorted, no insignificant whitespace, decimals as strings. Python’s json.dumps(obj, sort_keys=True, separators=(",", ":")) produces the same bytes.
• Identifiers. intent_id is the caller’s idempotency key. client_order_id is minted by the authorizer (co_ followed by 32 hex characters, 35 in all) and is never reused. It is the idempotency and reconciliation key at the venue.
• Fail closed. When a required input is missing, stale or ambiguous, the answer is a refusal with a code, never a default. An unsupported time in force or order type is refused before it is sent, never coerced into a supported value.

Two version numbers

• The specification version (this document) is v0.4.
• The decision payload version is the v field inside every signed decision. In v0.4 the current value is 4, which adds the signed asset_class and order terms. Versions 1 to 3 are still verified. Adding a signed field, or changing the meaning of one, is a payload version bump. See Decision and signing.