Escrow actions

Five actions you send, one resource. POST /dapi/v1/escrow/{escrowId}/actions prepares one and returns a payload to sign; POST /dapi/v1/escrow/{escrowId}/actions/{idempotencyKey}/confirm submits the signature. This page is the matrix.

The matrix

Action	`amount`	`feeBps`	Legal when	Leaves the deal	Wallet it signs on
`authorize`	required	ignored	before `approveBy`, nothing collected yet, `0 < amount ≤ maxAmount`	`authorized`	yours
`charge`	required	up to the deal’s ceiling	before `approveBy`, nothing collected yet, `0 < amount ≤ maxAmount`	`charged`	yours
`capture`	required	up to the deal’s ceiling	before `holdUntil`, `0 < amount ≤ capturableAmount`, repeatable	`partiallyCaptured`, then `captured`	yours
`void`	refused	ignored	any time while `capturableAmount > 0`	`voided`	yours
`refund`	required	ignored	before `refundableUntil`, `0 < amount ≤ refundableAmount`, repeatable	`partiallyRefunded`, then `refunded`	yours

Two more names can appear in availableActions and are not verbs you send. approve is prepared by POST /dapi/v1/escrow and is the buyer’s to sign with their own key. reclaim is the buyer’s own way to take an uncaptured hold back after holdUntil. Sending either as action answers 422 validation_failed. Sending an amount with void answers 409 amount_not_allowed; omitting it on the four that need it answers 422 validation_failed. charge is authorize and capture in one on-chain action — the money goes straight to the seller with no hold in between. Use it when there is nothing to wait for.

Preparing an action

Request — POST /dapi/v1/escrow/esc_5Qb4e17c9d/actions, Idempotency-Key: order-A-1187-capture

{ "action": "capture", "amount": "40.00", "feeBps": 250 }

201 for a new action, 200 with Idempotency-Replayed: true when the key replays one. A replay returns the same record — with its approval if that is still open, without it once the action was submitted. The same key with a different body answers 409 idempotency_key_reused.

Response — 201

{
  "deal": { "id": "esc_5Qb4e17c9d", "status": "authorized",
            "capturableAmount": "100.000000", "refundableAmount": "0.000000",
            "availableActions": ["capture", "void"] },
  "action": { "action": "capture", "idempotencyKey": "order-A-1187-capture",
              "status": "awaitingSignature", "amount": "40.000000", "feeBps": 250,
              "approval": { "id": "b1d0…", "payload": "eyJ…",
                            "expiresAt": "2026-09-17T10:31:02Z" } }
}

The idempotency key you sent is the action’s address. Send no key and HEVN derives one, echoes it as action.idempotencyKey, and that derived value works in the confirm URL exactly the same way. Either way, a lost prepare response costs you nothing: you already know where to confirm.

Confirming an action

Sign the decoded approval.payload bytes — never the base64 string, never a re-serialized JSON object.

import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec


def sign_bytes(key, message: bytes) -> str:
    """base64(DER ECDSA P-256 / SHA-256) over exactly these bytes."""
    return base64.b64encode(key.sign(message, ec.ECDSA(hashes.SHA256()))).decode()


def sign_payload(key, payload_b64: str) -> str:
    return sign_bytes(key, base64.b64decode(payload_b64))

import { sign } from "node:crypto";

export function signBytes(key, message) {
  return sign("sha256", message, { key, dsaEncoding: "der" }).toString("base64");
}

export function signPayload(key, payloadB64) {
  return signBytes(key, Buffer.from(payloadB64, "base64"));
}

func SignBytes(key *ecdsa.PrivateKey, message []byte) (string, error) {
	digest := sha256.Sum256(message)
	der, err := ecdsa.SignASN1(rand.Reader, key, digest[:])
	if err != nil {
		return "", err
	}
	return base64.StdEncoding.EncodeToString(der), nil
}

func SignPayload(key *ecdsa.PrivateKey, payloadB64 string) (string, error) {
	message, err := base64.StdEncoding.DecodeString(payloadB64)
	if err != nil {
		return "", err
	}
	return SignBytes(key, message)
}

