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

# How money moves

> How USDC enters and leaves a HEVN wallet, and which credential authorizes each step.

Money in a HEVN account is USDC in a Base smart wallet. A payin ends when USDC arrives in the wallet, and a payout starts with a transfer the holder's key signs.

## Login and authorization

The holder signs in with Privy by email or Google, and the Privy key signs a challenge message offchain at no gas cost. HEVN checks the signer against the holder's Privy address and issues a short-lived JWT.

| | Platform authorization | Money authorization |
| - | - | - |
| Credential | HEVN JWT | Signature from a wallet owner key, or from a [remote transfer key](https://docs.gethevn.com/general/remote-transfers.md) within its onchain allowance |
| Grants | Contacts, invoices, contracts, account details, verification (KYC and KYB), transaction reports, analytics, balances, team administration | Transfers and any onchain state change |
| Issued by | HEVN | The signer's key, per operation |

The JWT cannot move money.

## Payins

| Source | Path |
| - | - |
| Bank transfer | The payer sends fiat to the account details. The partner bank converts it and delivers USDC to the wallet address. |
| USDC on Base | Send to the wallet address shown in the app. |
| Other chain or token | Send to a one-time address from a cross-chain quote. See [Cross-chain](#cross-chain). |

The partner bank opens account details (an account number or IBAN) for one holder and links them to that holder's wallet address. A payin is complete when the USDC arrives on Base.

## Fiat payouts

1. Create a payout to a bank beneficiary in the app or through the API. The JWT authorizes this call, which returns a quote and moves no money.
2. The payout returns a one-time address. The app checks its [signature](https://docs.gethevn.com/general/security-model.md#signed-responses) before showing it.
3. The holder's key signs the USDC transfer from the wallet to that address.
4. After the USDC arrives, the partner bank pays the beneficiary.

Each one-time address serves one payout. The transfer is public on [Basescan](https://basescan.org).

## Cross-chain

Payins from other chains and payouts to them (BTC, ETH, SOL, USDT on TRON and others) are routed swaps.

1. HEVN requests a quote and returns a one-time address on the origin chain. The fee is in the quote.
2. The app validates the address against the quote before showing it.
3. The sender pays the one-time address, and the route delivers the destination asset.

If a swap fails, for example on an expired quote or a mismatched transfer, a payin is refunded to the sender's refund address and a payout to the wallet.

> [card] [Next: Security model](https://docs.gethevn.com/general/security-model.md)


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