> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfers

> Move funds from one account to another — fiat-denominated or crypto-denominated — and track them to completion.

A transfer moves funds from one account to another. You always send to a **receiver account** — by its Venly `receiverAccountId`, or by your own `receiverExternalId` if you set one on the account. There are two endpoints, differing only in how you denominate the amount.

## Fiat vs crypto

|                | [Fiat transfer](/api-reference/Finance-API/transfers/create-fiat-transfer) | [Crypto transfer](/api-reference/Finance-API/transfers/create-crypto-transfer) |
| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| You specify    | a fiat `currency` + `amount`                                               | a crypto `asset` + `chain` + `amount`                                          |
| Settles in     | the underlying stablecoin, on-chain                                        | the named asset, on-chain                                                      |
| Response extra | a `fiatOrigin` block (currency, amount, exchange rate)                     | —                                                                              |

Both settle on-chain and return a `transactionHash`.

## Prerequisites

The **sender** account must be [verified](/guides/finance/kyc-verification). For **self-custody** senders, the wallet must also be active with an allowance to the orchestration wallet — see [Approving transfers without gas](/guides/finance/permits-and-allowances).

<Warning>**Both** the sender **and** the receiver account must be KYC `VERIFIED`. A transfer to an unverified receiver is rejected with `422 receiver-kyc-not-verified` — verify the receiver before sending. Transfers are also scoped to a single company; you cannot transfer to an account in another company.</Warning>

## Create a fiat transfer

```bash theme={null}
curl -X POST https://api.venlyfinance.com/v1/accounts/{senderAccountId}/transfers/fiat \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverAccountId": "c3b2a1f0-9d8c-4e3a-bf21-1a2b3c4d5e60",
    "currency": "USD",
    "amount": 25.0,
    "description": "Invoice settlement",
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'
```

```json Response theme={null}
{
  "success": true,
  "result": {
    "id": "a1b2c3d4-e5f6-4789-9abc-def012345678",
    "senderAccountId": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
    "receiverAccountId": "c3b2a1f0-9d8c-4e3a-bf21-1a2b3c4d5e60",
    "chain": "BASE",
    "asset": "USDC",
    "amount": 25.0,
    "fiatOrigin": { "currency": "USD", "amount": 25.0, "exchangeRate": 1 },
    "status": "COMPLETED",
    "transactionHash": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
  }
}
```

A **crypto transfer** is the same call against `/transfers/crypto`, sending `chain` + `asset` instead of `currency` (and the response omits `fiatOrigin`).

## Status lifecycle

A transfer's `status` is `PENDING → COMPLETED`, or `FAILED` (with an `errorMessage`). Settlement is on-chain, so poll [Get a transfer](/api-reference/Finance-API/transfers/get-transfer-details) — or [List transfers](/api-reference/Finance-API/transfers/list-transfers-for-account), filtering by `accountRole` (`SENDER`/`RECEIVER`) and `status`.

## Idempotency

Every transfer takes a unique `idempotencyKey`; retrying with the same key returns the original transfer instead of sending again. See [Safe retries with idempotency keys](/guides/finance/idempotency).

## Next steps

<CardGroup cols={2}>
  <Card title="Create a crypto transfer" icon="money-bill-transfer" href="/api-reference/Finance-API/transfers/create-crypto-transfer">
    The endpoint reference and full schema.
  </Card>

  <Card title="Payment requests" icon="money-check-dollar" href="/guides/finance/payment-requests">
    Reserve and settle a payment from an account's balance.
  </Card>
</CardGroup>