Request — POST /dapi/v1/escrow/esc_5Qb4e17c9d/actions/order-A-1187-capture/confirm

{ "signature": "MEUCIQDk3f8Zc0xq2w1Yv7pB9nH4mJ6sR2tL5uD8aE0cQ1oXgAIg…" }

publicKey is optional and only skips a scan of your registered keys. HEVN verifies the signature locally, against the payload it stored, before it consumes the approval — a wrong signature costs nothing but the call. HEVN re-checks the developer key behind the session immediately before it co-signs: a key deleted between prepare and confirm, or a confirm sent from an IP outside the key’s allowlist, answers 403 and signs nothing. The prepared action is untouched, so a confirm from an allowlisted host still works.

Answer	Meaning	What to do
`200`, action `confirmed`	Mined. The body carries the projected deal and the `events` it produced.	Done.
`200`, action `reverted`	Mined, but the contract rejected it.	Read the deal; nothing moved. Prepare again with a new key.
`202`, `pollUrl`	With the bundler, no receipt yet.	`pollUrl` is the deal read, `GET /dapi/v1/escrow/{escrowId}`; `POST /dapi/v1/escrow/{escrowId}/sync` is the one that reconciles against the chain. Sync until the action settles.
`400 signature_invalid`	The signature does not verify.	The approval is untouched. Sign the decoded payload again.
`403 forbidden`	The developer key was deleted, or the confirm left an IP outside its allowlist.	Nothing was signed. Use a key that covers this host.
`403 account_not_controlled`	The action would sign on a wallet your key does not control — the buyer’s.	Nothing was signed. Only operator actions are yours to confirm.
`410 approval_expired`	The 60-second approval closed, or the action has no open approval left.	Prepare the action again with the same key; you get a fresh approval on the same record.
`409 approval_consumed`	That approval already signed something.	Prepare again with the same key, then read the deal before you sign anything else.
`409 action_in_flight`	Another action of yours is still on chain.	Sync this deal, then retry. The refusal carries no `details`; the deal to sync is the one you are acting on.
`409 escrow_state_changed`	The deal moved since prepare — nothing capturable, or the payment was already collected.	Re-read the deal and pick from `availableActions`.
`503 bundler_rejected`, `503 bundler_unavailable`	Chain infrastructure.	Confirm again with backoff.

def confirm_action(hevn, escrow_id, key, payload, signing_key):
    signature = signing_key.sign_payload(payload)
    receipt = hevn.post(f"/escrow/{escrow_id}/actions/{key}/confirm", {"signature": signature})
    if receipt["action"]["status"] in ("confirmed", "reverted"):
        return receipt
    return poll_until(
        lambda: hevn.post(f"/escrow/{escrow_id}/sync"),
        lambda deal: deal["action"]["status"] not in ("signing", "submitted"),
        first=15.0,
    )

export async function confirmAction(hevn, escrowId, key, payload, signingKey) {
  const signature = signingKey.signPayload(payload);
  const receipt = await hevn.post(`/escrow/${escrowId}/actions/${key}/confirm`, { signature });
  if (["confirmed", "reverted"].includes(receipt.action.status)) return receipt;
  return pollUntil(
    () => hevn.post(`/escrow/${escrowId}/sync`),
    (deal) => !["signing", "submitted"].includes(deal.action.status),
    { first: 15_000 },
  );
}

var pending = map[string]bool{"signing": true, "submitted": true}

func ConfirmAction(c *hevn.Client, escrowID, idemKey, payload string, key *hevn.Key) (hevn.Payload, error) {
	signature, err := key.SignPayload(payload)
	if err != nil {
		return nil, err
	}
	receipt, err := c.Post("/escrow/"+escrowID+"/actions/"+idemKey+"/confirm",
		hevn.Body{"signature": signature})
	if err != nil || !pending[receipt.Str("action.status")] {
		return receipt, err
	}
	return hevn.PollUntil(
		func() (hevn.Payload, error) { return c.Post("/escrow/"+escrowID+"/sync", nil) },
		func(deal hevn.Payload) bool { return !pending[deal.Str("action.status")] },
		2*time.Minute,
	)
}

