Idempotency keys

When taking actions with a server wallet, your application will likely want to ensure that API requests to the wallet cannot be sent multiple times and cause duplicated transactions.

To enable idempotency, Privy accepts an idempotency key on all POST requests to server wallet endpoints. Idempotency keys identify unique requests and support idempotency retries in the case of network failure or no response.

How idempotency keys work

When Privy receives a request with an idempotency key, the API will first determine if that idempotency key has been sent on a previous request within the past 24 hours. Then:

• If the key is being used for the first time in the past 24 hours, Privy will process the request and store the response. Privy will store the response regardless if the request succeeds or errors.
• If the key matches the key from previous request in the past 24 hours:
  • If the request body matches the request body of the previous request, the request will not be re-attempted and the response body and status code from the previous request will be returned verbatim.
  • If the request body differs from the request body of the previous request, Privy will return a 400 error indicating invalid use of the idempotency key.

This ensures you can retry requests without risk of executing actions twice (e.g. double spends), as long as they are sent with the same idempotency key.

TIP

Idempotency keys are valid for 24 hours before expiring. If a request includes an idempotency key that was last used more than 24 hours ago, the request will be processed as a new request and not idempotently.

Creating the idempotency key

Generate a unique, random idempotency key for the transaction. This may be a string up to 256 characters long. We recommend using a V4 UUID or similar.

Including the key in your request

Once you have created an idempotency key for a unique request, you must include the key on the request to have Privy treat it as unique and handle further uses of the key idempotently.

Using the Privy SDK

Pass your idempotency key to the walletApi.create and walletApi.rpc methods as an optional idempotencyKey parameter. As an example, you might include an idempotency key like so:

const {data} = await privy.walletApi.rpc({
  walletId: 'insert-wallet-id',
  idempotencyKey: 'insert-idempotency-key'
  caip2: 'eip155:8453',
  method: 'eth_sendTransaction',
  params: {
    transaction: {
      to: '0xE3070d3e4309afA3bC9a6b057685743CF42da77C',
      value: 100000,
      chainId: 8453,
    },
  },
});

Using the REST API

Pass your idempotency key as a 'privy-idempotency-key' request header.