> ## 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. # Sub accounts > Open further wallets of your own account, each with its own address, balance and virtual accounts. A sub account is a further Base smart wallet of your integrator account, with its own address, balance, ledger and virtual accounts. Open one with `POST /dapi/v1/client/accounts` and `kind: "sub"`, sending your own `cl_…` id in `X-Hevn-Account`. A typical use is one sub account per customer of yours, each with a wallet address and account details. Your developer key signs payouts and moves from a sub account as it does for your main wallet ([Signing](https://docs.gethevn.com/developers/signing.md)). ```json Response 201, Location: /dapi/v1/client/accounts/acc_9f2c… theme={null} { "accountId": "acc_9f2c…", "kind": "sub", "asset": "USDC", "chain": "base", "address": "0x51c7…", "label": "customer-1042", "balance": "0.0", "createdAt": "2026-11-13T09:14:02Z" } ``` The wallet has the same owners as your main wallet. Its `address` accepts transfers on Base as soon as the call returns, and the wallet is deployed with the first operation it sends. Field rules are on [Add an account](https://docs.gethevn.com/api-reference/client-accounts/add-an-account.md). ## Ownership Sub accounts exist on your integrator account, which is a HEVN account: a profile plus a Base smart wallet. `/client/accounts` requires `X-Hevn-Account`, so send your own id, the `userId` that [login](https://docs.gethevn.com/developers/authentication.md#sessions) returns. | Header value | `POST /client/accounts` with `kind: "sub"` | | - | - | | Your own `cl_…` id | Opens the sub account. | | The id of a client linked through [HEVN Connect](https://docs.gethevn.com/connect/overview.md) | `403 account_not_controlled`, with the client in `details.clientId` | | The id of a client created for [External wallets](https://docs.gethevn.com/external-wallets/overview.md) | `403 account_not_controlled`, with the client in `details.clientId` | The developer key signs for your own wallet and its sub accounts, and for no client's wallet, so a sub account on a client could not be spent with it. For a wallet your customer holds and signs for, register an [external account](https://docs.gethevn.com/external-wallets/external-accounts.md). The two kinds are compared in [Accounts](https://docs.gethevn.com/developers/accounts.md). A client that opened sub accounts in the HEVN app has them listed under its id on `GET /dapi/v1/client/accounts`. A move from one of them through the API returns `403 account_not_controlled`. ## Token A sub account holds one token on Base, set by `asset` at creation: `USDC` (the default) or `RD`. Any other value returns `422 validation_failed`, and the token of an existing sub account cannot be changed. Virtual accounts, payins, payouts and moves of the sub account run in that token. `RD` is the account key of the same name on your main wallet ([Account keys](https://docs.gethevn.com/developers/overview.md#account-keys)), and what it changes is in [RD sub accounts](https://docs.gethevn.com/sub-accounts/money-movement.md#rd-sub-accounts). ## Label `label` is optional, at most 64 characters, and together with `asset` it identifies the sub account on a retry. Use your own customer id as the label. | Request | Result | | - | - | | A `label` and `asset` that no sub account of yours has | `201` with a new sub account | | The same `label` and `asset` again | `200` with `Idempotency-Replayed: true` and the existing sub account | | The same `label` with the other `asset` | `201` with a second sub account | | No `label` | `201` with a new sub account on each call | An `Idempotency-Key` does not change the result. A body field other than `kind`, `label` and `asset` returns `422 validation_failed`. ## Refusals | Error | Cause | | - | - | | `403 account_not_controlled` | `X-Hevn-Account` names a client. | | `409 safe_mode_required` | The main wallet of your account is not protected by co-signing. | | `409 account_address_taken` | No address could be allocated after a retry. Send the request again. | | `409 account_destination_unsupported` | `asset` is `RD` in the [sandbox](https://docs.gethevn.com/sub-accounts/money-movement.md#sandbox). | | `409 account_archive_unsupported` | `DELETE /dapi/v1/client/accounts/{accountId}` on a sub account. A sub account cannot be archived or deleted. | | `404 account_not_found` | The `acc_…` id is unknown or belongs to another account. | ## Limits | Area | Sub account | | - | - | | Network | Base | | Tokens | `USDC` or `RD`. No EURC sub account. | | Spend limits and dual approval | Not evaluated per sub account. The transfer policy of your account applies to each source. | | Escrow and cards issued by a partner | Not available on a sub account | | Archive | None | | A token the sub account does not hold | Left out of `balance`. It can be moved to your main wallet ([Other tokens](https://docs.gethevn.com/sub-accounts/money-movement.md#other-tokens)). | > [card] [Next: Quickstart](https://docs.gethevn.com/sub-accounts/quickstart.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.