Get wallet action by reference ID
curl --request GET \
--url https://api.privy.io/v1/actions \
--header 'Authorization: Basic <encoded-value>' \
--header 'privy-app-id: <privy-app-id>'HttpResponse<String> response = Unirest.get("https://api.privy.io/v1/actions")
.header("privy-app-id", "<privy-app-id>")
.header("Authorization", "Basic <encoded-value>")
.asString();const options = {
method: 'GET',
headers: {'privy-app-id': '<privy-app-id>', Authorization: 'Basic <encoded-value>'}
};
fetch('https://api.privy.io/v1/actions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.privy.io/v1/actions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"privy-app-id: <privy-app-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.privy.io/v1/actions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("privy-app-id", "<privy-app-id>")
req.Header.Add("Authorization", "Basic <encoded-value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"actions": [
{
"id": "<string>",
"status": "pending",
"wallet_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"type": "swap",
"caip2": "<string>",
"input_token": "<string>",
"output_token": "<string>",
"input_amount": "<string>",
"output_amount": "<string>",
"reference_id": "<string>",
"failure_reason": {
"message": "<string>",
"details": "<unknown>"
},
"steps": [
{
"type": "evm_transaction",
"status": "preparing",
"caip2": "<string>",
"transaction_hash": "<string>",
"failure_reason": {
"message": "<string>",
"details": "<unknown>"
},
"finalized": true,
"gas_credits_charged_usd": "<string>"
}
],
"destination_caip2": "<string>",
"destination_address": "<string>",
"estimated_fees": [
{
"type": "privy",
"recipient": "0x1234567890abcdef1234567890abcdef12345678",
"amount": "0.20"
}
],
"estimated_gas": {
"base_amount": "100000000000000",
"amount": "0.0001",
"gas_asset": "ETH"
},
"fees": [
{
"type": "privy",
"recipient": "0x1234567890abcdef1234567890abcdef12345678",
"amount": "0.20"
}
],
"gas": {
"base_amount": "100000000000000",
"amount": "0.0001",
"gas_asset": "ETH"
}
}
]
}Wallet actions
Get wallet action by external ID
Look up a wallet action by reference_id across every wallet in the app. Returns an empty list if no action matches. Use ?include=steps to include step-level details.
GET
/
v1
/
actions
Get wallet action by reference ID
curl --request GET \
--url https://api.privy.io/v1/actions \
--header 'Authorization: Basic <encoded-value>' \
--header 'privy-app-id: <privy-app-id>'HttpResponse<String> response = Unirest.get("https://api.privy.io/v1/actions")
.header("privy-app-id", "<privy-app-id>")
.header("Authorization", "Basic <encoded-value>")
.asString();const options = {
method: 'GET',
headers: {'privy-app-id': '<privy-app-id>', Authorization: 'Basic <encoded-value>'}
};
fetch('https://api.privy.io/v1/actions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.privy.io/v1/actions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"privy-app-id: <privy-app-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.privy.io/v1/actions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("privy-app-id", "<privy-app-id>")
req.Header.Add("Authorization", "Basic <encoded-value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"actions": [
{
"id": "<string>",
"status": "pending",
"wallet_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"type": "swap",
"caip2": "<string>",
"input_token": "<string>",
"output_token": "<string>",
"input_amount": "<string>",
"output_amount": "<string>",
"reference_id": "<string>",
"failure_reason": {
"message": "<string>",
"details": "<unknown>"
},
"steps": [
{
"type": "evm_transaction",
"status": "preparing",
"caip2": "<string>",
"transaction_hash": "<string>",
"failure_reason": {
"message": "<string>",
"details": "<unknown>"
},
"finalized": true,
"gas_credits_charged_usd": "<string>"
}
],
"destination_caip2": "<string>",
"destination_address": "<string>",
"estimated_fees": [
{
"type": "privy",
"recipient": "0x1234567890abcdef1234567890abcdef12345678",
"amount": "0.20"
}
],
"estimated_gas": {
"base_amount": "100000000000000",
"amount": "0.0001",
"gas_asset": "ETH"
},
"fees": [
{
"type": "privy",
"recipient": "0x1234567890abcdef1234567890abcdef12345678",
"amount": "0.20"
}
],
"gas": {
"base_amount": "100000000000000",
"amount": "0.0001",
"gas_asset": "ETH"
}
}
]
}Use this endpoint to look up a wallet action by a developer-provided
If no action matches the given
reference_id. This is useful for
reconciling actions initiated via transfer,
swap or earn with your internal records.
Unlike get wallet action and
list all wallet actions, this endpoint searches across every wallet in
your app, so you do not need to know which wallet performed the action.
To set a
reference_id on a wallet action, pass it in the request body when creating the action.
The reference_id must be unique per app and can be up to 64 characters. See Set a reference
ID for examples.reference_id, the endpoint returns 200 with an empty list rather than a
404. Pass ?include=steps to expand step-level details in the response.Authorizations
Basic Auth header with your app ID as the username and your app secret as the password.
Headers
ID of your Privy app.
Query Parameters
Developer-provided reference ID to look the wallet action up by.
Required string length:
1 - 64Include step-level details in the response.
Available options:
steps Response
200 - application/json
List containing the matching wallet action, or empty if none matched.
A list of wallet actions.
actions
(SwapActionResponse · object | TransferActionResponse · object | EarnDepositActionResponse · object | EarnWithdrawActionResponse · object | EarnIncentiveClaimActionResponse · object | EarnFeeCollectActionResponse · object | PayoutResponse · object)[]
required
Response for a swap action.
- SwapActionResponse
- TransferActionResponse
- EarnDepositActionResponse
- EarnWithdrawActionResponse
- EarnIncentiveClaimActionResponse
- EarnFeeCollectActionResponse
- PayoutResponse
Show child attributes
Show child attributes
Was this page helpful?

