@privy-io/api-types 0.15.0 → 0.17.0

package/src/resources/{wallet-actions.ts → wallets/actions.ts}

@@ -1,9 +1,113 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../core/resource';
-import * as WalletsAPI from './wallets/wallets';
+import { APIResource } from '../../core/resource';
+import * as WalletsAPI from './wallets';
 
-export class WalletActions extends APIResource {}
+export class Actions extends APIResource {}
+
+/**
+ * Vault details for an Aave earn vault, including fee visibility.
+ */
+export interface AaveVaultDetails {
+  /**
+   * Vault identifier.
+   */
+  id: string;
+
+  /**
+   * EVM address of the vault admin wallet.
+   */
+  admin_wallet_address: string;
+
+  /**
+   * Privy wallet ID of the vault admin.
+   */
+  admin_wallet_id: string;
+
+  /**
+   * Annual percentage yield earned by the app from fee wrapper fees, in basis
+   * points.
+   */
+  app_apy: number | null;
+
+  /**
+   * Asset metadata for an earn vault position.
+   */
+  asset: EarnAsset;
+
+  /**
+   * Fees available to collect, in smallest unit of the underlying asset.
+   */
+  available_fees: string;
+
+  /**
+   * Available liquidity in USD.
+   */
+  available_liquidity_usd: number | null;
+
+  /**
+   * CAIP-2 chain identifier (e.g. "eip155:8453").
+   */
+  caip2: string;
+
+  /**
+   * Human-readable vault name from the yield provider.
+   */
+  name: string;
+
+  provider: 'aave';
+
+  /**
+   * Total value locked in USD.
+   */
+  tvl_usd: number | null;
+
+  /**
+   * Annual percentage yield available to the user, after fees and excluding rewards,
+   * in basis points (e.g. 500 for 5%). 1 basis point = 0.01%.
+   */
+  user_apy: number | null;
+
+  /**
+   * Onchain vault contract address.
+   */
+  vault_address: string;
+}
+
+/**
+ * A wallet action step representing a transaction executed by a custodian (e.g.
+ * Bridge).
+ */
+export interface CustodianTransactionWalletActionStep {
+  /**
+   * Identifier of the custodian executing this transaction (e.g. "bridge").
+   */
+  custodian: string;
+
+  /**
+   * Status of a custodian transaction step in a wallet action.
+   */
+  status: CustodianTransactionWalletActionStepStatus;
+
+  type: 'custodian_transaction';
+
+  /**
+   * A description of why a wallet action (or a step within a wallet action) failed.
+   */
+  failure_reason?: FailureReason;
+}
+
+/**
+ * Status of a custodian transaction step in a wallet action.
+ */
+export type CustodianTransactionWalletActionStepStatus =
+  | 'preparing'
+  | 'queued'
+  | 'custodian_reviewing'
+  | 'pending'
+  | 'confirmed'
+  | 'rejected'
+  | 'failed';
 
 /**
  * A wallet action step consisting of an EVM transaction.
@@ -31,8 +135,19 @@ export interface EvmTransactionWalletActionStep {
    * A description of why a wallet action (or a step within a wallet action) failed.
    */
   failure_reason?: FailureReason;
+
+  /**
+   * Whether this step has reached on-chain finality. Absent until finality is
+   * confirmed.
+   */
+  finalized?: boolean;
 }
 
+/**
+ * The ERC-4337 entrypoint contract version used by the user operation.
+ */
+export type EvmUserOperationEntrypointVersion = '0.6' | '0.7' | '0.8' | '0.9';
+
 /**
  * A wallet action step consisting of an EVM user operation.
  */
