Settlements

Seal unsettled receipts into Merkle-anchored settlements and verify inclusion proofs — periodic chain-of-custody anchoring for the Aira audit trail.

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

Create Settlement

POST /api/v1/settlements
Authorization: Bearer aira_live_xxxxx

Admin only. Seals every unsettled receipt for the organization into a new Merkle settlement. If there are no unsettled receipts, the response is null (no-op). In production this is typically called by a scheduled task; the endpoint serves as a manual escape hatch.

Rate-limited to 5 requests per minute per organization.

Request Body

No request body required.

Example Request

curl -X POST https://api.airaproof.com/api/v1/settlements \
  -H "Authorization: Bearer aira_live_xxxxx"

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "org_uuid": "org_01J9A...",
  "period_start": "2026-06-01T00:00:00.000Z",
  "period_end": "2026-06-05T12:00:00.000Z",
  "receipt_count": 142,
  "merkle_root": "sha256:a1b2c3d4...",
  "settlement_hash": "sha256:e5f6a7b8...",
  "signature": "ed25519:base64url...",
  "signing_key_id": "aira-signing-key-v1",
  "timestamp_token": "base64...",
  "sealed_at": "2026-06-05T12:00:00.000Z",
  "request_id": "req_01J9E..."
}

Returns null with status 200 if there are no unsettled receipts.

List Settlements

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

Returns a paginated list of settlements for the organization.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (minimum 1)
`per_page`	integer	`20`	Results per page (1--100)

Example Request

curl https://api.airaproof.com/api/v1/settlements?page=1&per_page=20 \
  -H "Authorization: Bearer aira_live_xxxxx"

Response (200 OK)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "period_start": "2026-06-01T00:00:00.000Z",
      "period_end": "2026-06-05T12:00:00.000Z",
      "receipt_count": 142,
      "merkle_root": "sha256:a1b2c3d4...",
      "sealed_at": "2026-06-05T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 5,
    "has_more": false
  },
  "request_id": "req_01J9E..."
}

Get Settlement

GET /api/v1/settlements/{settlement_uuid}
Authorization: Bearer aira_live_xxxxx

Returns the full detail for a single settlement.

Path Parameters

Parameter	Type	Description
`settlement_uuid`	string (UUID)	The settlement ID

Example Request

curl https://api.airaproof.com/api/v1/settlements/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer aira_live_xxxxx"

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "org_uuid": "org_01J9A...",
  "period_start": "2026-06-01T00:00:00.000Z",
  "period_end": "2026-06-05T12:00:00.000Z",
  "receipt_count": 142,
  "merkle_root": "sha256:a1b2c3d4...",
  "settlement_hash": "sha256:e5f6a7b8...",
  "signature": "ed25519:base64url...",
  "signing_key_id": "aira-signing-key-v1",
  "timestamp_token": "base64...",
  "sealed_at": "2026-06-05T12:00:00.000Z",
  "request_id": "req_01J9E..."
}

Error Codes

Status	Code	Description
404	`NOT_FOUND`	Settlement does not exist

Get Settlement Receipts

GET /api/v1/settlements/{settlement_uuid}/receipts
Authorization: Bearer aira_live_xxxxx

Returns all receipts sealed into a given settlement.

Path Parameters

Parameter	Type	Description
`settlement_uuid`	string (UUID)	The settlement ID

Example Request

curl https://api.airaproof.com/api/v1/settlements/550e8400-e29b-41d4-a716-446655440000/receipts \
  -H "Authorization: Bearer aira_live_xxxxx"

Response (200 OK)

[
  {
    "receipt_uuid": "r_01J9B...",
    "action_uuid": "act_01J9B...",
    "action_type": "transaction",
    "agent_id": "procurement-agent",
    "payload_hash": "sha256:f0e1d2c3...",
    "created_at": "2026-06-04T10:30:00.000Z"
  }
]

Response Fields

Field	Type	Description
`receipt_uuid`	string	UUID of the receipt
`action_uuid`	string	UUID of the associated action
`action_type`	string	Type of the action (e.g. `transaction`, `decision`)
`agent_id`	string	ID of the agent that performed the action
`payload_hash`	string	SHA-256 hash of the receipt payload
`created_at`	string	ISO 8601 timestamp of receipt creation

Inclusion Proof

GET /api/v1/settlements/inclusion-proof/{receipt_uuid}
Authorization: Bearer aira_live_xxxxx

Returns the Merkle inclusion proof for a specific receipt within its settlement. This proof can be independently verified to confirm that the receipt was included in the settlement's Merkle tree.

Path Parameters

Parameter	Type	Description
`receipt_uuid`	string (UUID)	The receipt ID to look up

Example Request

curl https://api.airaproof.com/api/v1/settlements/inclusion-proof/r_01J9B... \
  -H "Authorization: Bearer aira_live_xxxxx"

Response (200 OK)

{
  "settlement_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "receipt_uuid": "r_01J9B...",
  "merkle_root": "sha256:a1b2c3d4...",
  "leaf_hash": "sha256:b2c3d4e5...",
  "index": 7,
  "leaf_count": 142,
  "siblings": [
    "sha256:c3d4e5f6...",
    "sha256:d4e5f6a7...",
    "sha256:e5f6a7b8..."
  ],
  "request_id": "req_01J9E..."
}

Response Fields

Field	Type	Description
`settlement_uuid`	string	UUID of the settlement containing this receipt
`receipt_uuid`	string	UUID of the receipt
`merkle_root`	string	Root hash of the settlement's Merkle tree
`leaf_hash`	string	Hash of this receipt's leaf in the tree
`index`	integer	Position of the leaf in the tree
`leaf_count`	integer	Total number of leaves in the tree
`siblings`	string[]	Sibling hashes needed to reconstruct the path to the root
`request_id`	string	Request ID for tracing

Settlements

On this page