> ## Documentation Index
> Fetch the complete documentation index at: https://hevninc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> HEVN accounts are non-custodial in both products. Self-serve (the General tab): the person who owns the email holds the only key and signs for themselves. Whitelabel (the Whitelabel and REST API tabs): the integrator's customer creates and owns their account through Sign in with HEVN, a HEVN-hosted popup on the integrator's site; the integrator's backend holds a developer key, operates linked accounts and books their payouts, and the account holder approves every payout in that popup. The developer key signs only for the integrator's own wallet; it never signs a client's money.
> Use HEVN's terms exactly. A rail is a bank route a client can request. A virtual account (bnk_) is an opened rail. Account details are what a payer needs in order to wire money, and arrive in a field named requisites. A client is a customer's own account linked to the integrator through Sign in with HEVN (POST /dapi/v1/connect/sessions, then POST /dapi/v1/clients/link); there is no API call that creates one. The business behind it is the integrator's customer. A contact is a saved destination; a beneficiary is the party at the far end of a fiat payout. Every departure of money is a payout, to a bank account or to a wallet alike.
> Never name a banking partner. Say 'a licensed banking partner'.
> There are no published fee rates, spreads or minimums. Prices come from a quote on a specific payment; direct pricing questions to HEVN rather than inventing numbers.
> The whitelabel 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. They are different credentials and neither works on the other surface. The HEVN CLI is discontinued.

# REST API overview

> The published contract for every operation of the HEVN Platform API, grouped the way the whitelabel guide is.

This tab is generated from the HEVN Platform API's OpenAPI document: every operation, each with a
schema, request examples and an interactive playground. The API serves that document itself, at
`https://sandbox-api.hevn.finance/dapi/v1/openapi.json`, with Swagger UI at
`https://sandbox-api.hevn.finance/dapi/v1/docs` — so the running deployment is always the authority for a field.

