Skip to main content

​
Why

You send a request, but the network drops the response before it reaches you. Did it go through? With an idempotency key you can just retry: the same key returns the original result instead of doing the work a second time.

​
How it works

Every write takes an idempotencyKey — a unique ID you generate, like a UUID — in the request body: 
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"
  }'
  • The first call with a key runs the operation.
  • The same key with the same body returns that original result — the operation runs once, however many times you retry.

​
Two rules

  1. Generate one new key per operation — each transfer, payment, settlement, reversal, adjustment, and pay-in gets its own.
  2. Reuse a key only to retry that exact call. For a genuinely new operation, generate a new key.
A key is required on transfers, payment requests (create, settle, reverse, and update), pay-in sessions, and virtual bank accounts.
Save the key before you send the request. If your process restarts mid-flight, the retry reuses the same key and lands exactly once.

​
Next steps

API conventions

Pagination, versioning, and the shared idempotency rules.

Payment requests

Reserve, settle, reverse — each with its own key.