Read one escrow

Retrieve one escrow, its current balances, deadlines, available actions and last reconciled chain state.

GET /escrow/{escrowId}

Read one escrow

cURL

curl --request GET \
  --url https://api.example.com/escrow/{escrowId} \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "<string>",
  "status": "draft",
  "availableActions": [
    "approve"
  ],
  "sender": {
    "clientId": "<string>"
  },
  "receiver": {
    "clientId": "<string>"
  },
  "token": "<string>",
  "maxAmount": "500.00",
  "authorizedAmount": "500.00",
  "capturableAmount": "500.00",
  "refundableAmount": "500.00",
  "windows": {
    "approveBy": "2023-11-07T05:31:56Z",
    "holdUntil": "2023-11-07T05:31:56Z",
    "refundableUntil": "2023-11-07T05:31:56Z"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "action": {
    "action": "approve",
    "idempotencyKey": "<string>",
    "status": "awaitingSignature",
    "amount": "500.00",
    "feeBps": 123,
    "transactionHash": "<string>",
    "approval": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "payload": "<string>",
      "expiresAt": "2023-11-07T05:31:56Z"
    }
  },
  "consistent": true
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Hevn-Account · string | null

The client account to act for, as a cl_… id. Omit it to act as yourself.

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

x-api-key · string | null

Path Parameters

escrowId · string · required

Pattern: ^(?:esc_)?[A-Za-z0-9._:\-]{1,216}$

Response

200

application/json

Successful Response

id · string · required

Stable public identifier for this escrow.

status · enum<string> · required

Current public lifecycle status of the escrow.

Available options: draft, authorized, charged, partiallyCaptured, captured, voided, reclaimed, partiallyRefunded, refunded

availableActions · enum<string>[] · required

Actions permitted by current state and deadlines.

Available options: approve, authorize, charge, capture, reject, void, reclaim, refund

sender · EscrowPartyView · object · required

Account sending or authorizing escrow funds.

Show child attributes

receiver · EscrowPartyView · object · required

Account entitled to captured escrow funds.

Show child attributes

token · string · required

Digital asset held in escrow.

maxAmount · string · required

Maximum token amount that may be authorized.

Example:

"500.00"

authorizedAmount · string · required

Token amount currently authorized for capture.

Example:

"500.00"

capturableAmount · string · required

Token amount that may currently be captured.

Example:

"500.00"

refundableAmount · string · required

Token amount that may currently be refunded.

Example:

"500.00"

windows · EscrowWindowsView · object · required

Approval, holding and refund deadlines.

Show child attributes

createdAt · string<date-time> · required

UTC timestamp when the escrow was created.

updatedAt · string<date-time> · required

UTC timestamp when the escrow was last updated.

action · EscrowActionView · object | null

Latest prepared or submitted escrow action.

Show child attributes

consistent · boolean | null

Whether persisted state matches the latest chain state.