It is the machine-readable half of the [Whitelabel guide](https://hevninc.mintlify.site/whitelabel/overview.md). The guide explains
the model — your integrator account, the client accounts your customers link to it through Sign in with
HEVN, the developer key that logs your backend in. This reference is the exact contract for every call, and its
groups follow the guide's order: log in, link a client, submit its verification, open a rail, move money, operate
escrow.

> [card] [Whitelabel overview](https://hevninc.mintlify.site/whitelabel/overview.md)
>
> What you can build, and the object graph behind it.

> [card] [Quickstart](https://hevninc.mintlify.site/whitelabel/quickstart.md)
>
> Ten steps in the sandbox, from an empty account to money that moved on chain.

## Servers

| Environment | Server | Notes |
| - | - | - |
| Production | `https://api.hevn.finance/dapi/v1` | Real money, Base. |
| Sandbox | `https://sandbox-api.hevn.finance/dapi/v1` | Test funds, Base Sepolia, one emulated partner. |

The document the API serves declares one **relative** server, `/dapi/v1`, so the host decides which of the two rows
above you are talking to; the copy published in this tab names both hosts so the playground can pick one. Every path in
this reference hangs off that base: a full URL is `https://api.hevn.finance/dapi/v1/banks`, and
so is every `Location` header and every `pollUrl` the API answers with — both are absolute paths from the host root
that already begin `/dapi/v1`. The two deployments have separate accounts, and a token issued by one is refused by the
other, so pick the host before you send a request.

The operations tagged **sandbox** exist on the sandbox host only; production answers `404` for them.
Everything else exists on both.

## The bearer model

Every operation but the three under **auth** takes one header:

```http theme={null}
Authorization: Bearer <accessToken>
```

The access token is a short-lived JWT your backend mints for itself by signing a challenge with your registered
developer key. It is the **only** credential this API accepts. Its audience is `platform` and it carries a
`developer_key_id` claim naming the developer key that established the session; a request under `/dapi/v1` carrying
anything else — no bearer, an ordinary API token, or the `platform-refresh` token — is refused before it reaches a
route, with `401 unauthenticated` or `403 forbidden` and `details.reason: "developerSessionRequired"`. Ordinary
`/api/v1` routes refuse a platform token just as firmly, in the other direction.

An API key belongs to [remote transfers](https://hevninc.mintlify.site/remote-transfers/overview.md) and can never authenticate here, because the
boundary refuses the request before the key is read.

HEVN re-reads the developer key on every request: it must still exist, the request must arrive from an address inside
the immutable allowlist set when the key was created. A deleted key or a new egress IP is a `403` on every operation,
whatever the token says — see
[Developer key](https://hevninc.mintlify.site/whitelabel/developer-key.md).

To act for one of your clients, send that client's id in a second header instead of minting a second
token:

```http theme={null}
X-Hevn-Account: cl_7YQ2Kf3mN8
```

No operation names a client in its path; the header is the only selector, and operations fall into three groups.
Most accept it and act on your own account when you omit it. The singular `/client`, `/client/balance`, `/client/kyb`
and `/client/kyb/complete` **require** it — the spec marks it `required: true`, and omitting it is a
`422 validation_failed` on a missing header, not a read of your own account. Operations that are about your own account
by definition — `POST /clients/link`, `GET /clients`, `POST /connect/sessions` and all of **escrow** — refuse it with `400 account_scope_conflict` and
`details.reason: "selfScopedRoute"`. The three under **auth** ignore it: a login has no account to act for yet. The
full table is in [Sessions](https://hevninc.mintlify.site/whitelabel/sessions.md#acting-as-a-client).

## One error envelope

Every refusal, on every route, has the same body:

```json theme={null}
{
  "error": {
    "code": "insufficient_funds",
    "message": "The account's USDC balance does not cover this transfer.",
    "details": { "available": "3000000", "required": "5000000" }
  }
}
```

`code` is a stable lowercase slug — branch on it, never on `message`. The spec publishes the whole slug enum as
`PlatformErrorCode`, not a per-operation list, so the registry with what to do about each is in
[Errors](https://hevninc.mintlify.site/whitelabel/reference/errors.md). Every response carries an `X-Request-ID`; quote it in a support request.

## Conventions this reference assumes

Bodies, query parameters and response fields are camelCase; unknown keys are refused rather than
ignored; null fields are omitted, so absent and null are the same thing. Money is always a decimal
string in the asset's major unit (`"500.00"`), never a JSON number. Ids are opaque and prefixed by
what they name. Lists page with a cursor. `Idempotency-Key` is accepted on every write and required
on none. All seven rules, in one page:
[Conventions](https://hevninc.mintlify.site/whitelabel/conventions.md).

## Money movement is signed

Reading data, writing metadata and booking a client's payout need only a token. Every money movement
needs a signature from the wallet's owner:

| What moves | Prepare | Who signs, and where |
| - | - | - |
| A client's payout, to a bank or a wallet | `POST /payouts` with `X-Hevn-Account` | The client's holder, in the sign-in window `POST /connect/sessions` opens |
| A payout or swap from your own account | `POST /payouts`, `POST /swaps` | Your developer key: `POST /payouts/{payoutId}/confirm`, `POST /swaps/{swapId}/confirm` |
| An escrow action you operate | `POST /escrow/{escrowId}/actions` | Your developer key: `POST /escrow/{escrowId}/actions/{idempotencyKey}/confirm` |

The holder's side is [Sign in with HEVN](https://hevninc.mintlify.site/whitelabel/sign-in-with-hevn.md); your key's side is one
mechanism, described once in [Signing](https://hevninc.mintlify.site/whitelabel/signing.md).

> [card] [Authentication](https://hevninc.mintlify.site/api-reference/authentication.md)
>
> The two login calls, the two tokens, and the header that picks the account.

> [card] [HTTP client](https://hevninc.mintlify.site/whitelabel/reference/client.md)
>
> A working client in Python, Node and Go: login, retries, signing, polling.


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