Making Privy API requests idempotent with idempotency keys
Idempotency keys ensure your API requests to Privy aren’t executed multiple times, preventing duplicated transactions. When provided, Privy guarantees that a request with the same idempotency key will only be processed once within a 24-hour window.
Any POST request that triggers state changes or transactions
Scenarios where network issues might cause request retries
Critical operations where duplicate execution would be problematic
While optional, idempotency keys are strongly recommended for all non-idempotent operations in production environments to prevent double-spends and duplicate transactions.
When Privy receives a request with a new idempotency key, it processes the request normally and
stores both the request details and response for 24 hours.
2
Subsequent Requests
If the same idempotency key is used again within 24 hours:
If the request body matches the original request: Privy returns the stored response without re-executing the operation
If the request body differs: Privy returns a 400 error indicating invalid use of the key
3
Key Expiration
After 24 hours, idempotency keys expire. Using an expired key will result in normal request
processing.
Changing any part of the request body while reusing an idempotency key will result in an error.
Each unique operation should have its own idempotency key.
import {PrivyClient} from '@privy-io/server-auth';import {v4 as uuidv4} from 'uuid';const client = new PrivyClient($PRIVY_APP_ID, $PRIVY_APP_SECRET);// Generate a unique idempotency keyconst idempotencyKey = uuidv4();const res = await client.walletApi.ethereum.sendTransaction({ walletId: $WALLET_ID, idempotencyKey, // Pass the idempotency key to prevent duplicate transactions transaction: { to: '0xE3070d3e4309afA3bC9a6b057685743CF42da77C', value: '0x2386F26FC10000', chainId: 8453 }});
For critical operations, store the idempotency key alongside your transaction records. This allows
you to safely retry failed operations with the same key.