Balances and transactions

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

Balance

curl -s "$HEVN_API/client/balance" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: cl_7YQ2Kf3mN8"

balance = client.get("/client/balance")

const balance = await client.get("/client/balance");

balance, err := client.Get("/client/balance")

Response: 200

{ "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. The account keys are in 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).

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

curl -s "$HEVN_API/transactions?limit=50&incomeOnly=true" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID"

page = client.get("/transactions", params={"limit": 50, "incomeOnly": True})
while page["nextCursor"]:
    page = client.get("/transactions", params={"limit": 50, "cursor": page["nextCursor"]})

let page = await client.get("/transactions", { limit: 50, incomeOnly: true });
while (page.nextCursor) {
  page = await client.get("/transactions", { limit: 50, cursor: page.nextCursor });
}

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")})
}

Response: 200

{ "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. 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 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).

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

Response: 200

{ "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).

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.

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

client.download("/transactions/export", {
    "kind": "statement", "bankId": "bnk_88Hq3T", "format": "pdf",
    "from": "2026-09-01", "to": "2026-09-30",
}, "statement.pdf")

await client.download("/transactions/export", {
  kind: "statement", bankId: "bnk_88Hq3T", format: "pdf",
  from: "2026-09-01", to: "2026-09-30",
}, "statement.pdf");

_, 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.

Reconcile

Store the newest createdAt you have processed, per client, and per accountId when you reconcile accounts apart.
Request from=<watermark> and walk the cursor to the end.
Match your records on id, and a payout on the transactionId its read returns.
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).

Response: 200

{ "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.

Start here

Core concepts

Clients

Move money

Ship it

Reference

Changelog

Balances and transactions

Balance

Walk the ledger

Filters

Summary

Single transaction

Exports

Reconcile

Refresh the ledger

Next: Escrow