Escrow

Liability commitment ledger for AI agent operations — record, release, and dispute accountability commitments with cryptographic proof.

All endpoints require a Bearer token (Authorization: Bearer aira_live_xxxxx). Base URL: https://api.airaproof.com/api/v1

Create Escrow Account

POST /api/v1/escrow/accounts
Authorization: Bearer aira_live_xxxxx

Creates a new escrow account. Escrow accounts are accountability ledgers — they record liability commitments with cryptographic proof. All transactions are signed and notarized. No real funds are custodied by Aira; the escrow tracks your organization's recorded commitments.

Request Body

Field	Type	Required	Description
`purpose`	string	No	Purpose of the escrow account
`currency`	string	No	ISO 4217 currency code (default: `EUR`)
`agent_id`	string	No	Agent ID managing this escrow account
`counterparty_org_uuid`	string	No	Counterparty organization ID

Transaction Fields

Field	Type	Description
`name`	string	Counterparty name
`identifier`	string	External identifier (e.g. vendor ID, IBAN)
`type`	string	`individual` or `organization`

Example Request

curl -X POST https://api.airaproof.com/api/v1/escrow/accounts \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "purpose": "vendor_payment",
    "agent_id": "uuid",
    "counterparty": {
      "name": "Acme Supplies BV",
      "identifier": "NL91ABNA0417164300",
      "type": "organization"
    }
  }'

Response (201 Created)

{
  "account_uuid": "esc_01J9I...",
  "currency": "EUR",
  "purpose": "vendor_payment",
  "agent_id": "uuid",
  "counterparty": {
    "name": "Acme Supplies BV",
    "identifier": "NL91ABNA0417164300",
    "type": "organization"
  },
  "balance": "0.00",
  "status": "active",
  "created_at": "2026-03-24T10:00:00.000Z",
  "request_id": "req_01J9I..."
}

Error Codes

Status	Code	Description
400	`UNSUPPORTED_CURRENCY`	Currency not supported
404	`AGENT_NOT_FOUND`	Agent does not exist
422	`AGENT_DECOMMISSIONED`	Cannot create escrow for a decommissioned agent

List Escrow Accounts

GET /api/v1/escrow/accounts?page=1&per_page=20
Authorization: Bearer aira_live_xxxxx

Returns a paginated list of escrow accounts.

Response (200 OK)

{
  "accounts": [
    {
      "account_uuid": "esc_01J9I...",
      "currency": "EUR",
      "purpose": "vendor_payment",
      "agent_id": "uuid",
      "balance": "12500.00",
      "status": "active",
      "created_at": "2026-03-24T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 3
  }
}

Get Escrow Account

GET /api/v1/escrow/accounts/{account_uuid}
Authorization: Bearer aira_live_xxxxx

Returns full account detail including transaction history.

Response (200 OK)

{
  "account_uuid": "esc_01J9I...",
  "currency": "EUR",
  "purpose": "vendor_payment",
  "agent_id": "uuid",
  "counterparty": {
    "name": "Acme Supplies BV",
    "identifier": "NL91ABNA0417164300",
    "type": "organization"
  },
  "balance": "12500.00",
  "status": "active",
  "transactions": [
    {
      "transaction_id": "txn_01J9J...",
      "type": "deposit",
      "amount": "12500.00",
      "receipt_uuid": "rct_01J9J...",
      "created_at": "2026-03-24T11:00:00.000Z"
    }
  ],
  "created_at": "2026-03-24T10:00:00.000Z"
}

Deposit

POST /api/v1/escrow/accounts/{account_uuid}/deposit
Authorization: Bearer aira_live_xxxxx

Records a liability commitment. The commitment is cryptographically signed and notarized.

Request Body

Field	Type	Required	Description
`amount`	string	Yes	Commitment amount (decimal string)
`description`	string	No	Description of the commitment
`reference_action_uuid`	string	No	Reference to a notarized action

Example Request

curl -X POST https://api.airaproof.com/api/v1/escrow/accounts/esc_01J9I.../deposit \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "12500.00",
    "signature": "ed25519:base64url...",
    "reference": "INV-2026-0042"
  }'

