Transfers

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	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. For self-custody senders, the wallet must also be active with an allowance to the orchestration wallet — see Approving transfers without gas.

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.

Create a fiat transfer

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"
  }'

Response

{
  "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 — or List transfers, 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.

Next steps

Create a crypto transfer

The endpoint reference and full schema.

Payment requests

Reserve and settle a payment from an account’s balance.

Approving transfers without gas Payment requests

⌘I

Overview

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Wallets

Payment Requests

Fiat to Crypto Payment Sessions

Permits

Allowances

Reference

Transfers

Fiat vs crypto

Prerequisites

Create a fiat transfer

Status lifecycle

Idempotency

Next steps

Create a crypto transfer

Payment requests

​Fiat vs crypto

​Prerequisites

​Create a fiat transfer

​Status lifecycle

​Idempotency

​Next steps

Create a crypto transfer

Payment requests

Fiat vs crypto

Prerequisites

Create a fiat transfer

Status lifecycle

Idempotency

Next steps