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

# POST /irl/bind-execution

`POST /irl/bind-execution`

## 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/bind-execution`
- Auth: HTTP bearer

## Request body

- BindExecutionRequest: Request body for POST /irl/bind-execution. Called by the agent after receiving the exchange confirmation.
  - `asset` string, nullable: Asset actually traded (for mismatch detection).
  - `exchange_tx_id` string, required
  - `executed_quantity` number, double, nullable: Quantity actually executed (for tolerance check).
  - `executed_side` string, nullable: Trade direction as reported by the exchange: "Long" or "Short". Optional — if provided, verified against the authorized intent to detect side mismatches (e.g. Long authorized but Short executed). Omit if the exchange does not return direction in the fill report.
  - `execution_price` number, double, nullable: Execution price at the exchange (for forensic PnL correlation).
  - `execution_status` ExecutionStatus, required (unresolved $ref)
  - `execution_time_ms` integer, nullable: Unix milliseconds of the actual exchange fill. Optional — if provided, stored as execution_time for accurate PnL timestamps. Defaults to IRL wall clock at bind time if not supplied.
  - `trace_id` string, uuid, required

## Response `200`

Bound — final_proof computed

- BindExecutionResult: The result of binding a reasoning trace to an exchange execution.
  - `divergence_reason` string, nullable: Non-None when verification_status is Divergent — explains what differed.
  - `execution_status` string, required
  - `execution_time` string, date-time, required
  - `final_proof` string, required: SHA-256(reasoning_hash || "||" || exchange_tx_id). This is the terminal proof that closes the chain: Agent Reasoning → IRL Snapshot → Exchange Order
  - `trace_id` string, uuid, required
  - `verification_status` 'Pending' | 'Matched' | 'Divergent' | 'Orphan' | 'Expired' | 'Mismatch', required: Full lifecycle of a reasoning trace — whitepaper v3 §11.2.

## Other responses

- `404`: Trace not found
- `409`: Trace already bound
- `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)