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

# Rails and fees

> Products, payment methods with their currencies and identifiers, chain codes, and where each fee and rate is returned.

A payment method is the bank network a payin or payout uses, named by a value such as `sepa` or `ach`. Read what one client can use with `GET /dapi/v1/banks`, and what one contact can receive with `GET /dapi/v1/contacts/{contactId}/capabilities`.

[Virtual accounts](https://docs.gethevn.com/developers/virtual-accounts.md) defines product, rail, virtual account and account details.

## Products

Request a virtual account with `POST /dapi/v1/banks` and one of these products. The payer sends the listed currency over one of the listed methods.

| `product` | Methods | Currency |
| - | - | - |
| `us` | `ach`, `fedwire` | USD |
| `swift` | `swift` | USD |
| `eu` | `sepa` | EUR |
| `uk` | `ukfps` | GBP |
| `uae` | `uaefts` | AED |
| `br` | `pix` | BRL |
| `mx` | `spei` | MXN |
| `co` | `breb` | COP |
| `au` | `npp` | AUD |
| `ng` | `nip` | NGN |

`GET /dapi/v1/banks` returns the products one client can request, with `currency` and `method` for each. Use the response in code, not this table.

The `product` enum in the API reference has more codes than this table. A code the client cannot request is absent from its `GET /dapi/v1/banks` response, and `POST /dapi/v1/banks` with it returns `403 rail_not_available`.

## What each method needs

The identifiers are the `requisites.fields` of an active virtual account and the `fields` you send to save a contact.

`+` means each group is required. `or` means one of the alternatives in that group.

A contact can use any method in the table. A virtual account can use the methods from `ach` to `transfers_3_0`.

| Method | Currency | Market | Identifiers |
| - | - | - | - |
| `ach`, `fedwire` | USD | United States | `accountNumber` + `routingNumber` |
| `swift` | USD | International | `accountNumber` or `iban` + `bic` |
| `sepa` | EUR | Euro area | `iban` |
| `ukfps` | GBP | United Kingdom | `accountNumber` + `routingNumber` |
| `uaefts` | AED | United Arab Emirates | `iban` |
| `pix` | BRL | Brazil | `pixKey` or `accountNumber` |
| `spei` | MXN | Mexico | `accountNumber` or `iban` |
| `npp` | AUD | Australia | `accountNumber` + `routingNumber` |
| `nip` | NGN | Nigeria | `accountNumber` |
| `breb` | COP | Colombia | `paymentKey` or `accountNumber` |
| `pse` | COP | Colombia | `accountNumber` or `iban` |
| `transfers_3_0` | ARS | Argentina | `accountNumber` or `iban` |
| `bdt_ewallet` | BDT | Bangladesh | `financialInstitutionId` + `phoneNumber` |
| `bdt_local` | BDT | Bangladesh | `financialInstitutionId` + `branchNumber` + `accountNumber` |
| `bob_local` | BOB | Bolivia | `financialInstitutionId` + `accountNumber` + `accountKind` |
| `brl_local` | BRL | Brazil | `financialInstitutionId` + `branchNumber` + `accountNumber` + `accountKind` |
| `cad_eft` | CAD | Canada | `financialInstitutionId` + `accountNumber` + `routingNumber` |
| `clp_local` | CLP | Chile | `financialInstitutionId` + `accountNumber` + `accountKind` |
| `cny_alipay`, `cny_wechatpay` | CNY | China | `phoneNumber` |
| `cop_local` | COP | Colombia | `financialInstitutionId` + `accountNumber` + `accountKind` |
| `crc_local` | CRC | Costa Rica | `financialInstitutionId` + `iban` + `phoneNumber` |
| `dkk_local` | DKK | Denmark | `iban` |
| `dop_ewallet` | DOP | Dominican Republic | `financialInstitutionId` + `phoneNumber` |
| `dop_local` | DOP | Dominican Republic | `financialInstitutionId` + `accountNumber` + `accountKind` |
| `egp_local` | EGP | Egypt | `financialInstitutionId` + `iban` |
| `fednow`, `rtp` | USD | United States | `accountNumber` + `routingNumber` |
| `gtq_ewallet` | GTQ | Guatemala | `financialInstitutionId` + `phoneNumber` |
| `gtq_local` | GTQ | Guatemala | `financialInstitutionId` + `accountNumber` + `accountKind` + `phoneNumber` |
| `hkd_fps` | HKD | Hong Kong | `financialInstitutionId` + `accountNumber` |
| `hnl_local` | HNL | Honduras | `financialInstitutionId` + `accountNumber` + `accountKind` + `phoneNumber` |
| `idr_ewallet` | IDR | Indonesia | `financialInstitutionId` + `phoneNumber` |
| `idr_local` | IDR | Indonesia | `financialInstitutionId` + `accountNumber` |
| `ils_local` | ILS | Israel | `financialInstitutionId` + `iban` |
| `inr_local` | INR | India | `accountNumber` + `routingNumber` |
| `inr_upi` | INR | India | `accountNumber` |
| `jmd_local` | JMD | Jamaica | `financialInstitutionId` + `branchNumber` + `accountNumber` + `accountKind` + `phoneNumber` |
| `jpy_local` | JPY | Japan | `financialInstitutionId` + `branchNumber` + `accountNumber` + `phoneNumber` |
| `krw_local` | KRW | South Korea | `financialInstitutionId` + `accountNumber` |
| `myr_local` | MYR | Malaysia | `financialInstitutionId` + `accountNumber` |
| `nok_local` | NOK | Norway | `iban` |
| `php_ewallet` | PHP | Philippines | `financialInstitutionId` + `phoneNumber` |
| `php_local` | PHP | Philippines | `financialInstitutionId` + `accountNumber` |
| `pkr_ewallet` | PKR | Pakistan | `financialInstitutionId` + `phoneNumber` |
| `pkr_raast` | PKR | Pakistan | `financialInstitutionId` + `accountNumber` or `iban` |
| `pln_local` | PLN | Poland | `iban` |
| `sar_local` | SAR | Saudi Arabia | `financialInstitutionId` + `iban` |
| `sle_local` | SLE | Sierra Leone | `financialInstitutionId` + `phoneNumber` |
| `thb_local` | THB | Thailand | `financialInstitutionId` + `accountNumber` |
| `try_fast` | TRY | Türkiye | `financialInstitutionId` + `iban` |
| `tzs_local` | TZS | Tanzania | `financialInstitutionId` + `phoneNumber` |
| `ugx_local` | UGX | Uganda | `financialInstitutionId` + `phoneNumber` |
| `vnd_local` | VND | Vietnam | `financialInstitutionId` + `accountNumber` |
| `xof_local` | XOF | West African CFA franc zone | `financialInstitutionId` + `phoneNumber` |
| `zmw_local` | ZMW | Zambia | `financialInstitutionId` + `phoneNumber` |

An `_ewallet` method pays a mobile wallet identified by a phone number. A `_local` method is the domestic clearing system of that market. For both, save a contact and then book a payout.

Each `requisites` object and each contact has a `holder`. Its `type` is `individual` with `firstName` and `lastName`, or `business` with `businessName`. The holder does not replace the identifiers.

## Availability

| Narrowed by | Effect | Returned as |
| - | - | - |
| Your integrator agreement ([Going live](https://docs.gethevn.com/developers/sandbox.md#what-hevn-must-enable)) | Which products HEVN enables for you | `403 rail_not_available` on `POST /dapi/v1/banks` |
| The client's residency and legal form | Which of those products the client can request | The product is absent from `GET /dapi/v1/banks` |
| The account named in `accountId` | Which products can deliver to an external account or a sub account ([Virtual accounts](https://docs.gethevn.com/developers/virtual-accounts.md#deliver-to-an-account)) | `409 account_destination_unsupported` on `POST /dapi/v1/banks`, `403 rail_not_available` on `GET /dapi/v1/banks/{product}` |
| The client's verification state | Whether a requested virtual account can become `active` | `blockers[]` on the record: `kyb_required`, `verification_required`, `terms_required` |
| Rail status | Whether the rail accepts payments now | `503 provider_unavailable`, or `channel_unavailable` in a contact's `blockers[]` |

## Chain codes

A chain code names the chain in `crypto.chain` of a wallet [contact](https://docs.gethevn.com/developers/payouts.md#save-an-address-as-a-contact) and in `originChainId` of a quoted on-chain [payin](https://docs.gethevn.com/developers/payins.md#quote-an-on-chain-transfer).

A transfer to `baseSmartWallet` and a quoted on-chain payin need no virtual account and no verification. The client must be `ready`.

Read [`GET /dapi/v1/chains`](https://docs.gethevn.com/api-reference/catalog/list-supported-chains-and-tokens) at startup and do not hardcode the codes below.

Chain codes: `eth`, `bsc`, `avax`, `op`, `arb`, `pol`, `sol`, `base`, `gnosis`, `tron`, `xrp`, `zec`, `doge`, `ltc`, `btc`, `cardano`, `bera`, `sui`, `near`, `near_intents`, `xlayer`, `plasma`, `ton`, `stellar`, `monad`, `starknet`, `aptos`, `adi`, `bch`.

A payout to a chain other than Base is [routed](https://docs.gethevn.com/developers/payouts.md#a-routed-payout-is-priced).

## Fees

A fee or rate in this API is either declared before a payment exists or quoted on one payment. Rates are set per integrator. Ask HEVN for yours.

### Declared and quoted

| | Declared | Quoted |
| - | - | - |
| Meaning | A rate for a product or a contact | The terms of one payment |
| Returned by | `GET /dapi/v1/banks`, `GET /dapi/v1/banks/{product}/rate`, `GET /dapi/v1/contacts/{contactId}/capabilities`, `POST /dapi/v1/payouts/preview`, `GET /dapi/v1/rates` | `quote` on `POST /dapi/v1/payins` and `POST /dapi/v1/payouts` |
| Use | Display before the customer commits | Charge and reconcile |
| Binding | No. It can change | Yes, until `expiresAt` |

Do not bill from a stored declared rate.

### Fee fields

| Field | Returned by | Meaning |
| - | - | - |
| `feeBps`, `minimumDeposit` | `GET /dapi/v1/banks` | The payin fee is taken from the converted amount. A payment below `minimumDeposit` is returned to the payer. |
| `feeBps`, `fixedFee`, `minAmount`, `maxAmount` | `options[]` on `GET /dapi/v1/contacts/{contactId}/capabilities` | Indicative price and amount range for one contact. See [Payouts](https://docs.gethevn.com/developers/payouts.md#save-a-contact). |
| `feeAmount`, `feeCurrency`, `rate` | `quote` on a payin or a payout | The binding terms. See [Payins](https://docs.gethevn.com/developers/payins.md) and [Payouts](https://docs.gethevn.com/developers/payouts.md). |
| `expiresAt` | `quote` on a payout, top level of a payin | When the quoted terms stop applying. |

[`POST /dapi/v1/payouts/preview`](https://docs.gethevn.com/api-reference/transfers/create-an-outgoing-transfer-quote) prices a rail without a contact. A price from capabilities or preview is indicative. `POST /dapi/v1/payouts` repeats the checks and returns the binding quote.

To choose which side of a payment absorbs the fee, send `amount` or `amountTo` ([Conventions](https://docs.gethevn.com/developers/conventions.md#money)).

### Product rate

[`GET /dapi/v1/banks/{product}/rate`](https://docs.gethevn.com/api-reference/virtual-accounts/retrieve-the-receiving-conversion-rate) returns the indicative price of a payin on one product.

```json theme={null}
{ "currency": "EUR", "rate": "…", "fixedFee": "…", "fixedFeeCurrency": "EUR" }
```

### Market rate

[`GET /dapi/v1/rates?from=EUR&to=USDC`](https://docs.gethevn.com/api-reference/catalog/retrieve-a-market-reference-rate) returns the current market rate between two currencies or tokens.

```json theme={null}
{ "fromCurrency": "EUR", "toCurrency": "USDC", "rate": "1.14776038", "indicative": true }
```

A currency HEVN does not price returns `404 not_found`.

### Not a fee

| Item | Why |
| - | - |
| Gas | Gas on Base is paid by an ERC-4337 paymaster. A quote has no network fee line, and the client's wallet needs no ETH. A transfer an external account sends is paid for by the customer's wallet. |
| A move with a sub account | One for one, with no fee ([Swaps](https://docs.gethevn.com/developers/swaps.md#sub-account-moves)). |
| Escrow `feeBps` | Your take rate on `capture` and `charge`, deducted from the captured amount before the seller is paid. The ceiling is fixed when the deal is created. See [Escrow](https://docs.gethevn.com/developers/escrow.md#the-matrix). |

> [card] [Next: Errors](https://docs.gethevn.com/developers/reference/errors.md)


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