Specification v0.2 (draft)

Note

You are reading specification v0.2. The current draft is v0.4. Earlier: v0.1. See the changelog.

Status: draft. Published 2026-11-12 for feedback. 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 6 decimal places. qty, limit_price and reference_price MUST have at most 6 digits after the decimal point. A value with more is a 400 error (APEX_4011). It MUST NOT be rounded.
• 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.2.
• The decision payload version is the v field inside every signed decision. In v0.2 the current value is 2. Adding a signed field, or changing the meaning of one, is a payload version bump. See Decision and signing.