> ## Documentation Index > Fetch the complete documentation index at: https://docs.gethevn.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > HEVN accounts are non-custodial in both products. 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 customer creates and owns their account through Sign in with HEVN, a HEVN-hosted popup on the integrator's site; the integrator's backend holds a developer key, operates linked accounts and books their payouts, and the account holder approves every payout in that popup. The developer key signs only for the integrator's own wallet; it never signs a client's money. > 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 a customer's own account linked to the integrator through Sign in with HEVN (POST /dapi/v1/connect/sessions, then POST /dapi/v1/clients/link); there is no API call that creates one. 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. Developer keys have an IP allowlist and no scopes. Remote transfers are at /api/v1/remote_spend_limit and take a remote transfer key (rsl_) in X-Api-Key, bounded by an onchain spend permission the account holder grants. They are different credentials and neither works on the other surface. The HEVN CLI is discontinued. # 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 you drive is one `POST /dapi/v1/escrow/{escrowId}/actions` that you sign with your developer key, on your own wallet. You are the **operator** of every deal you create; escrow never takes `X-Hevn-Account`, because the caller is always you. Like `/clients*` and `/connect/sessions`, it refuses the header with `400 account_scope_conflict` and `details.reason = "selfScopedRoute"`. See [Sessions](https://docs.gethevn.com/whitelabel/sessions.md#acting-as-a-client). > [!WARNING] > > The buyer approves a deal with their own key: the spend permission that lets you pull the money later lives on the buyer's wallet, and your key never signs there. The [sign-in window](https://docs.gethevn.com/whitelabel/sign-in-with-hevn.md) does not offer escrow approvals yet, so `POST /dapi/v1/escrow` with a client linked through Sign in with HEVN as the buyer answers `403 account_not_controlled`. Talk to HEVN before you build on escrow. The rest of this page describes the deal and the operator actions as they work once the buyer has approved. ## 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, and the buyer's own `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](https://docs.gethevn.com/whitelabel/escrow-actions.md#statuses). ## The three parties | Party | Who | What they do | | - | - | - | | Sender | one of your clients, the buyer | Their wallet funds the deal. They approve its spend permission with their own key, and can reclaim an uncaptured hold after `holdUntil`. | | Receiver | another of your clients, the seller | Receives what you capture. | | Operator | you, the integrator | Authorize, charge, capture, void and refund. Every one is signed by your key on your own wallet. | All three must be different accounts, and both parties must be clients linked to you. HEVN binds sender and receiver through the relationship [Sign in with HEVN](https://docs.gethevn.com/whitelabel/sign-in-with-hevn.md) writes; an account you merely referred never qualifies, 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 linked to you and are `ready` — see [Clients](https://docs.gethevn.com/whitelabel/clients.md). * 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](https://docs.gethevn.com/whitelabel/going-live.md#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 and the call leaves an allowlisted source IP. Both are re-checked on every request, and again immediately before HEVN co-signs an action — see [Developer key](https://docs.gethevn.com/whitelabel/developer-key.md#the-ip-allowlist). 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](https://docs.gethevn.com/whitelabel/conventions.md#idempotency-key). ## A marketplace order, end to end Every example below uses the client from [HTTP client](https://docs.gethevn.com/whitelabel/reference/client.md) and the `sign_payload` helper from [Signing](https://docs.gethevn.com/whitelabel/signing.md). 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. **1. Open the deal, and let the buyer approve it** One call creates the deal and prepares the buyer's approval — the on-chain permission that lets you pull the money later. The response echoes the create's key as `action.idempotencyKey`. The approval is the buyer's to sign with their own key, not yours. ```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") ``` ```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" }); ``` ```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")) ``` ```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 buyer's approval lands on chain; read the deal until it does. **2. Lock the buyer's funds in the contract** `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. **3. Ship it, and capture with your commission** `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 | The buyer's own `reclaim`, after `holdUntil` | The hold returns to the buyer. It is not an action you send, and it keeps working even if your integrator profile is paused. | `void` and `refund` keep working when your relationship with a client is paused or your profile is suspended, and so does the buyer's `reclaim`, so held money is never stranded. > [!WARNING] > > 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`. > [card] [Next: Escrow actions](https://docs.gethevn.com/whitelabel/escrow-actions.md) > > Every action, the window it is legal in, the amount it takes, and the state it leaves behind. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.