> ## 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. # Balances and transactions > Read a balance, page the ledger, export files, and reconcile. The balance is what each account of a client, or of your integrator account, holds. The ledger lists the movements in and out. Start with `GET /dapi/v1/client/balance`. Send `X-Hevn-Account` to act for a client ([Acting as a client](https://docs.gethevn.com/developers/authentication.md#acting-as-a-client)). ## Balance ```bash cURL theme={null} curl -s "$HEVN_API/client/balance" \ -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \ -H "X-Hevn-Account: cl_7YQ2Kf3mN8" ``` ```python Python theme={null} balance = client.get("/client/balance") ``` ```javascript Node theme={null} const balance = await client.get("/client/balance"); ``` ```go Go theme={null} balance, err := client.Get("/client/balance") ``` ```json Response: 200 theme={null} { "clientId": "cl_7YQ2Kf3mN8", "baseSmartWallet": "0x2f1c…", "accounts": [ { "account": "USDC", "balance": "1204.500000", "usdValue": "1204.50" }, { "account": "USDC", "accountId": "acc_5Jd8Qw2LmX", "balance": "250.000000", "usdValue": "250.00" }, … ], "totalUsd": "1701.05" } ``` Fields: [Read a client's balances](https://docs.gethevn.com/api-reference/accounts/read-a-clients-balances.md). The account keys are in [Account keys](https://docs.gethevn.com/developers/overview.md#account-keys). The balance has no `FDIC_EUR` row. | Balance | Where it is returned | | - | - | | Main wallet and partner bank | One row per account key, with no `accountId` | | Sub account | One row with `account` set to its token, `USDC` or `RD`, and its `accountId`. `totalUsd` includes it. | | External account | Not in this response. Read `balance` on `GET /dapi/v1/client/accounts` ([Accounts](https://docs.gethevn.com/developers/accounts.md)). | If `POST /dapi/v1/payouts` returns `insufficient_funds` while the balance looks sufficient, a debit is in flight. ## Walk the ledger `GET /dapi/v1/transactions` returns rows newest first, in cursor pages ([Pagination](https://docs.gethevn.com/developers/conventions.md#pagination)). ```bash cURL theme={null} curl -s "$HEVN_API/transactions?limit=50&incomeOnly=true" \ -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \ -H "X-Hevn-Account: $HEVN_CLIENT_ID" ``` ```python Python theme={null} page = client.get("/transactions", params={"limit": 50, "incomeOnly": True}) while page["nextCursor"]: page = client.get("/transactions", params={"limit": 50, "cursor": page["nextCursor"]}) ``` ```javascript Node theme={null} let page = await client.get("/transactions", { limit: 50, incomeOnly: true }); while (page.nextCursor) { page = await client.get("/transactions", { limit: 50, cursor: page.nextCursor }); } ``` ```go Go theme={null} page, err := client.Get("/transactions", hevn.Query{"limit": "50", "incomeOnly": "true"}) for page.Str("nextCursor") != "" { page, err = client.Get("/transactions", hevn.Query{"limit": "50", "cursor": page.Str("nextCursor")}) } ``` ```json Response: 200 theme={null} { "items": [ { "id": "txn_9e4…", "type": "sepa", "status": "success", "isIncome": false, "from": { "amount": "500.00", "currency": "USD", "usdRate": "1.00" }, "to": { "amount": "459.31", "currency": "EUR", "usdRate": "1.0815" }, "fee": { "amount": "1.00", "currency": "USD" }, "counterparty": "Ardenne Fabrication SARL", "paymentReference": "INV-2026-114", "txHash": "0x4f1c…", "hasAttachments": false, "createdAt": "2026-09-17T10:04:39Z" } ], "nextCursor": "eyJ0IjoiMjAyNi0w…" } ``` Fields and filters: [List transactions, newest first](https://docs.gethevn.com/api-reference/transactions/list-transactions-newest-first.md). A row has `accountId` when an external account or a sub account moved the money. It is absent on a main wallet row. | Account | Rows on the ledger | | - | - | | Main wallet | Each tracked transfer in or out | | Sub account | Each transfer its address sends or receives. A [move](https://docs.gethevn.com/developers/swaps.md#sub-account-moves) is two rows of `type: "move"`, one per account. `RD` sent from outside HEVN to an `RD` sub account is not listed. | | External account | The transfers HEVN arranged: payins and virtual-account payments delivered to it, and payouts it funded | ### Filters | Parameter | Takes | | - | - | | `incomeOnly` | `true` keeps only money in | | `contactId` | `ct_…` ids of the contacts you paid | | `bankId` | `bnk_…` ids of the virtual accounts money arrived on | | `accountId` | The `acc_…` id of one external account or sub account. An archived account's rows stay readable. Another account's id returns `404 account_not_found`. | | `tag` | `UNTAGGED` keeps rows with no tag | | `q` | Free text, at least two characters | | `from`, `to` | ISO-8601 timestamps bounding `createdAt` | ### Summary `GET /dapi/v1/transactions/summary` takes the same filters and returns settled and pending totals in USD ([Inflow and outflow totals](https://docs.gethevn.com/api-reference/transactions/inflow-and-outflow-totals-for-the-same-filters.md)). | Rows | Without `accountId` | With `accountId` | | - | - | - | | Sub account income and outflow | Counted | Counted for that account | | `move` rows | Left out | Counted for that account | | External account income | Left out | Counted for that account | ```json Response: 200 theme={null} { "inflowUsd": "12040.50", "inflowCount": 9, "outflowUsd": "8300.00", "outflowCount": 14, "pendingInflowUsd": "2000.00", "pendingInflowCount": 1, "pendingOutflowUsd": "0.00", "pendingOutflowCount": 0 } ``` ### Single transaction `GET /dapi/v1/transactions/{transactionId}` returns the row with more detail ([Retrieve one transaction](https://docs.gethevn.com/api-reference/transactions/retrieve-one-transaction.md)). ## Exports `GET /dapi/v1/transactions/export` streams a file: the filtered transaction list, a transaction report for one virtual account (`kind=statement`), a confirmation that a virtual account exists with its account details (`kind=confirmation`), or a receipt for one transaction (`kind=receipt`). The parameters each `kind` needs and the formats it takes: [Export transactions](https://docs.gethevn.com/api-reference/transactions/export-transactions-a-statement-a-confirmation-or-a-receipt.md). ```bash cURL theme={null} curl -s "$HEVN_API/transactions/export?kind=statement&bankId=bnk_88Hq3T&format=pdf&from=2026-09-01&to=2026-09-30" \ -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \ -H "X-Hevn-Account: $HEVN_CLIENT_ID" \ -o statement.pdf ``` ```python Python theme={null} client.download("/transactions/export", { "kind": "statement", "bankId": "bnk_88Hq3T", "format": "pdf", "from": "2026-09-01", "to": "2026-09-30", }, "statement.pdf") ``` ```javascript Node theme={null} await client.download("/transactions/export", { kind: "statement", bankId: "bnk_88Hq3T", format: "pdf", from: "2026-09-01", to: "2026-09-30", }, "statement.pdf"); ``` ```go Go theme={null} _, err := client.Download("/transactions/export", hevn.Query{ "kind": "statement", "bankId": "bnk_88Hq3T", "format": "pdf", "from": "2026-09-01", "to": "2026-09-30", }, "statement.pdf") ``` The `download` helper is in the [reference client](https://docs.gethevn.com/developers/reference/client.md#download-an-export). ## Reconcile 1. Store the newest `createdAt` you have processed, per client, and per `accountId` when you reconcile accounts apart. 2. Request `from=` and walk the cursor to the end. 3. Match your records on `id`, and a payout on the `transactionId` its read returns. 4. Move the watermark after the walk completes. Ids are stable, so an overlapping replay is safe. A row appears once the partner bank reports the payment or the chain confirms the transfer. Until then, read the payin or payout by its id. A `pending` row is not an error. ### Refresh the ledger `POST /dapi/v1/transactions/sync` refreshes one client's ledger from the partner bank and the chains its money moved over ([Refresh the ledger](https://docs.gethevn.com/api-reference/transactions/refresh-the-clients-ledger-from-its-sources.md)). ```json Response: 200 theme={null} { "syncedAt": "2026-09-19T12:04:11Z", "written": 3 } ``` Reads do not refresh the ledger. When a transfer made outside your integration must be visible, call sync once before a walk. The route is rate-limited. > [card] [Next: Escrow](https://docs.gethevn.com/developers/escrow.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.