Open an escrow and return the payer's approval

Create an escrow draft and return the payer’s approval that funds it. The payer signs it on its own wallet: a developer key cannot, and a payer that owns its wallet is refused with account_not_controlled until it can approve in the HEVN sign-in window. No on-chain action is submitted until it is signed.

POST /escrow

Open an escrow and return the payer's approval

cURL

curl --request POST \
  --url https://api.example.com/escrow \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "senderClientId": "cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "receiverClientId": "cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "token": "USDC",
  "maxAmount": "500.00"
}
'

200

{
  "id": "<string>",
  "status": "draft",
  "availableActions": [
    "approve"
  ],
  "sender": {
    "clientId": "<string>"
  },
  "receiver": {
    "clientId": "<string>"
  },
  "onchainEscrowUrl": "<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",
  "description": "<string>",
  "completionConditions": "<string>",
  "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"

Idempotency-Key · string | null

Your own key for this write, ^[A-Za-z0-9._:-]{1,128}$. A retry with the same key replays the first answer; the same key with a different request is refused.

Example:

"po-inv-2026-114"

Body

application/json

senderClientId · string · required

Account funding the escrow.

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

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

receiverClientId · string · required

Account entitled to receive captured funds.

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

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

token · string · required

Digital asset held in escrow.

Required string length: 1 - 16

Example:

"USDC"

maxAmount · string · required

Maximum token amount that may be authorized.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"500.00"

approveWithin · string · default: 1h

Time allowed for the sender to approve funding.

Pattern: ^\d{1,4}[smhd]$

Example:

"14d"

holdFor · string · default: 14d

Time captured funds remain held after approval.

Pattern: ^\d{1,4}[smhd]$

Example:

"14d"

refundableFor · string · default: 90d

Time during which a refund remains available.

Pattern: ^\d{1,4}[smhd]$

Example:

"14d"

feeBps · integer · default: 0

Variable fee in basis points; 100 basis points equals 1 percent.

Required range: 0 <= x <= 10000

reference · Reference · object

Caller reference stored with the escrow.

description · string | null

Off-chain escrow description.

Maximum string length: 2000

completionConditions · string | null

Off-chain conditions reviewed before capture.

Maximum string length: 10000

Response

200

application/json

OK

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

onchainEscrowUrl · string · required

Block explorer URL for the shared escrow contract.

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.

description · string | null

Off-chain escrow description.

completionConditions · string | null

Off-chain conditions reviewed before capture.

action · EscrowActionView · object | null

Latest prepared or submitted escrow action.

Show child attributes

consistent · boolean | null

Whether persisted state matches the latest chain state.