@@ -49,9 +164,9 @@ export interface EvmUserOperationWalletActionStep {
   caip2: string;
 
   /**
-   * The entrypoint version of the user operation.
+   * The ERC-4337 entrypoint contract version used by the user operation.
    */
-  entrypoint_version: '0.6' | '0.7' | '0.8' | '0.9';
+  entrypoint_version: EvmUserOperationEntrypointVersion;
 
   /**
    * Status of an EVM step in a wallet action.
@@ -70,6 +185,17 @@ export interface EvmUserOperationWalletActionStep {
    * A description of why a wallet action (or a step within a wallet action) failed.
    */
   failure_reason?: FailureReason;
+
+  /**
+   * Whether this step has reached on-chain finality. Absent until finality is
+   * confirmed.
+   */
+  finalized?: boolean;
+
+  /**
+   * Amount charged in USD for gas sponsorship on this step.
+   */
+  gas_credits_charged_usd?: string;
 }
 
 /**
@@ -214,6 +340,98 @@ export interface EarnDepositRequestBody {
   raw_amount?: string;
 }
 
+/**
+ * Response for an earn fee collect action.
+ */
+export interface EarnFeeCollectActionResponse {
+  /**
+   * The ID of the wallet action.
+   */
+  id: string;
+
+  /**
+   * Underlying asset token address.
+   */
+  asset_address: string;
+
+  /**
+   * CAIP-2 chain identifier.
+   */
+  caip2: string;
+
+  /**
+   * ISO 8601 timestamp of when the wallet action was created.
+   */
+  created_at: string;
+
+  /**
+   * Base-unit amount of fees collected (e.g. "1500000"). Populated after on-chain
+   * confirmation.
+   */
+  raw_amount: string | null;
+
+  /**
+   * Status of a wallet action.
+   */
+  status: WalletActionStatus;
+
+  type: 'earn_fee_collect';
+
+  /**
+   * ERC-4626 vault contract address.
+   */
+  vault_address: string;
+
+  /**
+   * The vault ID.
+   */
+  vault_id: string;
+
+  /**
+   * The ID of the wallet involved in the action.
+   */
+  wallet_id: string;
+
+  /**
+   * 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.
+   */
+  amount?: string | null;
+
+  /**
+   * Asset identifier (e.g. "usdc", "eth"). Only present when the token is known in
+   * the asset registry.
+   */
+  asset?: string;
+
+  /**
+   * 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.
+   */
+  decimals?: number;
+
+  /**
+   * A description of why a wallet action (or a step within a wallet action) failed.
+   */
+  failure_reason?: FailureReason;
+
+  /**
+   * The steps of the wallet action. Only returned if `?include=steps` is provided.
+   */
+  steps?: Array<WalletActionStep>;
+}
+
+/**
+ * Input for collecting accumulated fees from an Aave vault.
+ */
+export interface EarnFeeCollectRequestBody {
+  /**
+   * The ID of the vault to collect fees from.
+   */
+  vault_id: string;
+}
+
 /**
  * Response for an earn incentive claim action.
  */
@@ -465,6 +683,11 @@ export interface EthereumEarnPositionQuery {
    * The vault ID to get position for.
    */
   vault_id: string;
+
+  /**
+   * Include archived wallets in lookup. Defaults to false.
+   */
+  include_archived?: boolean;
 }
 
 /**
@@ -500,17 +723,100 @@ export interface EthereumEarnPositionResponse {
 /**
  * Supported earn provider protocols.
  */
-export type EthereumEarnProvider = 'morpho' | 'aave';
+export type EthereumEarnProvider = 'morpho' | 'aave' | 'veda';
 
 /**
  * Detailed vault information including current APY, liquidity, and asset metadata.
+ * Discriminated on provider.
+ */
+export type EthereumEarnVaultDetailsResponse = AaveVaultDetails | MorphoVaultDetails | VedaVaultDetails;
+
+/**
+ * A wallet action step representing a cross-chain/cross-asset fill by an external
+ * provider.
+ */
+export interface ExternalTransactionWalletActionStep {
+  /**
+   * Status of an external transaction step in a wallet action.
+   */
+  status: ExternalTransactionWalletActionStepStatus;
+
+  type: 'external_transaction';
+
+  /**
+   * A description of why a wallet action (or a step within a wallet action) failed.
+   */
+  failure_reason?: FailureReason;
+}
+
+/**
+ * Status of an external transaction step in a wallet action.
  */
