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

# HEVN Connect

> Link your customers' HEVN accounts through a sign-in window and let them approve each payout there.

With HEVN Connect, your customer links a HEVN account to you in a HEVN-hosted sign-in window and approves each payout there. Start with `POST /dapi/v1/connect/sessions`, which returns the URL your site opens in a popup.

It is the recommended integration. HEVN provides the wallet, the sign-in and the approval screen, and your backend does the rest with its developer key.

```mermaid theme={null}
sequenceDiagram
    participant C as Your customer
    participant S as Your site and backend
    participant H as HEVN
    S->>H: POST /connect/sessions (link)
    S->>C: opens the sign-in window
    C->>H: signs in, allows your product
    H-->>S: code on redirectUri
    S->>H: POST /clients/link
    H-->>S: client cl_…
    S->>H: POST /payouts with X-Hevn-Account
    H-->>S: authorization "client"
    S->>H: POST /connect/sessions (sign)
    C->>H: approves the payout in the window
```

## What a client is

A HEVN account is a profile plus a Base smart wallet. With HEVN Connect, a client is your customer's HEVN account, created in the [sign-in window](https://docs.gethevn.com/connect/sign-in-with-hevn.md) and linked to you when the holder allows your product there.

The wallet is non-custodial. The holder's key is the signer on it, and HEVN holds no key to it ([Account structure](https://docs.gethevn.com/general/what-is-hevn.md#account-structure)). Your developer key is not a signer on a client's wallet.

`POST /dapi/v1/clients/link` returns the client's `cl_…` id. Your backend sends it in `X-Hevn-Account` to act for that client ([Acting as a client](https://docs.gethevn.com/developers/authentication.md#acting-as-a-client)).

## What your customer sees

HEVN Connect is not a full whitelabel. Your customer signs in to HEVN with Google or an email code, in a HEVN-hosted window that names your product, and approves payouts in the same window.

HEVN sets the window's title, logo and colours on request. The holder can also sign in to HEVN without your product.

To keep HEVN out of your interface, see [External wallets](https://docs.gethevn.com/external-wallets/overview.md). That integration is enabled per integrator, and your product provides the wallet and its signing flow.

## Integration steps

| Step | Calls | Page |
| - | - | - |
| Get access | Create a developer key, add your origins under **Allowed sites**, log in | [Authentication](https://docs.gethevn.com/developers/authentication.md), [Configure the window](https://docs.gethevn.com/connect/sign-in-with-hevn.md#configure-the-window) |
| Link a client | `POST /dapi/v1/connect/sessions` with `action: "link"`, the sign-in window, then `POST /dapi/v1/clients/link` | [Sign in with HEVN](https://docs.gethevn.com/connect/sign-in-with-hevn.md#link-an-account) |
| Verify the client | A business: `PUT /dapi/v1/client/kyb`, then `POST /dapi/v1/client/kyb/complete`. An individual: a `verify` session | [Clients and verification](https://docs.gethevn.com/developers/clients.md#write-the-document), [Verify an individual](https://docs.gethevn.com/connect/sign-in-with-hevn.md#verify-an-individual) |
| Take money in | `POST /dapi/v1/banks` requests a virtual account, `POST /dapi/v1/payins` quotes an incoming payment | [Virtual accounts](https://docs.gethevn.com/developers/virtual-accounts.md), [Payins](https://docs.gethevn.com/developers/payins.md) |
| Pay money out | `POST /dapi/v1/contacts`, `POST /dapi/v1/payouts`, then a `sign` session the holder approves | [Money movement](https://docs.gethevn.com/connect/money-movement.md) |
| Read the ledger | `GET /dapi/v1/client/balance`, `GET /dapi/v1/transactions` | [Balances and transactions](https://docs.gethevn.com/developers/balances-and-transactions.md) |

HEVN activates your integrator account before the first step works ([What HEVN must enable](https://docs.gethevn.com/developers/sandbox.md#what-hevn-must-enable)).

## Who signs

A payout booked for a linked client returns `authorization: "client"` and no `approval`. The holder signs it in a `sign` session ([Authorization values](https://docs.gethevn.com/developers/signing.md#authorization-values)).

| For a linked client | Your developer key | The holder, in the window |
| - | - | - |
| Read the profile, balance and ledger | Yes | n/a |
| Update phone and address, write and submit KYB, upload documents | Yes | n/a |
| Request virtual accounts, quote payins, save contacts | Yes | n/a |
| Book or preview a payout | Yes | n/a |
| Approve a payout | No. A confirm returns `403 account_not_controlled` | Yes, in a `sign` session |
| Verify an individual's identity | No | Yes, in a `verify` session |
| Create a swap, fund an escrow deal, open a sub account | No. Each returns `403 account_not_controlled` | Not offered in the window |

The refusals and their routes are in [Money movement](https://docs.gethevn.com/connect/money-movement.md#refusals). Who signs for your own integrator account is in [Accounts and control](https://docs.gethevn.com/developers/overview.md#accounts-and-control).

## What you build

| You build | HEVN provides |
| - | - |
| A button that opens the popup, and one static callback page | The sign-in window and the holder's wallet |
| Two server routes: create a session, exchange the code | The signed session URL and the one-time code |
| A server-side session that stores the `cl_…` id | Account records, virtual accounts through the partner bank, the ledger |
| The decision to pay and the prompt to the holder | Pricing, the approval screen and execution |

Bind each sign-in to the browser that started it, and exchange the code on your server ([Bind the session to this browser](https://docs.gethevn.com/connect/sign-in-with-hevn.md#3-bind-the-session-to-this-browser)). Do not accept a client id from the browser.

> [card] [Next: Quickstart](https://docs.gethevn.com/connect/quickstart.md)


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