Set a reference ID

A reference_id is an optional, developer-provided identifier that can be attached to a wallet action for reconciliation with your own internal records. It must be unique per app and can be up to 64 characters. This is useful when your request times out or you never receive the response: because you chose the reference_id yourself, you can still find the action afterwards without knowing the ID Privy assigned it. The reference_id is included in all wallet action payloads, including webhook events, and can be used to fetch a wallet action by its reference ID.

A reference_id is not an idempotency key. Reusing a value returns a 400 rather than replaying the original action, so a second request with different parameters is never silently swallowed. For at-most-once delivery, use the privy-idempotency-key header instead.

Supported actions

The reference_id parameter is supported on the following wallet actions:

Pass the reference_id field in the request body when creating the action.

Transfer
Swap
Earn deposit

curl --request POST \
  --url https://api.privy.io/v1/wallets/{wallet_id}/transfer \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
  "reference_id": "order-abc-123",
  "amount": "10.5",
  "source": {
    "asset": "usdc",
    "chain": "base"
  },
  "destination": {
    "address": "<recipient-address>"
  }
}'

curl --request POST \
  --url https://api.privy.io/v1/wallets/{wallet_id}/swap \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
  "reference_id": "order-abc-123",
  "base_amount": "1000000000000000000",
  "amount_type": "exact_input",
  "source": {
    "asset_address": "native",
    "caip2": "eip155:8453"
  },
  "destination": {
    "asset_address": "<token-contract-address>",
    "caip2": "eip155:8453"
  }
}'

curl --request POST \
  --url https://api.privy.io/v1/wallets/{wallet_id}/earn/ethereum/deposit \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
  "reference_id": "order-abc-123",
  "vault_id": "cm7oxq1el000e11o8iwp7d0d0",
  "amount": "1.5"
}'

Looking up wallet actions by reference ID

Once a reference_id has been set, your app can look up the associated wallet action using the get wallet action by external ID endpoint. Unlike the per-wallet endpoints, this searches across every wallet in your app, so you do not need to know which wallet performed the action:

curl --request GET \
  --url 'https://api.privy.io/v1/actions?reference_id=order-abc-123' \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'privy-app-id: <privy-app-id>'

Pass ?include=steps to expand step-level details in the response. If no action matches, the endpoint returns 200 with an empty list rather than a 404, so a caller polling for an action it may not have created yet does not have to treat 404 as a success case. Your app can also retrieve the action directly by its Privy-assigned ID using the get wallet action endpoint. The reference_id is included in the response.

Duplicate reference IDs

A reference_id must be unique per app. Creating a second wallet action with a value your app has already used returns a 400:

{
  "error": "A wallet action with this reference_id already exists for this app"
}

The action is rejected before anything is signed or broadcast, so a duplicate is always safe to retry with a fresh value.

Webhooks

All wallet action webhook events include the reference_id field in their payload when one was provided. This lets your app match incoming webhook notifications to your internal records without an additional API call.

Signatures and transactions

Wallet actions

Signing and RPC

Intents

Transactions

Supported actions

Looking up wallet actions by reference ID

Duplicate reference IDs

Webhooks

​Supported actions

​Looking up wallet actions by reference ID

​Duplicate reference IDs

​Webhooks

Supported actions

Looking up wallet actions by reference ID

Duplicate reference IDs

Webhooks