-export interface EthereumEarnVaultDetailsResponse {
+export type ExternalTransactionWalletActionStepStatus =
+  | 'preparing'
+  | 'queued'
+  | 'pending'
+  | 'confirmed'
+  | 'rejected'
+  | 'failed';
+
+/**
+ * A description of why a wallet action (or a step within a wallet action) failed.
+ */
+export interface FailureReason {
+  /**
+   * Human-readable failure message.
+   */
+  message: string;
+
+  /**
+   * Additional error details, if available.
+   */
+  details?: unknown;
+}
+
+/**
+ * Query parameters for listing wallet actions.
+ */
+export interface ListWalletActionsQuery {
+  cursor?: string;
+
+  limit?: number | null;
+
+  /**
+   * Type of wallet action
+   */
+  type?: WalletActionType;
+}
+
+/**
+ * Paginated list of wallet actions.
+ */
+export interface ListWalletActionsResponse {
+  data: Array<WalletActionResponse>;
+
+  next_cursor: string | null;
+}
+
+/**
+ * Vault details for a Morpho earn vault.
+ */
+export interface MorphoVaultDetails {
   /**
    * Vault identifier.
    */
   id: string;
 
+  /**
+   * EVM address of the vault admin wallet.
+   */
+  admin_wallet_address: string;
+
+  /**
+   * Privy wallet ID of the vault admin.
+   */
+  admin_wallet_id: string;
+
   /**
    * Annual percentage yield earned by the app from fee wrapper fees, in basis
    * points.
@@ -537,10 +843,12 @@ export interface EthereumEarnVaultDetailsResponse {
    */
   name: string;
 
+  provider: 'morpho';
+
   /**
-   * Supported earn provider protocols.
+   * Total rewards annual percentage rate in basis points.
    */
-  provider: EthereumEarnProvider;
+  total_rewards_apr: number;
 
   /**
    * Total value locked in USD.
@@ -548,8 +856,8 @@ export interface EthereumEarnVaultDetailsResponse {
   tvl_usd: number | null;
 
   /**
-   * Current annual percentage yield in basis points (e.g. 500 for 5%). 1 basis point
-   * = 0.01%.
+   * Annual percentage yield available to the user, after fees and excluding rewards,
+   * in basis points (e.g. 500 for 5%). 1 basis point = 0.01%.
    */
   user_apy: number | null;
 
@@ -559,50 +867,6 @@ export interface EthereumEarnVaultDetailsResponse {
   vault_address: string;
 }
 
-/**
- * A wallet action step representing a cross-chain/cross-asset fill by an external
- * provider.
- */
-export interface ExternalTransactionWalletActionStep {
-  /**
-   * Status of an external transaction step in a wallet action.
-   */
-  status: ExternalTransactionWalletActionStepStatus;
-
-  type: 'external_transaction';
-
-  /**
-   * A description of why a wallet action (or a step within a wallet action) failed.
-   */
-  failure_reason?: FailureReason;
-}
-
-/**
- * Status of an external transaction step in a wallet action.
- */
-export type ExternalTransactionWalletActionStepStatus =
-  | 'preparing'
-  | 'queued'
-  | 'pending'
-  | 'confirmed'
-  | 'rejected'
-  | 'failed';
-
-/**
- * A description of why a wallet action (or a step within a wallet action) failed.
- */
-export interface FailureReason {
-  /**
-   * Human-readable failure message.
-   */
-  message: string;
-
-  /**
-   * Additional error details, if available.
-   */
-  details?: unknown;
-}
-
 /**
  * A wallet action step consisting of an SVM (Solana) transaction.
  */
@@ -628,6 +892,17 @@ export interface SvmTransactionWalletActionStep {
    * A description of why a wallet action (or a step within a wallet action) failed.
    */
   failure_reason?: FailureReason;
+
+  /**
+   * Whether this step has reached on-chain finality. Absent until finality is
+   * confirmed.
+   */
+  finalized?: boolean;
+
+  /**
+   * Amount charged in USD for gas sponsorship on this step.
+   */
+  gas_credits_charged_usd?: string;
 }
 
 /**
@@ -638,7 +913,6 @@ export type SvmWalletActionStepStatus =
   | 'queued'
   | 'pending'
   | 'confirmed'
-  | 'finalized'
   | 'rejected'
   | 'reverted'
   | 'failed';
@@ -694,21 +968,29 @@ export interface SwapActionResponse {
    */
   wallet_id: string;
 
+  /**
+   * Recipient address on the destination chain. Present for cross-chain swaps. May
+   * differ from the source wallet address when swapping between chain types (e.g.
+   * EVM to Solana).
+   */
+  destination_address?: string;
+
   /**
    * Destination chain CAIP-2 identifier. Present for cross-chain swaps.
    */
   destination_caip2?: string;
 
   /**
-   * Estimated fee breakdown from the provider quote.
+   * Estimated fee breakdown from the provider quote. Only present for cross-chain
+   * swaps. Populated after on-chain confirmation.
    */
-  estimated_fees?: Array<WalletsAPI.FeeLineItem>;
+  estimated_fees?: Array<WalletsAPI.FeeLineItem> | null;
 
   /**
    * Gas cost for a blockchain action. Includes both raw base-unit amount and a
    * human-readable decimal string, plus the gas token symbol.
    */
-  estimated_gas?: WalletsAPI.Gas;
+  estimated_gas?: WalletsAPI.Gas | null;
 
   /**
    * A description of why a wallet action (or a step within a wallet action) failed.
@@ -716,15 +998,16 @@ export interface SwapActionResponse {
   failure_reason?: FailureReason;
 
   /**
-   * Actual fees paid for the swap. Populated after on-chain confirmation.
+   * Actual fees paid for the swap. Populated after on-chain confirmation. Only
+   * present for cross-chain swaps.
    */
-  fees?: Array<WalletsAPI.FeeLineItem>;
+  fees?: Array<WalletsAPI.FeeLineItem> | null;
 
   /**
    * Gas cost for a blockchain action. Includes both raw base-unit amount and a
    * human-readable decimal string, plus the gas token symbol.
    */
-  gas?: WalletsAPI.Gas;
+  gas?: WalletsAPI.Gas | null;
 
   /**
    * The steps of the wallet action. Only returned if `?include=steps` is provided.
@@ -732,6 +1015,45 @@ export interface SwapActionResponse {
   steps?: Array<WalletActionStep>;
 }
 
+/**
+ * A wallet action step consisting of a TVM (Tron) transaction.
+ */
+export interface TvmTransactionWalletActionStep {
+  /**
+   * CAIP-2 chain identifier for the Tron network.
+   */
+  caip2: string;
+
+  /**
+   * Status of a TVM (Tron) step in a wallet action.
+   */
+  status: TvmWalletActionStepStatus;
+
+  /**
+   * The Tron transaction ID. Null until broadcast.
+   */
+  transaction_id: string | null;
+
+  type: 'tvm_transaction';
+
+  /**
+   * A description of why a wallet action (or a step within a wallet action) failed.
+   */
+  failure_reason?: FailureReason;
+}
+
+/**
+ * Status of a TVM (Tron) step in a wallet action.
+ */
+export type TvmWalletActionStepStatus =
+  | 'preparing'
+  | 'queued'
+  | 'pending'
+  | 'confirmed'
+  | 'rejected'
+  | 'reverted'
+  | 'failed';
+
 /**
  * Response for a transfer action.
  */
@@ -751,6 +1073,13 @@ export interface TransferActionResponse {
    */
   destination_address: string;
 
+  /**
+   * 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.
+   */
+  destination_amount: string | null;
+
   /**
    * Chain name (e.g. "base", "ethereum").
    */
@@ -769,10 +1098,9 @@ export interface TransferActionResponse {
   wallet_id: string;
 
   /**
-   * Amount received on the destination chain. Populated immediately for exact_output
-   * transfers, or after fill confirmation for exact_input transfers.
+   * Whether the amount refers to the input token or output token.
    */
-  destination_amount?: string;
+  amount_type?: WalletsAPI.AmountType;
 
   /**
    * Destination asset for cross-asset transfers. Omitted for same-asset transfers.
@@ -785,15 +1113,16 @@ export interface TransferActionResponse {
   destination_chain?: string;
 
   /**
-   * Estimated fee breakdown from the provider quote.
+   * Estimated fee breakdown from the provider quote. Only present for cross-chain or
+   * cross-asset transfers. Populated after on-chain confirmation.
    */
-  estimated_fees?: Array<WalletsAPI.FeeLineItem>;
+  estimated_fees?: Array<WalletsAPI.FeeLineItem> | null;
 
   /**
    * Gas cost for a blockchain action. Includes both raw base-unit amount and a
    * human-readable decimal string, plus the gas token symbol.
    */
-  estimated_gas?: WalletsAPI.Gas;
+  estimated_gas?: WalletsAPI.Gas | null;
 
   /**
    * A description of why a wallet action (or a step within a wallet action) failed.
@@ -801,19 +1130,20 @@ export interface TransferActionResponse {
   failure_reason?: FailureReason;
 
   /**
-   * Actual fees paid for the transfer. Populated after on-chain confirmation.
+   * Actual fees paid for the transfer. Populated after on-chain confirmation. Only
+   * present for cross-chain transfers.
    */
-  fees?: Array<WalletsAPI.FeeLineItem>;
+  fees?: Array<WalletsAPI.FeeLineItem> | null;
 
   /**
    * Gas cost for a blockchain action. Includes both raw base-unit amount and a
    * human-readable decimal string, plus the gas token symbol.
    */
-  gas?: WalletsAPI.Gas;
+  gas?: WalletsAPI.Gas | null;
 
   /**
-   * Decimal amount sent on the source chain (e.g. "1.5"). Omitted for exact_output
-   * cross-chain transfers until the source amount is determined.
+   * Decimal amount sent on the source chain (e.g. "1.5"). For exact_output
+   * cross-chain transfers, null until fill confirmation.
    */
   source_amount?: string;
 
@@ -841,6 +1171,75 @@ export interface TransferActionResponse {
   steps?: Array<WalletActionStep>;
 }
 
+/**
+ * Vault details for a Veda (BoringVault) earn vault.
+ */
+export interface VedaVaultDetails {
+  /**
+   * Vault identifier.
+   */
+  id: string;
+
+  /**
+   * EVM address of the vault admin wallet.
+   */
+  admin_wallet_address: string;
+
+  /**
+   * Privy wallet ID of the vault admin.
+   */
+  admin_wallet_id: string;
+
+  /**
+   * Annual percentage yield earned by the app from fee wrapper fees, in basis
+   * points.
+   */
+  app_apy: number | null;
+
+  /**
+   * Asset metadata for an earn vault position.
+   */
+  asset: EarnAsset;
+
+  /**
+   * Available liquidity in USD.
+   */
+  available_liquidity_usd: number | null;
+
+  /**
+   * CAIP-2 chain identifier (e.g. "eip155:8453").
+   */
+  caip2: string;
+
+  /**
+   * Human-readable vault name from the yield provider.
+   */
+  name: string;
+
+  provider: 'veda';
+
+  /**
+   * Total value locked in USD.
+   */
+  tvl_usd: number | null;
+
+  /**
+   * Annual percentage yield available to the user, after fees and excluding rewards,
+   * in basis points (e.g. 500 for 5%). 1 basis point = 0.01%.
+   */
+  user_apy: number | null;
+
+  /**
+   * Onchain vault contract address.
+   */
+  vault_address: string;
+}
+
+/**
+ * Expandable relations to include on a wallet action response.
+ */
+export type WalletActionInclude = 'steps';
+
 /**
  * Response for a wallet action, discriminated on type.
  */
@@ -849,7 +1248,8 @@ export type WalletActionResponse =
   | TransferActionResponse
   | EarnDepositActionResponse
   | EarnWithdrawActionResponse
-  | EarnIncentiveClaimActionResponse;
+  | EarnIncentiveClaimActionResponse
+  | EarnFeeCollectActionResponse;
 
 /**
  * Status of a wallet action.
@@ -863,7 +1263,9 @@ export type WalletActionStep =
   | EvmTransactionWalletActionStep
   | EvmUserOperationWalletActionStep
   | SvmTransactionWalletActionStep
-  | ExternalTransactionWalletActionStep;
+  | TvmTransactionWalletActionStep
+  | ExternalTransactionWalletActionStep
+  | CustodianTransactionWalletActionStep;
 
 /**
  * Type of a wallet action step.
@@ -872,7 +1274,9 @@ export type WalletActionStepType =
   | 'evm_transaction'
   | 'evm_user_operation'
   | 'svm_transaction'
-  | 'external_transaction';
+  | 'tvm_transaction'
+  | 'external_transaction'
+  | 'custodian_transaction';
 
 /**
  * Type of wallet action
@@ -882,16 +1286,23 @@ export type WalletActionType =
   | 'transfer'
   | 'earn_deposit'
   | 'earn_withdraw'
-  | 'earn_incentive_claim';
+  | 'earn_incentive_claim'
+  | 'earn_fee_collect';
 
-export declare namespace WalletActions {
+export declare namespace Actions {
   export {
+    type AaveVaultDetails as AaveVaultDetails,
+    type CustodianTransactionWalletActionStep as CustodianTransactionWalletActionStep,
+    type CustodianTransactionWalletActionStepStatus as CustodianTransactionWalletActionStepStatus,
     type EvmTransactionWalletActionStep as EvmTransactionWalletActionStep,
+    type EvmUserOperationEntrypointVersion as EvmUserOperationEntrypointVersion,
     type EvmUserOperationWalletActionStep as EvmUserOperationWalletActionStep,
     type EvmWalletActionStepStatus as EvmWalletActionStepStatus,
     type EarnAsset as EarnAsset,
     type EarnDepositActionResponse as EarnDepositActionResponse,
     type EarnDepositRequestBody as EarnDepositRequestBody,
+    type EarnFeeCollectActionResponse as EarnFeeCollectActionResponse,
+    type EarnFeeCollectRequestBody as EarnFeeCollectRequestBody,
     type EarnIncentiveClaimActionResponse as EarnIncentiveClaimActionResponse,
     type EarnIncentiveClaimRequestBody as EarnIncentiveClaimRequestBody,
     type EarnIncentiveRewardEntry as EarnIncentiveRewardEntry,
@@ -907,10 +1318,17 @@ export declare namespace WalletActions {
     type ExternalTransactionWalletActionStep as ExternalTransactionWalletActionStep,
     type ExternalTransactionWalletActionStepStatus as ExternalTransactionWalletActionStepStatus,
     type FailureReason as FailureReason,
+    type ListWalletActionsQuery as ListWalletActionsQuery,
+    type ListWalletActionsResponse as ListWalletActionsResponse,
+    type MorphoVaultDetails as MorphoVaultDetails,
     type SvmTransactionWalletActionStep as SvmTransactionWalletActionStep,
     type SvmWalletActionStepStatus as SvmWalletActionStepStatus,
     type SwapActionResponse as SwapActionResponse,
+    type TvmTransactionWalletActionStep as TvmTransactionWalletActionStep,
+    type TvmWalletActionStepStatus as TvmWalletActionStepStatus,
     type TransferActionResponse as TransferActionResponse,
+    type VedaVaultDetails as VedaVaultDetails,
+    type WalletActionInclude as WalletActionInclude,
     type WalletActionResponse as WalletActionResponse,
     type WalletActionStatus as WalletActionStatus,
     type WalletActionStep as WalletActionStep,