--- title: "Get wallet action by reference ID" method: GET path: "/v1/actions" tags: ["Actions"] --- # Get wallet action by reference ID `GET /v1/actions` ## Request - Base URL: `https://api.privy.io` - URL: `https://api.privy.io/v1/actions` - Auth: HTTP basic 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. ## Query parameters - `reference_id` string, required: Developer-provided reference ID to look the wallet action up by. - `include` 'steps': Include step-level details in the response. ## Headers - `privy-app-id` string, required: ID of your Privy app. ## Response `200` List containing the matching wallet action, or empty if none matched. - ListActions: A list of wallet actions. - `actions` WalletActionResponse[], required - union: Response for a wallet action, discriminated on type. - object: Response for a swap action. - `id` string, required: The ID of the wallet action. - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required: The current status of the wallet action. - `wallet_id` string, required: The ID of the wallet involved in the action. - `created_at` string, date-time, required: ISO 8601 timestamp of when the wallet action was created. - `reference_id` string, nullable: Developer-provided reference ID, if one was included in the request. - `failure_reason` object: Top-level failure context for the wallet action. Present on rejected or failed actions when available. - `message` string, required: Human-readable failure message. - `details` unknown - `steps` WalletActionStep[]: The steps of the wallet action. Only returned if `?include=steps` is provided. - union: A step within a wallet action, representing a single onchain action. - object: A wallet action step consisting of an EVM transaction. - … - object: A wallet action step consisting of an EVM user operation. - … - object: A wallet action step consisting of an SVM (Solana) transaction. - … - object: A wallet action step consisting of a TVM (Tron) transaction. - … - object: A wallet action step representing a cross-chain/cross-asset fill by an external provider. - … - object: A wallet action step representing a transaction executed by a custodian (e.g. Bridge). - … - object: A wallet action step representing a Tempo Zone settlement on its parent chain. - … - `type` 'swap', required - `caip2` string, required: CAIP-2 chain identifier for the swap. - `input_token` string, required: Token address or "native" for the token being sold. - `output_token` string, required: Token address or "native" for the token being bought. - `input_amount` string, nullable, required: Exact base-unit amount of input token. Populated after on-chain confirmation. - `output_amount` string, nullable, required: Exact base-unit amount of output token. Populated after on-chain confirmation. - `destination_caip2` string: Destination chain CAIP-2 identifier. Present for cross-chain swaps. - `destination_address` string: Recipient address for the swap. Present for newly created swaps; may be absent for older swap actions. - `estimated_fees` FeeLineItem[], nullable: Estimated fee breakdown from the provider quote. Only present for cross-chain swaps. Populated after on-chain confirmation. - union: An individual fee assessed on a transfer. - object: Estimated fee paid to the relayer. - … - object: Estimated fee paid to Privy. - … - object: Estimated fee paid to the developer. - … - `estimated_gas` Gas: Gas cost for a blockchain action. Includes both raw base-unit amount and a human-readable decimal string, plus the gas token symbol. - `base_amount` string, required: Gas cost in the gas token's base units (e.g. wei). - `amount` string, required: Gas cost in the gas token as a human-readable decimal string (e.g. "0.0001"). - `gas_asset` string, required: Gas token symbol (e.g. "ETH", "USDC"). - `fees` FeeLineItem[], nullable: Actual fees paid for the swap. Populated after on-chain confirmation. Only present for cross-chain swaps. - union: An individual fee assessed on a transfer. - object: Estimated fee paid to the relayer. - … - object: Estimated fee paid to Privy. - … - object: Estimated fee paid to the developer. - … - `gas` Gas: Gas cost for a blockchain action. Includes both raw base-unit amount and a human-readable decimal string, plus the gas token symbol. - `base_amount` string, required: Gas cost in the gas token's base units (e.g. wei). - `amount` string, required: Gas cost in the gas token as a human-readable decimal string (e.g. "0.0001"). - `gas_asset` string, required: Gas token symbol (e.g. "ETH", "USDC"). - object: Response for a transfer action. - `id` string, required: The ID of the wallet action. - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required: The current status of the wallet action. - `wallet_id` string, required: The ID of the wallet involved in the action. - `created_at` string, date-time, required: ISO 8601 timestamp of when the wallet action was created. - `reference_id` string, nullable: Developer-provided reference ID, if one was included in the request. - `failure_reason` object: Top-level failure context for the wallet action. Present on rejected or failed actions when available. - `message` string, required: Human-readable failure message. - `details` unknown - `steps` WalletActionStep[]: The steps of the wallet action. Only returned if `?include=steps` is provided. - union: A step within a wallet action, representing a single onchain action. - object: A wallet action step consisting of an EVM transaction. - … - object: A wallet action step consisting of an EVM user operation. - … - object: A wallet action step consisting of an SVM (Solana) transaction. - … - object: A wallet action step consisting of a TVM (Tron) transaction. - … - object: A wallet action step representing a cross-chain/cross-asset fill by an external provider. - … - object: A wallet action step representing a transaction executed by a custodian (e.g. Bridge). - … - object: A wallet action step representing a Tempo Zone settlement on its parent chain. - … - `type` 'transfer', required - `amount_type` 'exact_input' | 'exact_output': Whether the amount refers to the input token or output token. - `source_asset` string: Asset identifier (e.g. "usdc", "eth"). Present when the transfer was initiated with a named asset; omitted for custom-token transfers. - `source_asset_address` string: Token contract address (EVM) or mint address (Solana). Present when the transfer was initiated with `asset_address`. - `source_asset_decimals` integer: Number of decimals for the transferred token. Present when the transfer was initiated with `asset_address` and the decimals were resolved on-chain. - `source_amount` string: Decimal amount sent on the source chain (e.g. "1.5"). For exact_output cross-chain transfers, null until fill confirmation. - `source_chain` string, required: Chain name (e.g. "tempo", "base"). - `destination_address` string, required: Recipient address. - `destination_asset` string: Destination asset for cross-asset transfers. Omitted for same-asset transfers. - `destination_chain` string: Destination chain for cross-chain transfers. Omitted for same-chain transfers. - `destination_amount` string, nullable, required: Amount received on the destination chain. For exact_output cross-chain transfers, set at creation (the guaranteed exact amount). For exact_input cross-chain transfers, null until fill confirmation. - `estimated_fees` FeeLineItem[], nullable: Estimated fee breakdown from the provider quote. Only present for cross-chain or cross-asset transfers. Populated after on-chain confirmation. - union: An individual fee assessed on a transfer. - object: Estimated fee paid to the relayer. - … - object: Estimated fee paid to Privy. - … - object: Estimated fee paid to the developer. - … - `estimated_gas` Gas: Gas cost for a blockchain action. Includes both raw base-unit amount and a human-readable decimal string, plus the gas token symbol. - `base_amount` string, required: Gas cost in the gas token's base units (e.g. wei). - `amount` string, required: Gas cost in the gas token as a human-readable decimal string (e.g. "0.0001"). - `gas_asset` string, required: Gas token symbol (e.g. "ETH", "USDC"). - `fees` FeeLineItem[], nullable: Actual fees paid for the transfer. Populated after on-chain confirmation. Only present for cross-chain transfers. - union: An individual fee assessed on a transfer. - object: Estimated fee paid to the relayer. - … - object: Estimated fee paid to Privy. - … - object: Estimated fee paid to the developer. - … - `gas` Gas: Gas cost for a blockchain action. Includes both raw base-unit amount and a human-readable decimal string, plus the gas token symbol. - `base_amount` string, required: Gas cost in the gas token's base units (e.g. wei). - `amount` string, required: Gas cost in the gas token as a human-readable decimal string (e.g. "0.0001"). - `gas_asset` string, required: Gas token symbol (e.g. "ETH", "USDC"). - object: Response for an earn deposit action. - `id` string, required: The ID of the wallet action. - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required: The current status of the wallet action. - `wallet_id` string, required: The ID of the wallet involved in the action. - `created_at` string, date-time, required: ISO 8601 timestamp of when the wallet action was created. - `reference_id` string, nullable: Developer-provided reference ID, if one was included in the request. - `failure_reason` object: Top-level failure context for the wallet action. Present on rejected or failed actions when available. - `message` string, required: Human-readable failure message. - `details` unknown - `steps` WalletActionStep[]: The steps of the wallet action. Only returned if `?include=steps` is provided. - union: A step within a wallet action, representing a single onchain action. - object: A wallet action step consisting of an EVM transaction. - … - object: A wallet action step consisting of an EVM user operation. - … - object: A wallet action step consisting of an SVM (Solana) transaction. - … - object: A wallet action step consisting of a TVM (Tron) transaction. - … - object: A wallet action step representing a cross-chain/cross-asset fill by an external provider. - … - object: A wallet action step representing a transaction executed by a custodian (e.g. Bridge). - … - object: A wallet action step representing a Tempo Zone settlement on its parent chain. - … - `type` 'earn_deposit', required - `caip2` string, required: CAIP-2 chain identifier. - `vault_id` string, required: The vault ID. - `vault_address` string, required: ERC-4626 vault contract address. - `asset` string: Asset identifier (e.g. "usdc", "eth"). Only present when the token is known in the asset registry. - `asset_address` string, required: Underlying asset token address. - `decimals` integer: Number of decimals for the underlying asset (e.g. 6 for USDC, 18 for ETH). Only present when the token is known in the asset registry. - `amount` string: Human-readable decimal amount of asset deposited (e.g. "1.5"). Only present when the token is known in the asset registry. - `raw_amount` string, required: Base-unit amount of asset deposited (e.g. "1500000"). - `share_amount` string, nullable, required: Vault shares received in base units. Populated after on-chain confirmation. - object: Response for an earn withdraw action. - `id` string, required: The ID of the wallet action. - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required: The current status of the wallet action. - `wallet_id` string, required: The ID of the wallet involved in the action. - `created_at` string, date-time, required: ISO 8601 timestamp of when the wallet action was created. - `reference_id` string, nullable: Developer-provided reference ID, if one was included in the request. - `failure_reason` object: Top-level failure context for the wallet action. Present on rejected or failed actions when available. - `message` string, required: Human-readable failure message. - `details` unknown - `steps` WalletActionStep[]: The steps of the wallet action. Only returned if `?include=steps` is provided. - union: A step within a wallet action, representing a single onchain action. - object: A wallet action step consisting of an EVM transaction. - … - object: A wallet action step consisting of an EVM user operation. - … - object: A wallet action step consisting of an SVM (Solana) transaction. - … - object: A wallet action step consisting of a TVM (Tron) transaction. - … - object: A wallet action step representing a cross-chain/cross-asset fill by an external provider. - … - object: A wallet action step representing a transaction executed by a custodian (e.g. Bridge). - … - object: A wallet action step representing a Tempo Zone settlement on its parent chain. - … - `type` 'earn_withdraw', required - `caip2` string, required: CAIP-2 chain identifier. - `vault_id` string, required: The vault ID. - `vault_address` string, required: ERC-4626 vault contract address. - `asset` string: Asset identifier (e.g. "usdc", "eth"). Only present when the token is known in the asset registry. - `asset_address` string, required: Underlying asset token address. - `decimals` integer: Number of decimals for the underlying asset (e.g. 6 for USDC, 18 for ETH). Only present when the token is known in the asset registry. - `amount` string: Human-readable decimal amount of asset withdrawn (e.g. "1.5"). Only present when the token is known in the asset registry. - `raw_amount` string, required: Base-unit amount of asset withdrawn (e.g. "1500000"). - `share_amount` string, nullable, required: Vault shares burned in base units. Populated after on-chain confirmation. - object: Response for an earn incentive claim action. - `id` string, required: The ID of the wallet action. - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required: The current status of the wallet action. - `wallet_id` string, required: The ID of the wallet involved in the action. - `created_at` string, date-time, required: ISO 8601 timestamp of when the wallet action was created. - `reference_id` string, nullable: Developer-provided reference ID, if one was included in the request. - `failure_reason` object: Top-level failure context for the wallet action. Present on rejected or failed actions when available. - `message` string, required: Human-readable failure message. - `details` unknown - `steps` WalletActionStep[]: The steps of the wallet action. Only returned if `?include=steps` is provided. - union: A step within a wallet action, representing a single onchain action. - object: A wallet action step consisting of an EVM transaction. - … - object: A wallet action step consisting of an EVM user operation. - … - object: A wallet action step consisting of an SVM (Solana) transaction. - … - object: A wallet action step consisting of a TVM (Tron) transaction. - … - object: A wallet action step representing a cross-chain/cross-asset fill by an external provider. - … - object: A wallet action step representing a transaction executed by a custodian (e.g. Bridge). - … - object: A wallet action step representing a Tempo Zone settlement on its parent chain. - … - `type` 'earn_incentive_claim', required - `chain` string, required: EVM chain name (e.g. "tempo", "base"). - `rewards` EarnIncetiveClaimRewardEntry[], nullable, required: Claimed reward tokens. Populated after the preparation step fetches from Merkl. - `token_address` string, required: Address of the reward token. - `token_symbol` string, required: Symbol of the reward token (e.g. "MORPHO"). - `token_decimals` integer: Number of decimal places for the reward token. - `amount` string, required: Claimable amount in base units. - object: Response for an earn fee collect action. - `id` string, required: The ID of the wallet action. - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required: The current status of the wallet action. - `wallet_id` string, required: The ID of the wallet involved in the action. - `created_at` string, date-time, required: ISO 8601 timestamp of when the wallet action was created. - `reference_id` string, nullable: Developer-provided reference ID, if one was included in the request. - `failure_reason` object: Top-level failure context for the wallet action. Present on rejected or failed actions when available. - `message` string, required: Human-readable failure message. - `details` unknown - `steps` WalletActionStep[]: The steps of the wallet action. Only returned if `?include=steps` is provided. - union: A step within a wallet action, representing a single onchain action. - object: A wallet action step consisting of an EVM transaction. - … - object: A wallet action step consisting of an EVM user operation. - … - object: A wallet action step consisting of an SVM (Solana) transaction. - … - object: A wallet action step consisting of a TVM (Tron) transaction. - … - object: A wallet action step representing a cross-chain/cross-asset fill by an external provider. - … - object: A wallet action step representing a transaction executed by a custodian (e.g. Bridge). - … - object: A wallet action step representing a Tempo Zone settlement on its parent chain. - … - `type` 'earn_fee_collect', required - `caip2` string, required: CAIP-2 chain identifier. - `vault_id` string, required: The vault ID. - `vault_address` string, required: ERC-4626 vault contract address. - `asset` string: Asset identifier (e.g. "usdc", "eth"). Only present when the token is known in the asset registry. - `asset_address` string, required: Underlying asset token address. - `decimals` integer: Number of decimals for the underlying asset (e.g. 6 for USDC, 18 for ETH). Only present when the token is known in the asset registry. - `amount` string, nullable: Human-readable decimal amount of fees collected (e.g. "1.5"). Omitted when the token is not in the asset registry. Null while the action is pending; populated after on-chain confirmation. - `raw_amount` string, nullable, required: Base-unit amount of fees collected (e.g. "1500000"). Populated after on-chain confirmation. - object: A payout wallet action. Crypto is sent on-chain to a liquidation address that offramps to the destination bank account. - `id` string, required: The ID of the wallet action. - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required: The current status of the wallet action. - `wallet_id` string, required: The ID of the wallet involved in the action. - `created_at` string, date-time, required: ISO 8601 timestamp of when the wallet action was created. - `reference_id` string, nullable: Developer-provided reference ID, if one was included in the request. - `failure_reason` object: Top-level failure context for the wallet action. Present on rejected or failed actions when available. - `message` string, required: Human-readable failure message. - `details` unknown - `steps` WalletActionStep[]: The steps of the wallet action. Only returned if `?include=steps` is provided. - union: A step within a wallet action, representing a single onchain action. - object: A wallet action step consisting of an EVM transaction. - … - object: A wallet action step consisting of an EVM user operation. - … - object: A wallet action step consisting of an SVM (Solana) transaction. - … - object: A wallet action step consisting of a TVM (Tron) transaction. - … - object: A wallet action step representing a cross-chain/cross-asset fill by an external provider. - … - object: A wallet action step representing a transaction executed by a custodian (e.g. Bridge). - … - object: A wallet action step representing a Tempo Zone settlement on its parent chain. - … - `type` 'payout', required - `provider` 'bridge', required: Supported fiat orchestration providers. - `environment` 'sandbox' | 'production', required: The Privy API environment. - `source` PayoutSource, required: The source crypto asset, chain, and amount for a payout. - `asset` string, required: Source crypto asset (e.g. "usdc"). - `chain` string, required: Source chain (e.g. "base"). - `amount` string, required: Amount to offramp, in the asset's standard units (e.g. "100.00"). - `destination` PayoutDestination, required: The destination bank account for a payout. - `fiat_account_id` string, required: The ID of a previously registered external fiat account to pay out to. - `payment_rail` 'ach' | 'ach_same_day' | 'wire' | 'fednow' | 'sepa' | 'faster_payments' | 'pix': The fiat payment rail to settle over; must be one the account supports. Defaults to the account type’s standard rail, `ach` for US accounts. - `developer_fee_percent` string, required: The fee your app keeps on the payout, as a percentage. "0" when none was set. ## Changes - **2026-10-20** `527110c2c2f4`: 28 breaking, 56 info - the response property `actions/items/oneOf[subschema #1: SwapActionResponse]/steps/items/oneOf[subschema #1: EVMTransactionWalletActionStep]/gas_credits_charged_usd` became nullable for the status `200` - the response property `actions/items/oneOf[subschema #1: SwapActionResponse]/steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/gas_credits_charged_usd` became nullable for the status `200` - the response property `actions/items/oneOf[subschema #1: SwapActionResponse]/steps/items/oneOf[subschema #3: SVMTransactionWalletActionStep]/gas_credits_charged_usd` became nullable for the status `200` - the response property `actions/items/oneOf[subschema #1: SwapActionResponse]/steps/items/oneOf[subschema #4: TVMTransactionWalletActionStep]/gas_credits_charged_usd` became nullable for the status `200` - …80 more - …earlier changes not shown [Operation history](https://skmtc.dev/privy-io/apis/privy-api/changes/v1/actions/get.md) --- [API](https://skmtc.dev/privy-io/apis/privy-api.md) - [All operations](https://skmtc.dev/privy-io/apis/privy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/privy-io/apis/privy-api/revisions/6a80d4be53a8?raw)