Skip to main content

​
The problem

You send a request to create a transfer, but the network drops the response before it reaches you. Did it go through? If you simply retry, you risk doing it twice — a double transfer or double charge.

​
The solution

Every create request takes an idempotencyKey: a unique ID you generate (a UUID works well). The rule is simple:
  • First request with a key → the operation runs.
  • Retry with the same key → you get the original result back. The operation never happens twice.
curl --request POST \
  --url https://api.venlyfinance.com/v1/accounts/{senderAccountId}/transfers/crypto \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "receiverAccountId": "c3b2a1f0-9d8c-4e3a-bf21-1a2b3c4d5e60",
    "chain": "BASE",
    "asset": "USDC",
    "amount": 25,
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

​
Rules of thumb

  • Generate one new key per distinct operation — each new transfer, payment, or pay-in gets its own.
  • Reuse the same key only when retrying that exact operation.
  • A key is required on: transfers, payment requests, pay-in sessions, and virtual bank accounts.
Save the key alongside your operation before you send it. That way, if your process crashes mid-request, the retry can reuse the same key.