Skip to main content

​
Execute a Business Transaction

POST /execute
Implemented in packages/api/src/routes/execute.ts. The route validates businessTransactionId, then delegates to application.execute(req.body) — ExecutionTrustApplication.execute in packages/runtime/src/ExecutionTrustApplication.ts.
A single call to POST /execute runs the entire pipeline synchronously: accept the Business Transaction → execute it through the Runtime → generate a Verification → generate a Receipt → return the resulting Execution Trust Record. See ExecutionTrustApplication.execute for the exact sequence.

​
Request body

The body is a full BusinessTransaction: 
curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "businessTransactionId": "b6f1c8de-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "metadata": {
      "businessTransactionId": "b6f1c8de-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "correlationId": "b6f1c8de-1111-4c3d-8e9f-0a1b2c3d4e5f",
      "createdBy": "integration-test",
      "createdAt": "2026-07-01T00:00:00.000Z"
    },
    "authority": {
      "authorityId": "b6f1c8de-2222-4c3d-8e9f-0a1b2c3d4e5f",
      "authorityType": "USER",
      "principalId": "integration-test",
      "displayName": "Integration Test",
      "issuedAt": "2026-07-01T00:00:00.000Z"
    },
    "authorization": {
      "authorizationId": "b6f1c8de-3333-4c3d-8e9f-0a1b2c3d4e5f",
      "authorityId": "b6f1c8de-2222-4c3d-8e9f-0a1b2c3d4e5f",
      "purpose": "Integration Test",
      "authorizedAt": "2026-07-01T00:00:00.000Z"
    },
    "intent": {
      "intentId": "b6f1c8de-4444-4c3d-8e9f-0a1b2c3d4e5f",
      "authorizationId": "b6f1c8de-3333-4c3d-8e9f-0a1b2c3d4e5f",
      "action": "PAY_VENDOR",
      "resource": "BusinessTransaction",
      "issuedAt": "2026-07-01T00:00:00.000Z"
    },
    "policy": { "name": "vendor-payment", "version": "1.0.0" },
    "signals": { "amount": 1000, "vendorVerified": true, "paymentApproved": true },
    "status": "SUBMITTED",
    "createdAt": "2026-07-01T00:00:00.000Z"
  }'
businessTransactionId must match a UUID (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i, per the regex in execute.ts). Any other value — including the short IDs used in some examples throughout this documentation, like txn-001 — is rejected with 400 before the request reaches the Runtime.

​
Response 200

The complete ExecutionTrustRecord, including the appended execution, verification, and receipt.

​
Response 400

{ "error": "businessTransactionId must be a valid UUID." }

​
SDK equivalents

const trustRecord = await client.execute(transaction);
See ExecutionApi in the TypeScript SDK — note it also exposes health(), mapped to GET /health, alongside execute().

Execution

The concept this endpoint produces.

Execution Lifecycle

The full accept → execute → verify → receipt sequence.

Error Model

How failures during any stage of this pipeline are reported.

Basic Execution Guide

A walkthrough of this endpoint end to end.