> ## 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 has two products and they authorize money differently. 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 backend holds a developer key, signs on behalf of client accounts it created, and HEVN co-signs. Never mix the two models in an answer.
> 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 an account the integrator created; 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. 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.
</Warning>

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](/whitelabel/overview) 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](/general/shared-access#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](/general/privy-wallets).

## 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 title="Next: Keys and permissions" icon="arrow-right" href="/remote-transfers/keys">
  Create a key, grant its spend permission, restrict it, and revoke it.
</Card>


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