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

# Accounts

> Account keys, acc_ ids, and how external accounts and sub accounts differ.

An `acc_…` id names an external account or a sub account: an address of its own, apart from the main wallet. List the ones a client or your own account has with `GET /dapi/v1/client/accounts`.

## Uses of the word

| Use | Named by | Example |
| - | - | - |
| A HEVN account: your integrator account or a client | A `cl_…` id, sent in `X-Hevn-Account` | `cl_7YQ2Kf3mN8` |
| A balance on the main wallet or at the partner bank | An [account key](https://docs.gethevn.com/developers/overview.md#account-keys) | `USDC`, `EURC`, `FDIC_USD` |
| An external account or a sub account | An `acc_…` id | `acc_5Jd8Qw2LmX` |

A balance on the main wallet has an account key and no `acc_…` id.

## Kinds

`kind` on the record is `external` or `sub`. The two kinds share the `/dapi/v1/client/accounts` routes and the id space.

| | External account | Sub account |
| - | - | - |
| What it is | A wallet address a client holds and signs for | A further wallet of your own integrator account that HEVN opens |
| Whose account | A client's, selected by `X-Hevn-Account` | Yours. A request that acts for a client returns `403 account_not_controlled`. |
| Created with | `POST /dapi/v1/client/accounts` and `chain`, `address`, optional `label` | `POST /dapi/v1/client/accounts` and `kind: "sub"`, optional `asset`, `label` |
| Network | `base`, `arb`, `eth`, `op`, `pol` or `sol` | Base |
| Token, returned as `asset` | `USDC` | `USDC` or `RD`, fixed at creation |
| Who signs a spend | The customer's wallet. HEVN and your developer key hold no key to it. | Your developer key, co-signed by HEVN |
| Payout `authorization` | `wallet`. The response has `transfer`, and there is no confirm call. | `debit`. Sign `approval.payload` and confirm. |
| Payout source | A Base account, paying USDC | The token the account holds |
| Swaps and moves | `404 account_not_found` | A move to or from the main wallet or another sub account of the same token, one for one, no fee |
| Payins | On-chain (`originChainId`). `refundAddress` is required. | On-chain (`originChainId`). No `refundAddress`. |
| Virtual accounts | Products whose rail delivers USDC to the address | Products whose rail delivers the account's token to the address |
| Balance | `balance` on the account record | `balance` on the account record, plus a row in `GET /dapi/v1/client/balance` |
| Ledger | Rows for the transfers HEVN arranged | Rows for each transfer the address sends or receives, except `RD` sent from outside HEVN to an `RD` sub account ([RD sub accounts](https://docs.gethevn.com/sub-accounts/money-movement.md#rd-sub-accounts)) |
| Archive | `DELETE /dapi/v1/client/accounts/{accountId}` | `409 account_archive_unsupported` |

The rules of each kind are on [External accounts](https://docs.gethevn.com/external-wallets/external-accounts.md) and [Sub accounts](https://docs.gethevn.com/sub-accounts/overview.md).

## Header

The `/dapi/v1/client/accounts` routes require `X-Hevn-Account`. Send a client's `cl_…` id for its external accounts. For your own sub accounts, send your own `cl_…` id, the `userId` that `POST /dapi/v1/auth/token` returns ([Acting as a client](https://docs.gethevn.com/developers/authentication.md#acting-as-a-client)).

```bash cURL theme={null}
curl "$HEVN_API/client/accounts" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_USER_ID"
```

```python Python theme={null}
mine = hevn.acting_as(USER_ID).get("/client/accounts")["items"]
```

```javascript Node theme={null}
const { items: mine } = await hevn.actingAs(userId).get("/client/accounts");
```

```go Go theme={null}
page, err := api.ActingAs(userID).Get("/client/accounts")
mine := page.List("items")
```

```json Response 200 theme={null}
{ "items": [
    { "accountId": "acc_5Jd8Qw2LmX", "kind": "sub", "asset": "USDC", "chain": "base",
      "address": "0x61c2…", "label": "Payroll", "balance": "250.0",
      "syncedAt": "2026-11-13T09:41:07Z", "createdAt": "2026-11-13T09:12:30Z" } ] }
```

The list is ordered oldest first and holds both kinds ([List accounts](https://docs.gethevn.com/api-reference/client-accounts/list-accounts.md)). `balance` is read from the network when the stored value is older than a minute. When the network does not respond, the route returns the last value read, with its time in `syncedAt`.

## Accepted fields

| Field | Route | Accepts |
| - | - | - |
| `sourceAccount` | `POST /dapi/v1/payouts` | An account key, an external account on Base or a sub account ([Payouts](https://docs.gethevn.com/developers/payouts.md#authorization)) |
| `sourceAccount`, `destinationAccount` | `POST /dapi/v1/swaps`, `POST /dapi/v1/swaps/preview` | An account key or a sub account ([Swaps](https://docs.gethevn.com/developers/swaps.md#sub-account-moves)) |
| `destinationAccount` | `POST /dapi/v1/payins` | An account key, an external account or a sub account ([Payins](https://docs.gethevn.com/developers/payins.md#deliver-to-an-account)) |
| `accountId` | `POST /dapi/v1/banks`, `GET /dapi/v1/banks/{product}` | An external account or a sub account ([Virtual accounts](https://docs.gethevn.com/developers/virtual-accounts.md#deliver-to-an-account)) |
| `accountId` | `GET /dapi/v1/transactions`, `/summary`, `/export` | An external account or a sub account, archived ones included ([Balances and transactions](https://docs.gethevn.com/developers/balances-and-transactions.md#filters)) |
| `accountId` | `POST /dapi/v1/sandbox/deposits` | A sub account ([Sandbox](https://docs.gethevn.com/developers/sandbox.md#accounts)) |

Responses return the id as `accountId` on a virtual account, a payin, a balance row and a transaction. The refusals of these fields are in [Errors](https://docs.gethevn.com/developers/reference/errors.md#accounts).

> [card] [Next: Clients and verification](https://docs.gethevn.com/developers/clients.md)


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