Skip to main content
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 transferCrypto transfer
You specifya fiat currency + amounta crypto asset + chain + amount
Settles inthe underlying stablecoin, on-chainthe named asset, on-chain
Response extraa 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. The receiver account must be verified too.

​
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 failureCode / failureReason). 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.