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

# Remote transfers

> Let a server or script send USDC from your own HEVN account, bounded by an onchain spend permission you grant to one key.

Remote transfers let a server, a script or an agent you run send USDC from your own HEVN account
without a person in the loop. You create a **remote transfer key** in the app, grant it a spend
permission from your smart wallet, and the key can then pay contacts, invoices, payout quotes and
email addresses over HTTP — never more than the allowance you granted for the current period.

> [!WARNING]
>
> **For advanced use only.** A remote transfer key moves money with no approval step. For everyday
> payments use the app, or the HEVN assistant, which only files transfer requests that you approve
> yourself. Reach for a key only when a program you operate must pay on its own, and grant it the
> smallest allowance that does the job.

This tab is about your **own** account. If you are building a product that creates and operates
accounts for your customers, you want the [Whitelabel](https://docs.gethevn.com/whitelabel/overview.md) API instead: it uses a
developer key and a different credential model, and the two never mix.

## How a transfer is authorized

```mermaid theme={null}
flowchart LR
    K["Remote transfer key<br/>rsl_…"] -->|"derives"| E["Server-held signer"]
    E -->|"owns"| S["Spender wallet<br/>(walletAddress)"]
    W["Your Base smart wallet"] -->|"spend permission:<br/>allowance per period"| S
    S -->|"spend + USDC transfer"| R["Receiving wallet"]
```

| Piece | What it is |
| - | - |
| **Remote transfer key** | A secret starting `rsl_`, shown once when you create it. HEVN stores only its SHA-256 hash. Keys created before the rename start `mcp_` and keep working |
| **Spender wallet** | A Coinbase smart wallet of its own, one per key, returned as `walletAddress`. Its owners are a signer HEVN derives from your key and Coinbase's `SpendPermissionManager`. HEVN predicts the address at creation; the wallet deploys with the key's first transfer |
| **Spend permission** | An onchain allowance you sign from your smart wallet, naming the spender wallet, with an amount per period. It is the real limit — see [Shared account access](https://docs.gethevn.com/general/shared-access.md#limited-access-spend-permissions) |
| **Transfer** | One sponsored ERC-4337 user operation from the spender wallet: `SpendPermissionManager.spend` pulls the amount out of your wallet, then a USDC `transfer` sends it on. You pay no gas |

Without an active spend permission the key cannot move a cent: every transfer answers
`403` until you grant one. The key never touches your own signing key, which stays in
[Privy](https://docs.gethevn.com/general/privy-wallets.md).

## Limits that apply to every transfer

| Limit | Where it is enforced | What happens when it is hit |
| - | - | - |
| **Spend permission allowance** | Onchain, by `SpendPermissionManager` | `400 Insufficient spend allowance` until the period resets |
| **`maxSpend`**, optional | HEVN, a lifetime ledger per key | `403 Spend limit exceeded for this API key` |
| **IP allowlist**, optional | HEVN, on every request | `403 IP not allowed` |
| **Rate limit** | HEVN, 60 requests per hour per key on `/transfer`, `/transfer_to_user` and `/resolve_address` | `429` with `Retry-After` |

The allowance is the only limit that holds even if HEVN itself misbehaves. `maxSpend` and the
allowlist are backend checks that narrow it further.

## A transfer runs at most once

Every transfer carries an ERC-4337 nonce derived from a payment id, and the spender wallet accepts each
nonce once. The payment id is `<keyId>_<reference>`, where the reference is the first of:

1. the `invoiceId` you pay,
2. the `quoteId` you fund,
3. the `Idempotency-Key` header you send.

A second request with the same payment id never executes: it answers `409 This transfer was already
sent`. That refusal comes from the wallet itself, so it holds across retries, restarts and concurrent
requests. Two consequences follow:

* A contact transfer **without** an `Idempotency-Key` gets a random reference and is never
  deduplicated. Always send the header when you pay a contact.
* The reference is scoped to the key. The same invoice paid through two different keys is two
  transfers.

## What you can do with a key

| Operation | Route |
| - | - |
| Read your USDC balance and the key's remaining allowance | `GET /get_balance` |
| Find the HEVN wallet for an email | `GET /resolve_address` |
| Pay a contact, an invoice or a payout quote | `POST /transfer` |
| Pay any email address, creating its HEVN account if needed | `POST /transfer_to_user` |
| List the email transfers this account made | `GET /transfers` |

There are no scopes: a valid key can call every route above. Treat it like a password with a budget.

> [card] [Next: Keys and permissions](https://docs.gethevn.com/remote-transfers/keys.md)
>
> Create a key, grant its spend permission, restrict it, and revoke it.


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