Prepare an escrow action and return the payload to sign

Prepare an escrow action and return the immutable payload to sign. This request does not broadcast the action.

POST /escrow/{escrowId}/actions

Prepare an escrow action and return the payload to sign

cURL

curl --request POST \
  --url https://api.hevn.finance/dapi/v1/escrow/{escrowId}/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

200

{
  "deal": {
    "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
  },
  "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"
    }
  },
  "events": [
    {
      "name": "<string>",
      "transactionHash": "<string>",
      "blockNumber": 123,
      "amount": "500.00"
    }
  ],
  "pollUrl": "<string>"
}

Authorizations

Authorization · string · header · required

Platform access token from POST /auth/token, carrying the platform audience and the developer_key_id of the registration that minted it. It acts as your own account; name a client you created with X-Hevn-Account: cl_…. Every request re-checks that the registration is still active and that the caller's source IP is inside its allowlist. A token is valid only against the server that issued it, so sandbox tokens are refused in production and production tokens in the sandbox.

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

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"

Path Parameters

escrowId · string · required

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

Body

application/json

action · enum<string> · required

Escrow state transition to prepare.

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

amount · string | null

Token amount affected by this action, when required.

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

Example:

"500.00"

feeBps · integer · default: 0

Variable fee in basis points for charge or capture actions.

Required range: 0 <= x <= 10000

Response

200

application/json

OK

deal · EscrowView · object · required

Latest escrow state after processing the action.

Show child attributes

action · EscrowActionView · object · required

Prepared or submitted action.

Show child attributes

events · EscrowEventView · object[]

Observed on-chain events for this action.

Show child attributes

pollUrl · string | null

Relative API URL to poll while processing continues.