HEhevn-inc
escrow

Open an escrow and return the payer's approval

Changed on

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

Request

Headers

X-Hevn-Accountstring nullable

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

Example:cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41
Idempotency-Keystring nullable

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

Request body

senderClientIdstring required

Account funding the escrow.

receiverClientIdstring required

Account entitled to receive captured funds.

tokenstring required

Digital asset held in escrow.

maxAmountstring required

Maximum token amount that may be authorized.

approveWithinstring

Time allowed for the sender to approve funding.

holdForstring

Time captured funds remain held after approval.

refundableForstring

Time during which a refund remains available.

feeBpsinteger

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

referenceobject

Caller reference stored with the escrow.

descriptionstring nullable

Off-chain escrow description.

completionConditionsstring nullable

Off-chain conditions reviewed before capture.

Example request

{
  "senderClientId": "cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "receiverClientId": "cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "token": "USDC",
  "maxAmount": "500.00",
  "approveWithin": "14d",
  "holdFor": "14d",
  "refundableFor": "14d"
}

Response

OK

idstring required

Stable public identifier for this escrow.

status'draft' | 'authorized' | 'charged' | 'partiallyCaptured' | 'captured' | 'voided' | 'reclaimed' | 'partiallyRefunded' | 'refunded' required
availableActionsEscrowAction[] required

Actions permitted by current state and deadlines.

onchainEscrowUrlstring required

Block explorer URL for the shared escrow contract.

descriptionstring nullable

Off-chain escrow description.

completionConditionsstring nullable

Off-chain conditions reviewed before capture.

tokenstring required

Digital asset held in escrow.

maxAmountstring required

Maximum token amount that may be authorized.

authorizedAmountstring required

Token amount currently authorized for capture.

capturableAmountstring required

Token amount that may currently be captured.

refundableAmountstring required

Token amount that may currently be refunded.

consistentboolean nullable

Whether persisted state matches the latest chain state.

createdAtstring date-time required

UTC timestamp when the escrow was created.

updatedAtstring date-time required

UTC timestamp when the escrow was last updated.

Example response

{
  "maxAmount": "500.00",
  "authorizedAmount": "500.00",
  "capturableAmount": "500.00",
  "refundableAmount": "500.00",
  "action": {
    "amount": "500.00"
  }
}

Changes

  • 299a3aa6f521Revision changes
    • warning

      added the new verification_not_applicable enum value to the / response property for the response status

    • info

      removed the phone_required enum value from the / response property for the response status

    • info

      removed the rail_requirements_unmet enum value from the / response property for the response status

  • a02795de2d2bRevision changes
    • warning

      deleted the header request parameter x-api-key

    • warning

      added the new client_already_linked enum value to the / response property for the response status

    • warning

      added the new kyb_documents_processing enum value to the / response property for the response status

    • warning

      added the new link_code_expired enum value to the / response property for the response status

    • warning

      added the new link_code_invalid enum value to the / response property for the response status

    • warning

      added the new payout_not_awaiting_signature enum value to the / response property for the response status

    • warning

      added the new redirect_uri_not_allowed enum value to the / response property for the response status

    • warning

      added the new sandbox_amount_limit_exceeded enum value to the / response property for the response status

    • warning

      added the new sandbox_faucet_balance_too_high enum value to the / response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      removed the client_policy_not_enabled enum value from the / response property for the response status

    • info

      removed the client_request_conflict enum value from the / response property for the response status

    • info

      removed the email_in_use enum value from the / response property for the response status

    • info

      removed the integrator_inactive enum value from the / response property for the response status

    • info

      removed the name_in_use enum value from the / response property for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status