> ## 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. # Payins > Quote incoming fiat, hand the payer instructions, and watch it settle onto the client's wallet. Money arrives four ways: a quoted deposit you priced, a quoted on-chain transfer you priced, an unsolicited wire to account details that are already live, or crypto sent straight to the wallet. All four end as one income row on the client's ledger. | Shape | What you call | What the payer needs | | ---------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Quoted deposit** | `POST /dapi/v1/payins` with `rail`, then `POST /dapi/v1/payins/{payinId}/instructions` | The instructions that quote returns, payment reference included | | **Quoted on-chain transfer** | `POST /dapi/v1/payins` with `originChainId`, then the same instructions call | The `address`, `chainId` and `memo` the instructions return | | **Unsolicited wire** | Nothing — the account details stay live | The `requisites` on the client's active rail from `GET /dapi/v1/banks` | | **Crypto** | Nothing | The client's `baseSmartWallet` address | Quote a payin when you need the rate and the fee pinned before the payer pays, and when you want their transfer attributed to one order. Take an unquoted path when the client publishes its own details and reconciles afterwards. ```mermaid theme={null} flowchart LR Q["POST /dapi/v1/payins
price the deposit"] --> I["POST /dapi/v1/payins/pi_2b7/instructions
what the payer needs"] I --> W["Payer wires"] W --> C["Partner converts"] C --> B["Client's wallet credited
+ income row"] W -.->|"sandbox"| S["POST /dapi/v1/sandbox/payins/pi_2b7/complete"] S --> C ``` Send `X-Hevn-Account: cl_…` with your own access token to act for one client. On a resource route like `GET /banks` the header is optional: omit it and the call acts on your integrator account instead. The singular `/client*` routes **require** it — the header is the only thing that names the account — and `/clients` and `/escrow*` refuse it. ```bash cURL theme={null} curl "$HEVN_API/banks" \ -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \ -H "X-Hevn-Account: $HEVN_CLIENT_ID" ``` ```python Python theme={null} northwind = hevn.acting_as(CLIENT_ID) rails = northwind.get("/banks") ``` ```javascript Node theme={null} const northwind = hevn.actingAs(clientId); const rails = await northwind.get("/banks"); ``` ```go Go theme={null} northwind := api.ActingAs(clientID) rails, err := northwind.Get("/banks") ``` The whole table — where the header is optional, where it is required and where it is refused — is in [Sessions](/whitelabel/sessions#acting-as-a-client). ## Quote a deposit The client needs an **active rail** in the currency the payer sends — see [Virtual accounts](/whitelabel/virtual-accounts). ```bash cURL theme={null} curl -s -X POST "$HEVN_API/payins" \ -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \ -H "X-Hevn-Account: $HEVN_CLIENT_ID" \ -H "Content-Type: application/json" \ -d '{"amount":"2000.00","currency":"EUR","rail":"sepa","destinationAccount":"EURC"}' ``` ```python Python theme={null} payin = northwind.post("/payins", { "amount": "2000.00", "currency": "EUR", "rail": "sepa", "destinationAccount": "EURC", }) ``` ```javascript Node theme={null} const payin = await northwind.post("/payins", { amount: "2000.00", currency: "EUR", rail: "sepa", destinationAccount: "EURC", }); ``` ```go Go theme={null} payin, err := northwind.Post("/payins", hevn.Body{ "amount": "2000.00", "currency": "EUR", "rail": "sepa", "destinationAccount": "EURC", }) ``` ```json Response — 201, Location: /dapi/v1/payins/pi_2b7… theme={null} { "id": "pi_2b7…", "status": "pending", "rail": "sepa", "quote": { "amount": "2000.00", "currency": "EUR", "settlementAmount": "1989.50", "destinationAccount": "EURC", "feeAmount": "10.50", "feeCurrency": "EUR", "rate": "1.0000" }, "expiresAt": "2026-09-17T10:06:11Z", "createdAt": "2026-09-17T10:04:11Z" } ``` Four decisions: * **`amount` or `amountTo`, exactly one.** `amount` is what the payer sends in `currency`; `amountTo` is what should land on the wallet, and HEVN grosses the payer's side up to reach it. * **`rail` or `originChainId`, exactly one.** `rail` prices money arriving over a payment method; `originChainId` prices money arriving on a chain. Sending both, or neither, is refused. * **`rail` here is a payment *method*** — `sepa`, `ach`, `swift`, `fedwire`, `pix`, … — not the rail id you opened with `POST /dapi/v1/banks`. The two are different vocabularies; [Rails](/whitelabel/reference/rails) lists both. * **`destinationAccount`** is the stablecoin the payin is delivered in, `USDC` (the default) or `EURC`. It has to be a token one of the client's matching rails settles into; when it is not, the call refuses with the pairs that work (see below). The price holds until `expiresAt`. Read it; do not cache a quote. ```bash cURL theme={null} curl -s -X POST "$HEVN_API/payins/pi_2b7…/instructions" \ -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \ -H "X-Hevn-Account: $HEVN_CLIENT_ID" \ -H "Content-Type: application/json" -d '{}' ``` ```python Python theme={null} instructions = northwind.post(f"/payins/{payin['id']}/instructions", {}) ``` ```javascript Node theme={null} const instructions = await northwind.post(`/payins/${payin.id}/instructions`, {}); ``` ```go Go theme={null} instructions, err := northwind.Post("/payins/"+payin.Str("id")+"/instructions", hevn.Body{}) ``` ```json Response — 200 theme={null} { "payinId": "pi_2b7…", "kind": "bank_transfer", "amount": "2000.00", "currency": "EUR", "paymentReference": "HEVN-7QF3K2", "singleUse": true, "requisites": { "fields": { "iban": "MT84…", "bic": "BANKMTMT" }, "holder": { "type": "business", "businessName": "Northwind Trading Ltd" }, "bankName": "Bank A", "state": "active" } } ``` Hand `requisites` to the payer verbatim, **`paymentReference` included** — on a pooled account it is the only thing that attributes the money to this payin. `kind` says where the payer acts: `bank_transfer` (use `requisites`), `qr_code` (`qrPayload`), `hosted_page` (`url`), `manual`, or `onchain` (`address`, `chainId` and `memo`). `singleUse: true` means these instructions belong to this payin alone. Opening the same payin again returns the same instructions — that is the safe retry, not a way to create a second payin. Once the price stops holding it answers `410 payin_expired`; quote again. `GET /dapi/v1/payins/{payinId}` carries the payin through its whole life. Settlement is driven by the partner's own reports, so poll it rather than waiting on a response. ```python Python theme={null} import random, time def poll_until(read, done, *, deadline=120.0, first=1.0, cap=8.0): """Call read() until done(value) is true. Returns the last value or raises TimeoutError.""" started, delay = time.monotonic(), first while True: value = read() if done(value): return value if time.monotonic() - started > deadline: raise TimeoutError(f"still {value.get('status')} after {deadline:.0f}s") time.sleep(delay + random.uniform(0, delay / 2)) delay = min(delay * 2, cap) ``` ```javascript Node theme={null} export async function pollUntil(read, done, { deadline = 120_000, first = 1_000, cap = 8_000 } = {}) { const until = Date.now() + deadline; let delay = first; for (;;) { const value = await read(); if (done(value)) return value; if (Date.now() > until) throw new Error(`still ${value.status} after ${deadline}ms`); await new Promise((wake) => setTimeout(wake, delay + Math.random() * (delay / 2))); delay = Math.min(delay * 2, cap); } } ``` ```go Go theme={null} func PollUntil[T any](read func() (T, error), done func(T) bool, deadline time.Duration) (T, error) { until, delay := time.Now().Add(deadline), time.Second for { value, err := read() if err != nil { return value, err } if done(value) { return value, nil } if time.Now().After(until) { return value, fmt.Errorf("hevn: still pending after %s", deadline) } time.Sleep(delay + time.Duration(rand.Int63n(int64(delay/2)))) if delay < 8*time.Second { delay *= 2 } } } ``` | `status` | Meaning | | -------------------- | ------------------------------------------------------ | | `pending` | Priced. Nothing has arrived. | | `awaitingFunds` | Open, instructions issued, waiting for the payer. | | `processing` | The partner has the money and is converting it. | | `inReview` | Held pending an information request about the payment. | | `completed` | Settled. The tokens are on the client's wallet. | | `failed`, `canceled` | It will not arrive. Quote again. | | `refunded` | Returned to the payer. | ## Quote an on-chain transfer `originChainId` in place of `rail` prices money arriving on a chain instead of through a bank. The body is otherwise the same call: ```json theme={null} { "amount": "2000.00", "currency": "USDC", "originChainId": "arb", "destinationAccount": "USDC" } ``` `PayinView` then carries `originChainId` — the network the payer funds from — and `destinationChainId`, the network the payin settles on. Open it with the same `POST /dapi/v1/payins/{payinId}/instructions`, and the instructions answer `kind: "onchain"` with the three fields a sender needs: ```json Response — 200 theme={null} { "payinId": "pi_5d3…", "kind": "onchain", "amount": "2000.00", "currency": "USDC", "singleUse": true, "address": "0x9b41…", "chainId": "arb", "memo": null } ``` `memo` is the destination tag some networks route on. When it is present it is as load-bearing as a `paymentReference` — a transfer that omits it cannot be attributed. `ChainCode` is the same vocabulary a wallet contact uses; `base`, `arb`, `sol` and the rest are listed on the [rail reference](/whitelabel/reference/rails). This is the quoted arm of crypto-in. The unquoted arm — send straight to the wallet, no call at all — is further down. ## What a rail converts at `GET /dapi/v1/banks/{rail}/rate` answers `{currency, rate, fixedFee, fixedFeeCurrency}` — the indicative price of a deposit over that rail. On a rail the client has not opened, only `currency` comes back. Use it to show a rate in your own UI before the payer commits to an amount. It is indicative: `POST /dapi/v1/payins` returns the number you are held to. ## When the payer has to be named Some rails require the payer's own account so the receiving bank can check the sender. `POST /dapi/v1/payins/{payinId}/instructions` takes it: ```json theme={null} { "payer": { "method": "sepa", "requisites": { "method": "sepa", "currency": "EUR", "fields": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX" }, "holder": { "type": "business", "businessName": "Payer GmbH" } } } } ``` `payer.requisites.method` has to equal `payer.method`. When a rail needs the payer and you omit it, the call answers `400 invalid_request` and names the fields it wants in `message` — that refusal carries no `details`. `details.options[].payerRequired` on a refused quote is the part you can branch on, and it tells you in advance which pairs demand a payer. ## When a pair cannot be paid A currency and method the client cannot be paid in answers `422 payin_not_available`, and `details.options` carries every pair that **can** — each with `rail`, `currency`, `available`, `minAmount`, `maxAmount`, `feeBps`, `fixedFee`, `payerRequired` and `destinationAccounts`. Read the options rather than pre-flighting: the refusal is the capability catalogue. `410 payin_expired` and `404 payin_not_found` are the other two you will meet; both carry `details.payinId`. [Errors](/whitelabel/reference/errors#rails-and-payins) has the rest. ## Unsolicited wires to the client's account details An active rail's account details stay live between payments. Anyone can wire to them with no quote and no API call from you. 1. Read `requisites` for the active rail from `GET /dapi/v1/banks`. 2. Give the payer the fields it carries, plus `paymentReference` when one is set. 3. The deposit lands as an income row on `GET /dapi/v1/transactions`, carrying `remitter` where the partner reports the sender, `paymentReference`, and the receiving account details. Some partners report no sender at all. When `remitter` is absent on a settled deposit, the sender cannot be recovered from the API — treat it as unknown rather than retrying. ## Crypto straight to the wallet The client's smart wallet is an ordinary address on Base. Read it from `GET /dapi/v1/client/balance` — with the client id in `X-Hevn-Account` — as `baseSmartWallet` and publish it; anything sent there is the client's. Nothing is quoted on this path, and there is no payin record: use the quoted on-chain arm above when you need a price or an attributed transfer. Only **USDC and EURC on Base** are tracked. Other tokens, and the same tokens on other chains, sit at the address without ever becoming a balance or a transaction. ## In the sandbox The partner is emulated, so a quoted payin waits forever until you complete it yourself. One call does what the payer would have done: ```bash cURL theme={null} curl -s -X POST "$HEVN_API/sandbox/payins/pi_2b7f14c0a9/complete" \ -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \ -H "X-Hevn-Account: $HEVN_CLIENT_ID" \ -H "Content-Type: application/json" \ -d '{"remitter":"Payer GmbH"}' ``` ```python Python theme={null} settled = northwind.post(f"/sandbox/payins/{payin['id']}/complete", {"remitter": "Payer GmbH"}) ``` ```javascript Node theme={null} const settled = await northwind.post(`/sandbox/payins/${payin.id}/complete`, { remitter: "Payer GmbH" }); ``` ```go Go theme={null} settled, err := northwind.Post("/sandbox/payins/"+payin.Str("id")+"/complete", hevn.Body{"remitter": "Payer GmbH"}) ``` `POST /dapi/v1/sandbox/deposits` covers the other two unquoted shapes: with `bankId` it emulates an unsolicited wire to that rail, without one it credits the smart wallet with tokens. Both are in [Sandbox](/whitelabel/sandbox#mint-money). The sandbox is the same API against one emulated partner on Base Sepolia. Its money comes from a shared faucet account: at most **100 tokens per credit**, at least `0.10`, and **60 money calls per account per hour**. `GET /dapi/v1/sandbox/treasury` reports the live ceiling. Full table in [Limits](/whitelabel/reference/limits#sandbox). Money out: price and book a bank payout in one call, sign it in the next.