> ## Documentation Index > Fetch the complete documentation index at: https://hevninc.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > HEVN has two products and they authorize money differently. Self-serve (the General tab): the person who owns the email holds the only key and signs for themselves. Whitelabel (the Whitelabel and REST API tabs): the integrator's backend holds a developer key, signs on behalf of client accounts it created, and HEVN co-signs. Never mix the two models in an answer. > Use HEVN's terms exactly. A rail is a bank route a client can request. A virtual account (bnk_) is an opened rail. Account details are what a payer needs in order to wire money, and arrive in a field named requisites. A client is an account the integrator created; the business behind it is the integrator's customer. A contact is a saved destination; a beneficiary is the party at the far end of a fiat payout. Every departure of money is a payout, to a bank account or to a wallet alike. > Never name a banking partner. Say 'a licensed banking partner'. > There are no published fee rates, spreads or minimums. Prices come from a quote on a specific payment; direct pricing questions to HEVN rather than inventing numbers. > The whitelabel API is at /dapi/v1 and takes a developer-key session plus an X-Hevn-Account header. The CLI uses an app API key in X-Api-Key. They are different credentials and neither works on the other surface. # Escrow > Lock one client's funds in an on-chain contract while another delivers: the states a deal passes through, the windows it lives in, and a marketplace order end to end. Escrow locks one client's funds in an on-chain contract while another delivers. The buyer's funds stay in the buyer's own wallet until you authorize a lock, they then sit in the escrow contract where neither party — and neither HEVN nor you — can spend them outside its rules, and they reach the seller only when you capture. ```mermaid theme={null} stateDiagram-v2 [*] --> draft: POST /dapi/v1/escrow draft --> authorized: authorize — the hold leaves the buyer's wallet draft --> charged: charge — hold and pay out in one action authorized --> partiallyCaptured: capture (part) partiallyCaptured --> captured: capture (rest) authorized --> captured: capture (all) authorized --> voided: void — the hold goes back to the buyer partiallyCaptured --> voided: void authorized --> reclaimed: reclaim — after holdUntil partiallyCaptured --> reclaimed: reclaim captured --> partiallyRefunded: refund (part) charged --> partiallyRefunded: refund (part) partiallyRefunded --> refunded: refund (rest) captured --> refunded: refund (all) charged --> refunded: refund (all) ``` A `voided` or `reclaimed` deal can still be refunded, if something was captured before the hold was released. Every transition is one `POST /dapi/v1/escrow/{escrowId}/actions` that you sign with your developer key. You are the **operator** of every deal you create; escrow never takes `X-Hevn-Account`, because the caller is always you. It is one of two self-scoped families — the other is `POST /clients` and `GET /clients` — and both refuse the header the same way, with `400 account_scope_conflict` and `details.reason = "selfScopedRoute"`. See [Sessions](/whitelabel/sessions#acting-as-a-client). ## The states money is in A deal carries two amounts, and they are what you branch on: * **`capturableAmount`** — money out of the buyer's wallet, held in the contract, not yet paid to the seller. `capture` moves it to the seller, `void` returns it to the buyer, `reclaim` returns it after the hold window. * **`refundableAmount`** — money already paid to the seller that you can still send back. A refund leaves **your own** wallet, not the seller's, so keep a working balance in the deal's token. `status` is a label for the last thing that happened, not a decision input. Read **`availableActions`** — the server computes it from the amounts, the windows and what already landed on chain — and pick from it. A draft nobody approved in time has an empty `availableActions`; there is no `expired` status and nothing sweeps a stale deal. Amounts are decimal strings in the token's major unit, rendered at the token's precision: `"100.000000"` for USDC. `token` is a symbol — `USDC` or `EURC` — never an address. The full status vocabulary is in [Escrow actions](/whitelabel/escrow-actions#statuses). ## The three parties | Party | Who | What they do | | -------- | ----------------------------------- | ------------------------------------------------------------------------------- | | Sender | one of your clients, the buyer | Their wallet funds the deal. They sign nothing: your key signs on their wallet. | | Receiver | another of your clients, the seller | Receives what you capture. | | Operator | you, the integrator | Authorize, charge, capture, void, refund and reclaim. Every action, one key. | All three must be different accounts, and both parties must be clients you created. HEVN binds sender and receiver through the sub-user relationship that `POST /clients` writes, so only accounts you provisioned through this API qualify; an account you merely referred never does, and a stranger's account id answers `422 receiver_not_a_client` or `404 client_not_found`. The addresses are each party's Base smart wallet at creation time, and the deal is immutable: its terms are hashed into an on-chain payment record. ## The three windows You give three durations and HEVN resolves them once, at creation, each measured from the end of the one before it. ```mermaid theme={null} gantt title Default windows on a deal created at 10:04 on 17 September dateFormat YYYY-MM-DD HH:mm axisFormat %d %b section approveWithin — 1h approve · authorize · charge :a1, 2026-09-17 10:04, 1h section holdFor — 14d capture · void :a2, after a1, 14d section refundableFor — 90d refund :a3, after a2, 90d section after holdFor reclaim · void :crit, a4, after a2, 90d ``` | Duration | Default | Ends at | What it bounds | | --------------- | ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `approveWithin` | `1h` | `windows.approveBy` | The buyer's approval, and the `authorize` or `charge` that collects the money. After it, an unapproved deal is dead. | | `holdFor` | `14d` | `windows.holdUntil` | Your delivery window. `capture` is legal until it ends; after it the buyer can `reclaim`. | | `refundableFor` | `90d` | `windows.refundableUntil` | Your returns window. `refund` is legal until it ends. | A duration is `^\d{1,4}[smhd]$` — `30m`, `1h`, `14d`. You never compute a timestamp, which is what makes a retry safe: repeating `POST /dapi/v1/escrow` with the same `Idempotency-Key` returns the same deal with the same absolute windows, no matter how much later it arrives. Different durations under the same key answer `409 idempotency_key_reused` with `details.escrowId`. `void` is the exception with no clock on it: while anything is capturable, you can always hand it back. ## What it costs `feeBps` on the deal is your **ceiling**, an integer in basis points. `capture` and `charge` may take any fee up to it; the fee goes to your own Base smart wallet, which HEVN derives — there is no `feeReceiver` to send. `fee = amount × feeBps / 10000`, the receiver gets the rest, and a refund returns the gross amount from your wallet without clawing the fee back. Set the ceiling at creation. It is part of the immutable deal, so a deal created with `feeBps: 0` can never take a commission. HEVN sponsors the gas for every action and charges nothing on top. ## Before you start * Both parties are clients of yours and are `ready` — see [Clients](/whitelabel/clients). * Your account may operate escrow. HEVN enables that, in the sandbox as in production; nothing in the API grants it. Without it every escrow call is refused — see [Going live](/whitelabel/going-live#what-hevn-must-enable). * The buyer's wallet holds the token when you authorize, not when you create. Creating a deal moves nothing. * Call escrow with your own access token and **no** `X-Hevn-Account` — the header answers `400 account_scope_conflict` on every escrow route. * Your developer key still exists, holds the `escrow:sign` scope, and the call leaves an allowlisted source IP. All three are re-checked on every request, and again immediately before HEVN co-signs an action — see [Developer key](/whitelabel/developer-key#scopes). Derive `Idempotency-Key` from an id your own system already owns, pass it in from the caller, and keep it identical across every retry of the same payment. ```python Python theme={null} key = f"payout-{invoice.id}" # "payout-INV-2026-114" northwind.post("/payouts", payout, idempotency_key=key) ``` ```javascript Node theme={null} const key = `payout-${invoice.id}`; await northwind.post("/payouts", payout, { idempotencyKey: key }); ``` ```go Go theme={null} key := "payout-" + invoice.ID northwind.Post("/payouts", payout, hevn.IdempotencyKey(key)) ``` Never generate the key inside the helper that sends the request, and never rotate it on a retry — both turn one payment into two. The format and the replay windows are in [Conventions](/whitelabel/conventions#idempotency-key). ## A marketplace order, end to end Every example below uses the client from [HTTP client](/whitelabel/reference/client) and the `sign_payload` helper from [Signing](/whitelabel/signing). Order `A-1187`: Northwind Trading Ltd (`cl_7YQ2Kf3mN8`) buys 100 USDC of parts from Ardenne Fabrication SARL (`cl_2ABxR9dL4m`), and you take 2.5% when it ships. One call creates the deal and prepares the buyer's approval — the on-chain permission that lets you pull the money later. Confirm it with the **same** key the create carried; the response echoes it as `action.idempotencyKey`. ```python Python theme={null} deal = hevn.post("/escrow", { "senderClientId": "cl_7YQ2Kf3mN8", "receiverClientId": "cl_2ABxR9dL4m", "token": "USDC", "maxAmount": "100.00", "approveWithin": "1h", "holdFor": "14d", "refundableFor": "90d", "feeBps": 250, "reference": {"orderId": "A-1187"}, }, idempotency_key="order-A-1187") approve = deal["action"] signature = key.sign_payload(approve["approval"]["payload"]) hevn.post(f"/escrow/{deal['id']}/actions/{approve['idempotencyKey']}/confirm", {"signature": signature}) ``` ```javascript Node theme={null} const deal = await hevn.post("/escrow", { senderClientId: "cl_7YQ2Kf3mN8", receiverClientId: "cl_2ABxR9dL4m", token: "USDC", maxAmount: "100.00", approveWithin: "1h", holdFor: "14d", refundableFor: "90d", feeBps: 250, reference: { orderId: "A-1187" }, }, { idempotencyKey: "order-A-1187" }); const approve = deal.action; const signature = key.signPayload(approve.approval.payload); await hevn.post(`/escrow/${deal.id}/actions/${approve.idempotencyKey}/confirm`, { signature }); ``` ```go Go theme={null} deal, err := api.Post("/escrow", hevn.Body{ "senderClientId": "cl_7YQ2Kf3mN8", "receiverClientId": "cl_2ABxR9dL4m", "token": "USDC", "maxAmount": "100.00", "approveWithin": "1h", "holdFor": "14d", "refundableFor": "90d", "feeBps": 250, "reference": hevn.Body{"orderId": "A-1187"}, }, hevn.IdempotencyKey("order-A-1187")) signature, err := key.SignPayload(deal.Str("action.approval.payload")) _, err = api.Post("/escrow/"+deal.Str("id")+"/actions/"+ deal.Str("action.idempotencyKey")+"/confirm", hevn.Body{"signature": signature}) ``` ```json Response — 201, Location: /dapi/v1/escrow/esc_5Qb4e17c9d theme={null} { "id": "esc_5Qb4e17c9d", "status": "draft", "availableActions": ["approve"], "sender": { "clientId": "cl_7YQ2Kf3mN8" }, "receiver": { "clientId": "cl_2ABxR9dL4m" }, "token": "USDC", "maxAmount": "100.000000", "authorizedAmount": "0.000000", "capturableAmount": "0.000000", "refundableAmount": "0.000000", "windows": { "approveBy": "2026-09-17T11:04:11Z", "holdUntil": "2026-10-01T11:04:11Z", "refundableUntil": "2026-12-30T11:04:11Z" }, "action": { "action": "approve", "idempotencyKey": "order-A-1187", "status": "awaitingSignature", "approval": { "id": "a7c1…", "payload": "eyJ…", "expiresAt": "2026-09-17T10:05:11Z" } }, "createdAt": "2026-09-17T10:04:11Z" } ``` Nothing has moved. `availableActions` becomes `["authorize", "charge"]` once the approval lands on chain — if the confirm answers `202`, poll it to settlement first ([Escrow actions](/whitelabel/escrow-actions#confirming-an-action)). `authorize` pulls the amount out of the buyer's wallet into the escrow contract. It happens **once** per deal: authorize less than `maxAmount` and the remainder is unusable, so authorize the order total. ```python Python theme={null} action = hevn.post(f"/escrow/{deal['id']}/actions", {"action": "authorize", "amount": "100.00"}, idempotency_key="order-A-1187-authorize") hevn.post(f"/escrow/{deal['id']}/actions/order-A-1187-authorize/confirm", {"signature": key.sign_payload(action["action"]["approval"]["payload"])}) ``` ```javascript Node theme={null} const action = await hevn.post(`/escrow/${deal.id}/actions`, { action: "authorize", amount: "100.00" }, { idempotencyKey: "order-A-1187-authorize" }); await hevn.post(`/escrow/${deal.id}/actions/order-A-1187-authorize/confirm`, { signature: key.signPayload(action.action.approval.payload) }); ``` ```go Go theme={null} action, err := api.Post("/escrow/"+deal.Str("id")+"/actions", hevn.Body{"action": "authorize", "amount": "100.00"}, hevn.IdempotencyKey("order-A-1187-authorize")) signature, err := key.SignPayload(action.Str("action.approval.payload")) _, err = api.Post("/escrow/"+deal.Str("id")+"/actions/order-A-1187-authorize/confirm", hevn.Body{"signature": signature}) ``` ```json Response — 200 theme={null} { "deal": { "id": "esc_5Qb4e17c9d", "status": "authorized", "capturableAmount": "100.000000", "refundableAmount": "0.000000", "availableActions": ["capture", "void"] }, "action": { "action": "authorize", "idempotencyKey": "order-A-1187-authorize", "status": "confirmed", "amount": "100.000000", "transactionHash": "0x3a77…" }, "events": [ { "name": "PaymentAuthorized", "amount": "100.000000", "transactionHash": "0x3a77…", "blockNumber": 19884412 } ] } ``` The buyer's balance is down 100 USDC, the seller has nothing yet, and you have 14 days to deliver. `capture` pays the seller and takes your fee in the same action. It is repeatable up to `capturableAmount`, so a partial shipment is a partial capture. ```python Python theme={null} capture = hevn.post(f"/escrow/{deal['id']}/actions", {"action": "capture", "amount": "100.00", "feeBps": 250}, idempotency_key="order-A-1187-capture") hevn.post(f"/escrow/{deal['id']}/actions/order-A-1187-capture/confirm", {"signature": key.sign_payload(capture["action"]["approval"]["payload"])}) ``` ```javascript Node theme={null} const capture = await hevn.post(`/escrow/${deal.id}/actions`, { action: "capture", amount: "100.00", feeBps: 250 }, { idempotencyKey: "order-A-1187-capture" }); await hevn.post(`/escrow/${deal.id}/actions/order-A-1187-capture/confirm`, { signature: key.signPayload(capture.action.approval.payload) }); ``` ```go Go theme={null} capture, err := api.Post("/escrow/"+deal.Str("id")+"/actions", hevn.Body{"action": "capture", "amount": "100.00", "feeBps": 250}, hevn.IdempotencyKey("order-A-1187-capture")) signature, err := key.SignPayload(capture.Str("action.approval.payload")) _, err = api.Post("/escrow/"+deal.Str("id")+"/actions/order-A-1187-capture/confirm", hevn.Body{"signature": signature}) ``` The seller receives 97.50 USDC, 2.50 lands on your wallet, and the deal ends `captured` with `refundableAmount: "100.000000"` — the gross is what you can still send back. ## When the order does not go to plan | What happened | Action | Where the money goes | | ------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Cancelled before you ship | `void` | The whole hold returns to the buyer. The deal ends `voided` and nothing was charged. | | Only part shipped | `capture` the shipped lines, then `void` the rest | The deal passes `partiallyCaptured` and ends `voided`, with the captured amount still refundable. | | Returned after delivery | `refund` | The amount leaves **your** wallet and reaches the buyer. `partiallyRefunded`, then `refunded`. | | You never captured | `reclaim`, after `holdUntil` | The hold returns to the buyer. You can run it for them; it keeps working even if your integrator profile is paused. | `void`, `refund` and `reclaim` keep working when your relationship with a client is paused or your profile is suspended, so held money is never stranded. A refund is paid by your own wallet, not out of the deal. If you owe refunds, keep a balance in the deal's token — an empty operator wallet turns `refund` into `409 simulation_failed`. Every action, the window it is legal in, the amount it takes, and the state it leaves behind.