---
title: "POST /irl/authorize"
method: POST
path: "/irl/authorize"
tags: ["Core"]
---

# POST /irl/authorize

`POST /irl/authorize`

## Request

- Base URL: `https://irl.macropulse.live` (the document declares no server; this is the origin it was published from)
- URL: `https://irl.macropulse.live/irl/authorize`
- Auth: HTTP bearer

## Request body

- AuthorizeRequest: The request body sent by an agent to POST /irl/authorize.
  - `action` TradeAction, required (unresolved $ref)
  - `agent_id` string, uuid, required: Registered agent identity (UUID from POST /irl/agents).
  - `agent_valid_time` integer, required: Unix ms: the timestamp of the MTA regime the agent used.
  - `asset` string, required
  - `client_order_id` string, required
  - `feature_schema_id` string, required
  - `heartbeat` SignedHeartbeat: A signed pulse from MacroPulse, broadcast every ~100ms. Acts as an anti-replay anchor: proves the agent used a fresh, authentic regime. §9.2: signature is Ed25519 over (seq_id || timestamp || regime_id || mta_ref)
    - `mta_ref` string: Hex-encoded SHA-256 of the current MTA broadcast — binds heartbeat to a specific MTA state. Must match `MtaState.hash` for the regime the agent is acting on.
    - `regime_id` integer, required: The regime ID active at broadcast time (must match MTA response).
    - `sequence_id` integer, required: Monotonically increasing counter. Ensures no replay.
    - `signature` string, binary, required: Ed25519 signature over: seq_id_be || timestamp_ms_be || regime_id || mta_ref_bytes Signed by the MTA operator's private key. Verified against Config.mta_pubkey.
    - `timestamp_ms` integer, required: Unix ms when MacroPulse broadcast this heartbeat.
  - `hyperparameter_checksum` string, required: Checksum of hyperparameters — 4th component of L_t fingerprint.
  - `limit_price` number, double, nullable
  - `model_hash_hex` string, required: Hex-encoded SHA-256 of the running model version + config — verified against MAR.
  - `model_id` string, required
  - `mta_ref` string, nullable: Layer 2 v2: regime reference from `GET /irl/regime` (replaces the client-carried heartbeat when LAYER2_MODE is v2 or both).
  - `multiplier` number, double: Contract multiplier. Defaults to 1.0 if not provided.
  - `notional` number, double, required
  - `notional_currency` string: ISO 4217 currency of the notional. Defaults to "USD" if not provided.
  - `order_type` OrderType, required (unresolved $ref)
  - `parent_trace_id` string, uuid, nullable: Multi-agent linking: the trace_id of the orchestrator decision that triggered this sub-agent call. Forms a causal DAG for full lineage audits.
  - `prompt_version` string, required
  - `quantity` number, double, required
  - `reduce_only` boolean: When true, this order is reducing an existing position (not opening a new one). The `allowed_sides` regime constraint is bypassed — a trader must be able to exit positions even during a kill-switch regime. Notional cap still applies. The agent asserts reduce-only intent; IRL seals and audits the claim.
  - `regulatory` RegulatoryBlock: Optional regulatory metadata — included when the agent operates under a reporting regime that requires structured fields in the audit trace. All fields are optional. The block itself is absent (`None`) when no regulatory context is provided by the agent. MiFID II (EU): algorithmic trading identifier + decision-maker identity. CFTC (US): Commodity Trading Advisor Code + special account code. SEC/FINRA: optional order-tracking reference number (CAT NMS). IRL seals and persists whatever the agent supplies — it does not validate against any external regulatory schema. Compliance teams are responsible for verifying that the values satisfy their specific reporting obligations.
    - `cat_order_id` string, nullable: SEC CAT NMS: Consolidated Audit Trail order-tracking reference number.
    - `cftc_account_type` string, nullable: CFTC: special account type designator (e.g. "H" = hedge, "S" = speculator).
    - `cftc_cti_code` string, nullable: CFTC: Commodity Trading Advisor (CTA) code for the account.
    - `jurisdiction` string, nullable: Free-form jurisdiction tag (e.g. "EU", "US", "UK", "APAC"). Allows downstream compliance tooling to route the trace for the right rulebook.
    - `mifid_algo_id` string, nullable: MiFID II Annex I Table 2: algorithm identifier assigned by the firm. Required for algorithmic orders under Art. 17 of MiFID II.
    - `mifid_decision_maker` string, nullable: MiFID II: identifier of the person or system that made the investment decision.
  - `stop_price` number, double, nullable
  - `venue_id` string, required

## Response `200`

Authorized — reasoning_hash issued

- AuthorizeResponse: Response for POST /irl/authorize.
  - `authorized` boolean, required
  - `reasoning_hash` string, required
  - `shadow_blocked` boolean, required
  - `trace_id` string, uuid, required

## Other responses

- `403`: Policy violation or mTLS CN mismatch
- `422`: Validation error

---

[API](https://skmtc.dev/macropulse/apis/irl-engine.md) · [All operations](https://skmtc.dev/macropulse/apis/irl-engine/llms.txt) · [OpenAPI document](https://skmtc.dev/macropulse/apis/irl-engine/revisions/5226e22ddd17?raw)