> ## 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 is payments software: an API and app over a Base smart wallet. HEVN is not a bank and holds no key to the wallet. Virtual accounts, fiat payins and fiat payouts are provided by partner banks, which hold fiat while it is in transit. Self-serve (the General tab): the person who controls the email signs for the wallet. Developers integrate /dapi/v1 in one of two ways. HEVN Connect (recommended, the HEVN Connect tab): the integrator's customer creates or links a HEVN account in a HEVN-hosted sign-in window on the integrator's site, the integrator's backend reads the linked account and books its payouts, and the account holder approves each payout in that window. External wallets (the External wallets tab, enabled per integrator): the integrator creates a client through the API, registers a wallet address the customer holds as an external account, and requests virtual accounts that deliver to that address. The customer's own wallet sends each transfer that funds a payout. The developer key signs for the integrator's wallet and its sub accounts and cannot sign for a client's wallet.
> Use HEVN's terms as written. A product is the region a client requests. A rail is the bank route HEVN picks for the product. A virtual account (bnk_) is the record a partner bank opens for a client. Account details are what a payer needs to send a bank transfer, returned in a field named requisites. A client (cl_) is a customer's account: linked to the integrator through Sign in with HEVN (POST /dapi/v1/connect/sessions, then POST /dapi/v1/clients/link), or created with POST /dapi/v1/clients for an external-wallets integration. An external account (acc_, kind external) is a wallet address the client holds and signs for. A sub account (acc_, kind sub) is a further wallet of the integrator's own account on Base, spent with the developer key. Write 'sub account' as two words. A contact is a saved destination. A beneficiary is the party that receives a fiat payout. Money leaving an account is a payout, whether it goes to a bank account or to a wallet.
> Do not name a bank, payment institution, card issuer, identity-verification vendor or stablecoin issuer. Say 'the partner bank'. Do not describe HEVN as licensed, regulated or insured.
> HEVN publishes no fee rates, spreads or minimums. Prices come from a quote on a specific payment. Direct pricing questions to HEVN and do not invent numbers.
> The 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. The two credentials are separate and neither works on the other API. The HEVN CLI is discontinued.
# Overview
> Choose an integration kind, get API access, and see how money moves and who signs each payment.
The `/dapi/v1` API lets your backend onboard customers, open virtual accounts for them and move their money. Choose an integration kind below, then log in with `POST /dapi/v1/auth/challenge` and `POST /dapi/v1/auth/token`.
## Integration kinds
Both kinds use the same API, the same developer key and the same sandbox. They differ in who holds the customer's wallet and how a payout is authorized.
| | HEVN Connect | External wallets |
| - | - | - |
| Status | Recommended | For integrators that run their own wallet infrastructure. HEVN enables it per integrator. |
| Customer's wallet | The Base smart wallet of the customer's HEVN account | A wallet address the customer holds outside HEVN |
| How a client is created | The customer signs in through the sign-in window on your site, then you call `POST /dapi/v1/clients/link` | You call `POST /dapi/v1/clients`, then register the address with `POST /dapi/v1/client/accounts` |
| Who can be a client | A business or an individual | A company |
| Money in | Settles on the client's Base smart wallet | Settles as USDC on the registered address |
| Payout | `authorization: "client"`. The holder signs in the sign-in window. | `authorization: "wallet"`. The customer's wallet sends one USDC transfer. |
| HEVN in your UI | The sign-in window | None |
HEVN Connect needs no wallet infrastructure of your own. HEVN provides the wallet and the signing screen.
External wallets is a full whitelabel. Before HEVN enables `POST /dapi/v1/clients` for you, you show that your customers hold the keys to their wallets and that your wallet infrastructure is non-custodial.
> [card] [HEVN Connect](https://docs.gethevn.com/connect/overview.md)
> [card] [External wallets](https://docs.gethevn.com/external-wallets/overview.md)
### Sub accounts
A sub account is a further wallet of your own integrator account on Base, with its own address, balance, ledger and virtual accounts. Your developer key signs for it. You open sub accounts on your own account, and a request that acts for a client returns `403 account_not_controlled`. See [Sub accounts](https://docs.gethevn.com/sub-accounts/overview.md).
## API access
1. Ask HEVN to activate your integrator account, in the sandbox and in production ([What HEVN must enable](https://docs.gethevn.com/developers/sandbox.md#what-hevn-must-enable)).
2. Create a developer key in the HEVN app. A key has an IP allowlist and no scopes ([Authentication](https://docs.gethevn.com/developers/authentication.md#developer-key)).
3. Log in from your backend and send the access token as a bearer ([Sessions](https://docs.gethevn.com/developers/authentication.md#sessions)).
Your integrator account and each client linked through HEVN Connect are HEVN accounts: a profile plus a Base smart wallet. A client created with `POST /dapi/v1/clients` is a profile with no wallet at HEVN.
## API layout
Each call acts on your integrator account, or on the client named in `X-Hevn-Account` ([Acting as a client](https://docs.gethevn.com/developers/authentication.md#acting-as-a-client)).
| Resource | Routes under `/dapi/v1` | Page |
| - | - | - |
| Session | `/auth/challenge`, `/auth/token`, `/auth/refresh` | [Authentication](https://docs.gethevn.com/developers/authentication.md) |
| Clients | `/clients`, `/clients/link`, `/connect/sessions`, `/client` | [Clients and verification](https://docs.gethevn.com/developers/clients.md) |
| Verification | `/client/kyb`, `/documents` | [Clients and verification](https://docs.gethevn.com/developers/clients.md#write-the-document) |
| External accounts and sub accounts | `/client/accounts` | [Accounts](https://docs.gethevn.com/developers/accounts.md) |
| Virtual accounts | `/banks` | [Virtual accounts](https://docs.gethevn.com/developers/virtual-accounts.md) |
| Payins | `/payins` | [Payins](https://docs.gethevn.com/developers/payins.md) |
| Payouts | `/contacts`, `/payouts` | [Payouts](https://docs.gethevn.com/developers/payouts.md) |
| Swaps and moves | `/swaps` | [Swaps](https://docs.gethevn.com/developers/swaps.md) |
| Balance and ledger | `/client/balance`, `/transactions` | [Balances and transactions](https://docs.gethevn.com/developers/balances-and-transactions.md) |
| Escrow, enabled per integrator | `/escrow` | [Escrow](https://docs.gethevn.com/developers/escrow.md) |
| Emulation | `/sandbox/*` | [Sandbox](https://docs.gethevn.com/developers/sandbox.md) |
A payment from your own account is prepared, signed with the developer key and confirmed ([Signing](https://docs.gethevn.com/developers/signing.md)). Formats, idempotency and polling are in [Conventions](https://docs.gethevn.com/developers/conventions.md). The API sends no webhooks.
## Base URLs
| Environment | Base URL |
| - | - |
| Sandbox | `https://sandbox-api.hevn.finance/dapi/v1` |
| Production | `https://api.hevn.finance/dapi/v1` |
Browse the spec at [`/dapi/v1/docs`](https://sandbox-api.hevn.finance/dapi/v1/docs) or fetch the schema from `/dapi/v1/openapi.json`.
## How money moves
Money arrives through a virtual account or an on-chain transfer and leaves through a payout to a contact. It settles on a Base smart wallet, a sub account or an external account.
```mermaid theme={null}
flowchart LR
W["Base smart wallet,
sub account or external account"]
subgraph In["Fiat in"]
P["Payer's bank"] --> R["Virtual account
POST /dapi/v1/banks"]
end
subgraph Crypto["Crypto in"]
S["An on-chain sender"]
end
subgraph Out["Fiat out"]
D["Payout funding address"] --> RB["Beneficiary's bank"]
end
R -->|"partner bank converts"| W
S -->|"USDC or EURC"| W
W -->|"POST /dapi/v1/payouts"| D
```
### Account keys
An account key names one balance of a HEVN account. `GET /dapi/v1/client/balance` returns one row in `accounts[]` per balance the account holds: its tokens, `FDIC_USD` and each sub account.
| Account key | Held | Currency |
| - | - | - |
| `USDC` | On the account's Base smart wallet, `baseSmartWallet` | USD |
| `EURC` | On the same wallet | EUR |
| `RD` | On the same wallet, a second dollar token, when HEVN has switched the `RD` account on | USD |
| `USDC_ARB` | The same wallet address on Arbitrum | USD |
| `FDIC_USD` | At the partner bank, when the account holds it | USD |
| `FDIC_EUR` | At the partner bank, when the account holds it. `GET /dapi/v1/client/balance` returns no row for it | EUR |
The token rows are read on chain. `FDIC_USD` and `FDIC_EUR` are account identifiers for a balance held at a partner bank. The name is an identifier and says nothing about deposit insurance.
`sourceAccount` and `destinationAccount` take an account key or the `acc_…` id of an external account or a sub account ([Accounts](https://docs.gethevn.com/developers/accounts.md)). `USDC_ARB` holds and receives, and payins and payouts refuse it with `422 account_not_supported`.
A virtual account record has `destinationAccount`, the account key its rail settles into, and `supportedAccounts`.
### Money in
| Path | Result | Page |
| - | - | - |
| Bank transfer to a virtual account | The partner bank converts it at the rail's rate and delivers the settlement token, minus the rail's `feeBps`. A payin quote is optional. | [Virtual accounts](https://docs.gethevn.com/developers/virtual-accounts.md) |
| Quoted payin | `POST /dapi/v1/payins` takes either `rail` or `originChainId`. `POST /dapi/v1/payins/{payinId}/instructions` returns what the payer needs. | [Payins](https://docs.gethevn.com/developers/payins.md) |
| Transfer to `baseSmartWallet` or to a sub account address | The amount is in the balance once the transfer confirms. No payin record is created. | [Payins](https://docs.gethevn.com/developers/payins.md#direct-crypto) |
> [!WARNING]
>
> Send USDC or EURC on Base to `baseSmartWallet`. A token HEVN does not track does not become a balance or a transaction.
### Money out
`POST /dapi/v1/payouts` books a payout. Its `quote` has the amount that leaves the balance and the amount that arrives.
| Contact | The paying account sends to | Then |
| - | - | - |
| Bank | The funding address for this payout | The partner bank pays the beneficiary's bank. |
| Wallet on Base | The contact's address, from the `sourceAccount` you name | No conversion, so both quote amounts are equal. |
| Wallet on another chain or token | A one-time address for the route | The payout is routed across chains and priced in `quote` ([Payouts](https://docs.gethevn.com/developers/payouts.md#a-routed-payout-is-priced)). |
| Email of a HEVN account | The wallet of the HEVN account with that email | See [Payouts](https://docs.gethevn.com/developers/payouts.md). |
Send `amount` or `amountTo`, as described in [Money](https://docs.gethevn.com/developers/conventions.md#money).
### Status
A payout is complete when `GET /dapi/v1/payouts/{payoutId}` returns `settled`. Fiat timing is set by the partner bank. Poll as described in [Status codes](https://docs.gethevn.com/developers/conventions.md#status-codes).
Completed payins and payouts are rows in `GET /dapi/v1/transactions` ([Balances and transactions](https://docs.gethevn.com/developers/balances-and-transactions.md)).
## Accounts and control
Your developer key signs for your integrator wallet and its sub accounts. A client's wallet belongs to its holder, and the holder's key signs each spend from it.
`X-Hevn-Account` selects whose data a call reads and writes. It does not let the developer key sign for another account's wallet.
### Who can spend
`authorization` on the response of `POST /dapi/v1/payouts` and `POST /dapi/v1/swaps` names who authorizes the payment. The values are defined in [Authorization values](https://docs.gethevn.com/developers/signing.md#authorization-values).
| Operation | `authorization` | Who signs |
| - | - | - |
| A payout or swap from your main wallet | `debit` or `intent` | Your developer key, co-signed by HEVN ([Signing](https://docs.gethevn.com/developers/signing.md)) |
| A payout or move from one of your sub accounts | `debit` | Your developer key, co-signed by HEVN ([Sub accounts](https://docs.gethevn.com/sub-accounts/money-movement.md)) |
| An operator action on an escrow deal you run | n/a | Your developer key, co-signed by HEVN ([Escrow](https://docs.gethevn.com/developers/escrow.md#the-matrix)) |
| A payout for a client linked through HEVN Connect | `client` | The holder, in the sign-in window ([HEVN Connect](https://docs.gethevn.com/connect/money-movement.md)) |
| A payout from a client's external account | `wallet` | The customer's wallet, which sends the transfer ([External wallets](https://docs.gethevn.com/external-wallets/money-movement.md)) |
For a client, these calls return `403 account_not_controlled` with `details.clientId`:
* `POST /dapi/v1/payouts/{payoutId}/confirm`, `POST /dapi/v1/swaps` and `POST /dapi/v1/swaps/{swapId}/confirm`.
* `POST /dapi/v1/payouts` from the main wallet of a client that is not linked through HEVN Connect.
* `POST /dapi/v1/client/accounts` with `kind: "sub"`.
| Question | Answer |
| - | - |
| Can you move a client's money? | No. Your developer key is not a signer on a client's wallet or on an external account. |
| Can HEVN move a client's money without the holder? | No. HEVN holds no key to the client's wallet or to an external account. |
| Can the holder move their balance? | Yes. They sign each payout you book. A HEVN Connect holder can also sign in to HEVN without your product. |
| What can HEVN do to a client balance? | HEVN can stop building new operations for a paused integrator. It cannot spend the balance or reverse a payment. |
| Who decides which beneficiaries a client may pay? | The partner bank, through the refusals a payout returns. HEVN does not choose beneficiaries. |
The holder's key on a HEVN account is an embedded wallet managed by [Privy](https://docs.gethevn.com/general/security-model.md#keys-and-privy). See [Account structure](https://docs.gethevn.com/general/what-is-hevn.md#account-structure).
### What this means for your product
HEVN authenticates your key and does not see your user. Your server chooses the client for each request and sends it in `X-Hevn-Account`:
* Keep the `cl_…` in your signed session. Do not accept a client id from a request body or a query string.
* With HEVN Connect, bind each sign-in to the browser that started it and exchange the link code on your server ([Sign in with HEVN](https://docs.gethevn.com/connect/sign-in-with-hevn.md#3-bind-the-session-to-this-browser)).
* With external wallets, show the customer the `transfer` of a payout before their wallet signs it ([External wallets](https://docs.gethevn.com/external-wallets/money-movement.md)).
A leaked developer key works from addresses on its [IP allowlist](https://docs.gethevn.com/developers/authentication.md#the-ip-allowlist) until you delete it. Whoever has it can read and configure your clients, book client payouts that wait for the holder or the customer's wallet, and spend from your integrator wallet and its sub accounts. The key cannot spend a client balance.
To recover, create a new key, deploy it and delete the old one. HEVN refuses the next request made with a deleted key. See [Rotate a key](https://docs.gethevn.com/developers/authentication.md#rotate-a-key).
## Responsibilities
| You build | HEVN provides |
| - | - |
| Your product UI | Account records, virtual accounts through the partner bank, on-chain balances, the ledger |
| The onboarding form | Submission to the partner bank and the review status |
| The decision to pay and the prompt to the customer | Pricing, execution and the receipt |
| With HEVN Connect, two pages for the sign-in window | The wallet, the sign-in window and its approval screen |
| With external wallets, the wallet, its key handling and its signing flow | The transfer each payout needs, and matching of the transfer once it is mined |
> [card] [Next: Authentication](https://docs.gethevn.com/developers/authentication.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.