# HEVN

> HEVN documentation: the whitelabel REST API for linking and operating your customers' own accounts, remote transfers for paying from your own account with a capped key, and how the non-custodial platform underneath works.

> ## 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.

- [What is HEVN](https://docs.gethevn.com/general/what-is-hevn.md): HEVN is a non-custodial financial platform: your money lives in a smart wallet only you own, while HEVN provides the payment tooling around it.
- [Architecture](https://docs.gethevn.com/general/architecture.md): How HEVN combines Privy key management, Base smart wallets, and a metadata-only platform API into a non-custodial payment system.
- [Key management with Privy](https://docs.gethevn.com/general/privy-wallets.md): Every HEVN account is rooted in a self-custodial Privy embedded wallet that only the user's email identity can unlock.
- [Base smart wallets](https://docs.gethevn.com/general/smart-wallets.md): Every HEVN account is an ERC-4337 smart wallet on Base — owned only by the user's key, with gasless USDC, deterministic addresses, shared access, and exactly-once transfers.
- [Shared account access](https://docs.gethevn.com/general/shared-access.md): Invite other users to manage a balance — with full onchain ownership or a limited spend allowance — grantable and revocable without HEVN in the middle.
- [Deposits & fiat payouts](https://docs.gethevn.com/general/deposits-and-payouts.md): All deposits land directly in your smart wallet, and fiat payouts are executed by a licensed banking partner — HEVN never holds the money.
- [Cross-chain deposits & withdrawals](https://docs.gethevn.com/general/cross-chain.md): HEVN uses NEAR Intents 1Click for cross-chain swaps — one-time passive deposit addresses, competing market makers, and no HEVN custody.
- [Authentication](https://docs.gethevn.com/general/authentication.md): Platform login is a web3 signature exchange for a JWT — and that JWT can never move money.
- [Trust assumptions](https://docs.gethevn.com/general/trust-assumptions.md): Non-custodial does not mean trustless. An honest map of what HEVN relies on, what a failure of each dependency would mean, and how each one is bounded.
- [Security model](https://docs.gethevn.com/general/security-model.md): A summary of HEVN's trust boundaries: what each party can do, what happens in failure scenarios, and how to protect your account.
- [Remote transfers](https://docs.gethevn.com/remote-transfers/overview.md): Let a server or script send USDC from your own HEVN account, bounded by an onchain spend permission you grant to one key.
- [Keys and permissions](https://docs.gethevn.com/remote-transfers/keys.md): Create a remote transfer key, grant its spender wallet a spend permission, restrict it by IP and lifetime spend, and revoke it.
- [API reference](https://docs.gethevn.com/remote-transfers/api.md): Every route a remote transfer key can call: balance, address lookup, transfers to contacts, invoices, quotes and email addresses, and transfer history.
- [Overview](https://docs.gethevn.com/whitelabel/overview.md): Link your customers' own HEVN accounts through a sign-in popup on your site, open partner-bank payment details for them, and move their money with their approval.
- [What you can build](https://docs.gethevn.com/whitelabel/use-cases.md): The five moves every integration is made of, and three products assembled out of them: a marketplace with escrow, a payables platform, and an embedded account.
- [How money moves](https://docs.gethevn.com/whitelabel/how-money-moves.md): Where a client balance lives, which legs are partner conversions, and what is never instant.
- [Quickstart](https://docs.gethevn.com/whitelabel/quickstart.md): In the sandbox: log in with a developer key, link a client through Sign in with HEVN, fund its wallet, and have its holder approve a payout on chain.
- [Accounts and control](https://docs.gethevn.com/whitelabel/accounts-and-control.md): Who owns a client account, who can move its money, what your developer key can and cannot do, and what happens if it leaks.
- [Developer key](https://docs.gethevn.com/whitelabel/developer-key.md): Create a P-256 key in the app with its IP allowlist, load it on your server, and rotate it without downtime.
- [Sessions](https://docs.gethevn.com/whitelabel/sessions.md): Log in with two calls, hold one access token, and act for any of your clients with one header.
- [Conventions](https://docs.gethevn.com/whitelabel/conventions.md): The seven rules that hold for every operation: money, ids, casing, idempotency, pagination, status codes and errors.
- [Signing](https://docs.gethevn.com/whitelabel/signing.md): Prepare, check, sign, confirm: what you sign, what HEVN verifies, and why confirm is always safe to repeat.
- [Sign in with HEVN](https://docs.gethevn.com/whitelabel/sign-in-with-hevn.md): Link your customer's own HEVN account to your integrator account through a HEVN-hosted popup, and let them approve their own payouts and verify their identity in the same window.
- [Clients](https://docs.gethevn.com/whitelabel/clients.md): Read a client linked through Sign in with HEVN, wait until it is usable, list your clients, and keep the one id that identifies each of them.
- [Onboard a client](https://docs.gethevn.com/whitelabel/onboarding.md): Fill the client's KYB document, upload its papers, complete the submission for review, and answer an RFI — all from your backend.
- [Virtual accounts](https://docs.gethevn.com/whitelabel/virtual-accounts.md): Request a virtual account for a client by product, read what still stands in its way, read the account details its payers wire to, and know when it is payable.
- [Payins](https://docs.gethevn.com/whitelabel/payins.md): Quote incoming fiat, hand the payer instructions, and watch it settle onto the client's wallet.
- [Payouts](https://docs.gethevn.com/whitelabel/payouts.md): Price and book a payout in one call, have the account holder approve it in the sign-in window, and track it to settlement — to a bank account or to a wallet.
- [Swaps](https://docs.gethevn.com/whitelabel/swaps.md): Move money between two accounts you own: dollars to euros on the wallet, or the custodial balance to the wallet and back.
- [Balances and transactions](https://docs.gethevn.com/whitelabel/balances-and-transactions.md): Read a client's balance, walk its ledger with a cursor, and export statements, confirmations and receipts.
- [Escrow](https://docs.gethevn.com/whitelabel/escrow.md): 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 actions](https://docs.gethevn.com/whitelabel/escrow-actions.md): Every escrow action: the amount it takes, the window it is legal in, the state it leaves behind, and how to confirm it.
- [Sandbox](https://docs.gethevn.com/whitelabel/sandbox.md): The one place /dapi/v1/sandbox/* is documented: read the faucet account, mint money, settle a payin and move a payout.
- [Going live](https://docs.gethevn.com/whitelabel/going-live.md): What HEVN must enable, what you re-create per environment, what stops being instant, and what production starts refusing.
- [Coverage](https://docs.gethevn.com/whitelabel/reference/coverage.md): The currencies and payment methods money can arrive in and leave by, the chains a payout can reach, and why the authoritative answer is always per client.
- [Fees](https://docs.gethevn.com/whitelabel/reference/fees.md): Where a fee is declared, where it is quoted, which side of a payment absorbs it, and why the quote is the only number you are held to.
- [Rails and payment methods](https://docs.gethevn.com/whitelabel/reference/rails.md): What each payment method needs, which products a client can request, and the currency each one carries.
- [KYB fields](https://docs.gethevn.com/whitelabel/reference/kyb-fields.md): Every field of the KYB document, its accepted values, the document slots, and how to read a missing[] path.
- [Errors](https://docs.gethevn.com/whitelabel/reference/errors.md): One envelope and every error slug, grouped by resource, with what to do about each.
- [Limits](https://docs.gethevn.com/whitelabel/reference/limits.md): Every number that can refuse your request: rate limits, expiry windows, idempotency scoping, page sizes and sandbox caps.
- [HTTP client](https://docs.gethevn.com/whitelabel/reference/client.md): The whole client — key loading, login, acting as a client, signing, retries and polling — in Python, Node and Go.
- [Changelog](https://docs.gethevn.com/whitelabel/changelog.md): What changed in the whitelabel API, newest first, and what to change on your side.
- [REST API overview](https://docs.gethevn.com/api-reference/overview.md): The published contract for every operation of the HEVN Platform API, grouped the way the whitelabel guide is.
- [API authentication](https://docs.gethevn.com/api-reference/authentication.md): Two calls to log in with a developer key, two tokens to hold, and one header to act as a client.
- [Start a developer-key login and receive the payload to sign](https://docs.gethevn.com/api-reference/auth/start-a-developer-key-login-and-receive-the-payload-to-sign.md): Start developer-key authentication. Sign the returned payload with the registered key and exchange it once through `POST /auth/token` before it expires.
- [Exchange a signed login challenge for a session](https://docs.gethevn.com/api-reference/auth/exchange-a-signed-login-challenge-for-a-session.md): Exchange a signed, unexpired challenge for an access token and refresh token. A challenge is consumed once; replay, a different key or a different account is refused.
- [Exchange a refresh token for a session, optionally acting for an account](https://docs.gethevn.com/api-reference/auth/exchange-a-refresh-token-for-a-session-optionally-acting-for-an-account.md): Exchange a device-bound refresh token for a new short-lived access token. `userId` may select an account the authenticated actor is currently authorized to access.
- [Create a sign-in window session](https://docs.gethevn.com/api-reference/accounts/create-a-sign-in-window-session.md): Issue a short-lived URL for the HEVN sign-in window. Open it in a popup from your page: `link` lets the account holder connect their account and returns a code for `POST /clients/link`, `sign` lets the holder of a connected account approve one payout that waits for their signature. The result comes…
- [Connect an existing account](https://docs.gethevn.com/api-reference/accounts/connect-an-existing-account.md): Exchange the short-lived code the account holder approved in the HEVN sign-in window for access to their account. The account holder keeps signing their own transfers: a payout for this client answers with `authorization: client` and no approval, and the holder approves it in the HEVN sign-in window…
- [List clients](https://docs.gethevn.com/api-reference/accounts/list-clients.md): Every account connected to you, newest first.
- [Retrieve one account](https://docs.gethevn.com/api-reference/accounts/retrieve-one-account.md): Retrieve the client selected by `X-Hevn-Account`. Unknown, malformed and foreign account ids share the same not-found response.
- [Update a client profile](https://docs.gethevn.com/api-reference/accounts/update-a-client-profile.md): Update the phone and postal address for the client selected by `X-Hevn-Account`. Everything else about a client is verification data.
- [Read a client's balances](https://docs.gethevn.com/api-reference/accounts/read-a-clients-balances.md): One row per account the client holds: the tokens on the smart wallet of the client selected by `X-Hevn-Account`, plus any custodial balance. `USDC_ARB` is USDC on Arbitrum at the same wallet address; it is turned on with the client's first balance read. A custodial row is read live from the provider…
- [Provide applicant information](https://docs.gethevn.com/api-reference/verification/provide-applicant-information.md): Save information for the business applicant and its related individual applicants in the entity graph. This updates an editable verification submission; it does not send anything for review. People are addressed by a stable `key` chosen by the caller, so retrying the same body updates the same entit…
- [Retrieve the verification submission](https://docs.gethevn.com/api-reference/verification/retrieve-the-verification-submission.md): Return the current editable applicant information, related people, filed documents, outstanding requirements and the latest review status. `missing` is authoritative for whether `complete` can succeed. A pending or completed review is read-only as an application snapshot; later draft edits apply to…
- [Complete the verification submission](https://docs.gethevn.com/api-reference/verification/complete-the-verification-submission.md): Close the editable submission and send its immutable snapshot for compliance review. This is the only operation that starts review. It is refused with `kyb_incomplete` and the same `missing` paths returned by GET when applicant information or documents are outstanding. An identical retry replays the…
- [Upload a document](https://docs.gethevn.com/api-reference/documents/upload-a-document.md): Stores a file and answers the `doc_…` id the verification document references as `uploadId`. Uploading the same bytes in the same slot twice answers the first id.
- [Fill the typed fields read off a document](https://docs.gethevn.com/api-reference/documents/fill-the-typed-fields-read-off-a-document.md): The verification gate refuses a submission whose documents have no recognised fields. Write them here — the keys are the paths the refusal names in `details.documents`, without the slot prefix.
- [List virtual accounts and available payment methods](https://docs.gethevn.com/api-reference/virtual-accounts/list-virtual-accounts-and-available-payment-methods.md): List receiving payment methods available to the selected account and identify which virtual accounts have already been opened.
- [Request a receiving account for a product](https://docs.gethevn.com/api-reference/virtual-accounts/request-a-receiving-account-for-a-product.md): Answers 201 with the account record the first time, 200 with `Idempotency-Replayed: true` when the product was already requested or is already active. A receiving account is a singleton per client and product, so the server key is the client and the product. Unmet prerequisites never refuse the requ…
- [Retrieve one virtual account](https://docs.gethevn.com/api-reference/virtual-accounts/retrieve-one-virtual-account.md): Retrieve the receiving account of one region product and, when opened, its receiving details. The product is the path key.
- [Retrieve the receiving conversion rate](https://docs.gethevn.com/api-reference/virtual-accounts/retrieve-the-receiving-conversion-rate.md): Return the current conversion rate and fixed fee for this receiving payment method. The result is indicative until an incoming transfer is created.
- [Create an incoming transfer quote](https://docs.gethevn.com/api-reference/transfers/create-an-incoming-transfer-quote.md): Price money arriving for this account. Set `originChainId` for an on-chain transfer or `rail` for a local payment method; exactly one is required. An unsupported route answers `payin_not_available`.
- [Open the incoming transfer and retrieve funding instructions](https://docs.gethevn.com/api-reference/transfers/open-the-incoming-transfer-and-retrieve-funding-instructions.md): Idempotent: an already-open transfer returns the same payment-account details or on-chain deposit address. A quote that stopped holding answers `410 payin_expired`.
- [Retrieve an incoming transfer](https://docs.gethevn.com/api-reference/transfers/retrieve-an-incoming-transfer.md): Retrieve an incoming-transfer quote and its current funding lifecycle. Use the instructions operation when payment details are still required.
- [Create an outgoing transfer](https://docs.gethevn.com/api-reference/transfers/create-an-outgoing-transfer.md): Validate the contact, fix the transfer terms, reserve an idempotent outgoing transfer and return the approval payload to sign. Supplying `amount` fixes the debit side; `amountTo` fixes the contact side.
- [Create an outgoing transfer quote](https://docs.gethevn.com/api-reference/transfers/create-an-outgoing-transfer-quote.md): Estimate rate, fees, limits and contact amount without creating a contact, transfer or external side effect.
- [Authorize an outgoing transfer](https://docs.gethevn.com/api-reference/transfers/authorize-an-outgoing-transfer.md): Verify the developer-key signature against the immutable approval and fund the prepared transfer. A retry cannot change the contact, amount, payment method or quote.
- [Retrieve an outgoing transfer](https://docs.gethevn.com/api-reference/transfers/retrieve-an-outgoing-transfer.md): Retrieve the current transfer lifecycle, including quote, contact, settlement result and any actionable failure.
- [Create a transfer between the client's own accounts](https://docs.gethevn.com/api-reference/transfers/create-a-transfer-between-the-clients-own-accounts.md): Price a move between two accounts the client owns, reserve it idempotently and return the approval to sign. `authorization` says what that approval covers: a `debit` of the client's wallet that funds the move, or an `intent` its smart wallet signs so the backend can settle it.
- [Price a transfer between the client's own accounts](https://docs.gethevn.com/api-reference/transfers/price-a-transfer-between-the-clients-own-accounts.md): Compare every route that can serve this pair of accounts and return the best price. Nothing is booked with a provider and nothing is signed.
- [Authorize a transfer between the client's own accounts](https://docs.gethevn.com/api-reference/transfers/authorize-a-transfer-between-the-clients-own-accounts.md): Verify the developer-key signature against the immutable approval and settle the move. A retry cannot change the accounts, the amount or the quote it was fixed at.
- [Retrieve a transfer between the client's own accounts](https://docs.gethevn.com/api-reference/transfers/retrieve-a-transfer-between-the-clients-own-accounts.md): Retrieve the current lifecycle of a swap, the quote it was fixed at and any actionable failure.
- [Create a contact](https://docs.gethevn.com/api-reference/contacts/create-a-contact.md): Create an idempotent reusable contact from either payment-account or on-chain details. Fields are validated for the selected account type before persistence.
- [List saved contacts](https://docs.gethevn.com/api-reference/contacts/list-saved-contacts.md): List saved contacts using opaque cursor pagination.
- [Retrieve one contact](https://docs.gethevn.com/api-reference/contacts/retrieve-one-contact.md): Retrieve one saved contact without exposing internal routing or infrastructure identifiers.
- [Update a contact](https://docs.gethevn.com/api-reference/contacts/update-a-contact.md): Update fields present in the request. Omitted fields are retained; immutable payment-routing identity cannot be replaced through this operation.
- [Delete a contact](https://docs.gethevn.com/api-reference/contacts/delete-a-contact.md): Remove a saved contact from future selection. Existing transactions remain immutable and readable.
- [Retrieve contact channels](https://docs.gethevn.com/api-reference/contacts/retrieve-contact-channels.md): Return currently available payment methods, limits, fees and blockers. Capabilities are a point-in-time eligibility read, not a transfer quote.
- [List transactions, newest first](https://docs.gethevn.com/api-reference/transactions/list-transactions-newest-first.md): Cursor-paged: pass `nextCursor` back as `cursor`. There is no offset and no total.
- [Retrieve one transaction](https://docs.gethevn.com/api-reference/transactions/retrieve-one-transaction.md): Retrieve one ledger transaction with detailed counterparties, payment references and attachments visible to the selected account.
- [Inflow and outflow totals for the same filters](https://docs.gethevn.com/api-reference/transactions/inflow-and-outflow-totals-for-the-same-filters.md): Its own route: an aggregate is never folded into a page.
- [Export transactions, a statement, a confirmation or a receipt](https://docs.gethevn.com/api-reference/transactions/export-transactions-a-statement-a-confirmation-or-a-receipt.md): Without `kind` the filtered transaction list is exported as `csv`, `xlsx` or `pdf`. `kind=statement` and `kind=confirmation` need `bankId` and support `pdf` or `xlsx`; `kind=receipt` needs `transactionId` and answers `pdf`.
- [Open an escrow and return the payer's approval](https://docs.gethevn.com/api-reference/escrow/open-an-escrow-and-return-the-payers-approval.md): 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 s…
- [List the escrows this account operates](https://docs.gethevn.com/api-reference/escrow/list-the-escrows-this-account-operates.md): List escrow agreements operated by the authenticated account, newest first.
- [Read one escrow](https://docs.gethevn.com/api-reference/escrow/read-one-escrow.md): Retrieve one escrow, its current balances, deadlines, available actions and last reconciled chain state.
- [Prepare an escrow action and return the payload to sign](https://docs.gethevn.com/api-reference/escrow/prepare-an-escrow-action-and-return-the-payload-to-sign.md): Prepare an escrow action and return the immutable payload to sign. This request does not broadcast the action.
- [Submit the signature for a prepared escrow action](https://docs.gethevn.com/api-reference/escrow/submit-the-signature-for-a-prepared-escrow-action.md): Submit the signature for the previously prepared escrow action. The path idempotency key must match the prepared action and makes safe retries return the first result.
- [Reconcile one escrow with the chain](https://docs.gethevn.com/api-reference/escrow/reconcile-one-escrow-with-the-chain.md): Reconcile one escrow with current on-chain state. This read-through operation may persist newly observed events but never invents a successful chain action.
- [Read the sandbox treasury that funds emulated credits](https://docs.gethevn.com/api-reference/sandbox/read-the-sandbox-treasury-that-funds-emulated-credits.md)
- [Emulate an incoming deposit: an account transfer with bankId, a token transfer without](https://docs.gethevn.com/api-reference/sandbox/emulate-an-incoming-deposit:-an-account-transfer-with-bankid-a-token-transfer-without.md)
- [Emulate the arrival of the funds a pay-in is waiting for](https://docs.gethevn.com/api-reference/sandbox/emulate-the-arrival-of-the-funds-a-pay-in-is-waiting-for.md)
- [Move an emulated outgoing transfer to its next reported status](https://docs.gethevn.com/api-reference/sandbox/move-an-emulated-outgoing-transfer-to-its-next-reported-status.md)

## OpenAPI Specs

- [openapi](/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.