One action in flight

A signing wallet runs one on-chain action at a time — across every deal it signs for, not just this one. While one of yours is signing or submitted, the next prepare or confirm answers 409 action_in_flight. The refusal names no deal, so a worker that drives many deals has to know which one it left in flight: serialise your actions per signing wallet and keep the in-flight deal id on your side, then POST /dapi/v1/escrow/{escrowId}/sync it before retrying.

Statuses

The deal’s status is a label for the last thing that landed. Decide with availableActions, capturableAmount and refundableAmount.

Deal status	Meaning
`draft`	Created. Nothing held. The buyer’s approval does not change this.
`authorized`	The on-chain hold is in the contract. `capturableAmount` is positive.
`charged`	Held and paid out in one action. Only a refund moves it back.
`partiallyCaptured`	Part of the hold reached the seller, the rest is still capturable.
`captured`	Nothing is capturable any more.
`voided`	The hold went back to the buyer.
`reclaimed`	The buyer took the hold back after `holdUntil`.
`partiallyRefunded` / `refunded`	You sent money back out of your own wallet.

Action status	Meaning	What to do
`awaitingSignature`	Prepared, approval open	Sign and confirm within 60 seconds
`signing`	Confirm in progress	Wait. Do not prepare again
`submitted`	With the bundler, no receipt	Sync, no more than every 15 seconds
`confirmed`	Mined and projected	Done
`reverted`	Mined, the call reverted	Read the deal, prepare again with a new key
`failed`	Never reached the bundler	Prepare again with the same key
`dropped`	No receipt within the timeout	Keep syncing: it can still confirm for up to 24 hours
`superseded`	A later prepare replaced it	Ignore

Reads

GET /dapi/v1/escrow/{escrowId} returns one deal with its last action. GET /dapi/v1/escrow lists the deals you operate, newest first, cursor-paged:

curl "$HEVN_API/escrow?status=authorized&status=partiallyCaptured&limit=50" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN"

open_deals = hevn.get("/escrow?status=authorized&status=partiallyCaptured&limit=50")["items"]

const { items: openDeals } =
  await hevn.get("/escrow?status=authorized&status=partiallyCaptured&limit=50");

page, err := api.Get("/escrow?status=authorized&status=partiallyCaptured&limit=50")
openDeals := page.List("items")

status repeats, so it goes in the path rather than the client’s parameter map, which holds one value per name. Filters are status, senderClientId and receiverClientId. The envelope is { "items": [...], "nextCursor": "…" }; pass nextCursor back as cursor until it is absent. A cursor from another query answers 400 invalid_cursor. POST /dapi/v1/escrow/{escrowId}/sync reconciles the deal against the chain and returns the same shape plus consistent. It reads the chain at most once every 15 seconds per deal; calls in between answer the stored projection, which is why polling it in a tight loop buys nothing. There is no separate action list: the deal read carries the last action, and every action is addressable by the key you chose.

Refusals

action_in_flight, escrow_state_changed and escrow_action_not_found are the three that change your control flow, and all three are handled above. The full registry, with every status code, is in Errors. One shape worth knowing: a closed window or an over-large amount arrives today as a bare 400 invalid_request — the contract-level reason (preApprovalExpiry has been reached, amount exceeds available amount) is logged on our side but not published, so message is the generic one and details is absent. Treat it exactly like window_closed and amount_out_of_range: re-read the deal and pick from availableActions, which is computed from the same windows and amounts.

Next: Sandbox

The same operations against an emulated partner on Base Sepolia.

Start here

Core concepts

Onboard a client

Move money

Escrow

Ship it

Reference

Escrow actions

The matrix

Preparing an action

Confirming an action

One action in flight

Statuses

Reads

Refusals

Next: Sandbox

​The matrix

​Preparing an action

​Confirming an action

​One action in flight

​Statuses

​Reads

​Refusals

Next: Sandbox

The matrix

Preparing an action

Confirming an action

One action in flight

Statuses

Reads

Refusals