Specification v0.1 (draft)

Status: draft. Published 2026-11-11 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 in v0.1.

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.
• 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 are opaque strings. intent_id and client_order_id are idempotency keys.
• Fail closed. When a required input is missing, stale or ambiguous, the answer is a refusal with a code, never a default.

Two version numbers

• The specification version (this document) is v0.1. It will move to v0.2 and so on while the protocol is in draft.
• The decision payload version is the v field inside every signed decision. The current value is 2. Adding a signed field, or changing the meaning of one, is a payload version bump. See Decision and signing.