Response (201 Created)

{
  "transaction_id": "txn_01J9J...",
  "account_uuid": "esc_01J9I...",
  "type": "deposit",
  "amount": "12500.00",
  "balance_after": "12500.00",
  "reference": "INV-2026-0042",
  "receipt": {
    "receipt_uuid": "rct_01J9J...",
    "payload_hash": "sha256:c3d4e5f6...",
    "signature": "ed25519:base64url...",
    "public_key_id": "aira-signing-key-v1",
    "timestamp": "2026-03-24T11:00:00.000Z"
  },
  "created_at": "2026-03-24T11:00:00.000Z"
}

Error Codes

Status	Code	Description
400	`INVALID_AMOUNT`	Amount must be positive
409	`ACCOUNT_FROZEN`	Account is frozen due to an active dispute

Release

POST /api/v1/escrow/accounts/{account_uuid}/release
Authorization: Bearer aira_live_xxxxx

Releases a liability commitment. The release is cryptographically signed and notarized.

Request Body

Field	Type	Required	Description
`amount`	string	Yes	Release amount (decimal string)
`description`	string	No	Description of the release
`reference_action_uuid`	string	No	Reference to a notarized action

Example Request

curl -X POST https://api.airaproof.com/api/v1/escrow/accounts/esc_01J9I.../release \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "12500.00",
    "signature": "ed25519:base64url...",
    "reference": "PO-2026-0042-final"
  }'

Response (200 OK)

{
  "transaction_id": "txn_01J9K...",
  "account_uuid": "esc_01J9I...",
  "type": "release",
  "amount": "12500.00",
  "fee": "125.00",
  "net_release": "12375.00",
  "balance_after": "0.00",
  "reference": "PO-2026-0042-final",
  "receipt": {
    "receipt_uuid": "rct_01J9K...",
    "payload_hash": "sha256:a7b8c9d0...",
    "signature": "ed25519:base64url...",
    "public_key_id": "aira-signing-key-v1",
    "timestamp": "2026-03-24T14:00:00.000Z"
  },
  "created_at": "2026-03-24T14:00:00.000Z"
}

Error Codes

Status	Code	Description
400	`INSUFFICIENT_BALANCE`	Release amount exceeds available balance
409	`ACCOUNT_FROZEN`	Account is frozen due to an active dispute

Dispute

POST /api/v1/escrow/accounts/{account_uuid}/dispute
Authorization: Bearer aira_live_xxxxx

Opens a dispute on an escrow account. This immediately freezes the account — no deposits or releases are allowed until the dispute is resolved. The dispute is cryptographically signed and notarized.

Request Body

Field	Type	Required	Description
`amount`	string	Yes	Disputed amount (decimal string)
`description`	string	Yes	Reason for the dispute
`reference_action_uuid`	string	No	Reference to a notarized action

Example Request

curl -X POST https://api.airaproof.com/api/v1/escrow/accounts/esc_01J9I.../dispute \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Goods not delivered as specified in PO-2026-0042",
    "signature": "ed25519:base64url...",
    "evidence_package_uuid": "pkg_01J9E..."
  }'

Response (200 OK)

{
  "dispute_id": "dsp_01J9L...",
  "account_uuid": "esc_01J9I...",
  "reason": "Goods not delivered as specified in PO-2026-0042",
  "status": "open",
  "account_status": "frozen",
  "evidence_package_uuid": "pkg_01J9E...",
  "receipt": {
    "receipt_uuid": "rct_01J9L...",
    "payload_hash": "sha256:f0e1d2c3...",
    "signature": "ed25519:base64url...",
    "public_key_id": "aira-signing-key-v1",
    "timestamp": "2026-03-24T15:00:00.000Z"
  },
  "opened_at": "2026-03-24T15:00:00.000Z",
  "opened_by": "user_01J9C..."
}

Error Codes

Status	Code	Description
400	`INVALID_SIGNATURE`	Signature verification failed
409	`DISPUTE_ALREADY_OPEN`	An active dispute already exists on this account
404	`EVIDENCE_NOT_FOUND`	Evidence package ID does not exist

On this page