> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/wallets/actions/webhooks),
and can be used to [fetch a wallet action by its reference ID](/api-reference/wallets/actions/external-id).

<Note>
  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.
</Note>

## Supported actions

The `reference_id` parameter is supported on the following wallet actions:

* [Transfer](/api-reference/wallets/transfer/index)
* [Swap](/api-reference/wallets/swap/quote)
* [Earn deposit](/api-reference/wallets/earn/deposit)
* [Earn withdraw](/api-reference/wallets/earn/withdraw)
* [Earn incentive claim](/api-reference/wallets/earn/incentive-claim)
* [Earn fee collect](/api-reference/wallets/earn/fees-collect)

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

<Tabs>
  <Tab title="Transfer">
    ```bash theme={"system"}
    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>"
      }
    }'
    ```
  </Tab>

  <Tab title="Swap">
    ```bash theme={"system"}
    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"
      }
    }'
    ```
  </Tab>

  <Tab title="Earn deposit">
    ```bash theme={"system"}
    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"
    }'
    ```
  </Tab>
</Tabs>

## 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](/api-reference/wallets/actions/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:

```bash theme={"system"}
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](/api-reference/wallets/actions/get) 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`:

```json theme={"system"}
{
  "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](/wallets/actions/webhooks) 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.