@privy-io/api-types 0.8.0 → 0.10.0

package/src/resources/wallet-actions.ts

@@ -5,19 +5,71 @@ import { APIResource } from '../core/resource';
 export class WalletActions extends APIResource {}
 
 /**
- * Type of wallet action
+ * A wallet action step consisting of an EVM transaction.
  */
-export type WalletActionType = 'swap' | 'transfer';
+export interface EvmTransactionWalletActionStep {
+  /**
+   * CAIP-2 chain identifier of the transaction, containing the chain ID.
+   */
+  caip2: string;
 
-/**
- * Status of a wallet action.
- */
-export type WalletActionStatus = 'pending' | 'succeeded' | 'rejected' | 'failed';
+  /**
+   * Status of an EVM step in a wallet action.
+   */
+  status: EvmWalletActionStepStatus;
+
+  /**
+   * The transaction hash for this step. May change while the step status is
+   * non-terminal.
+   */
+  transaction_hash: string | null;
+
+  type: 'evm_transaction';
+
+  /**
+   * A description of why a wallet action (or a step within a wallet action) failed.
+   */
+  failure_reason?: FailureReason;
+}
 
 /**
- * Type of a wallet action step.
+ * A wallet action step consisting of an EVM user operation.
  */
-export type WalletActionStepType = 'evm_transaction' | 'evm_user_operation';
+export interface EvmUserOperationWalletActionStep {
+  /**
+   * Transaction hash of the bundle in which this user operation was included. Null
+   * until included by a bundler.
+   */
+  bundle_transaction_hash: string | null;
+
+  /**
+   * CAIP-2 network identifier, containing the chain ID of the user operation.
+   */
+  caip2: string;
+
+  /**
+   * The entrypoint version of the user operation.
+   */
+  entrypoint_version: '0.6' | '0.7' | '0.8' | '0.9';
+
+  /**
+   * Status of an EVM step in a wallet action.
+   */
+  status: EvmWalletActionStepStatus;
+
+  type: 'evm_user_operation';
+
+  /**
+   * The user operation hash for this step. May change while the step status is
+   * non-terminal.
+   */
+  user_operation_hash: string | null;
+
+  /**
+   * A description of why a wallet action (or a step within a wallet action) failed.
+   */
+  failure_reason?: FailureReason;
+}
 
 /**
  * Status of an EVM step in a wallet action.
@@ -34,91 +86,481 @@ export type EvmWalletActionStepStatus =
   | 'abandoned';
 
 /**
- * A description of why a wallet action (or a step within a wallet action) failed.
+ * Asset metadata for an earn vault position.
  */
-export interface FailureReason {
+export interface EarnAsset {
   /**
-   * Human-readable failure message.
+   * Token contract address.
    */
-  message: string;
+  address: string;
 
   /**
-   * Additional error details, if available.
+   * Number of decimals for the asset (e.g. 6 for USDC).
    */
-  details?: unknown;
+  decimals: number;
+
+  /**
+   * Lowercase token symbol (e.g. "usdc").
+   */
+  symbol: string;
 }
 
 /**
- * A wallet action step consisting of an EVM transaction.
+ * Response for an earn deposit action.
  */
-export interface EvmTransactionWalletActionStep {
+export interface EarnDepositActionResponse {
   /**
-   * CAIP-2 chain identifier of the transaction, containing the chain ID.
+   * The ID of the wallet action.
+   */
+  id: string;
+
+  /**
+   * Underlying asset token address.
+   */
+  asset_address: string;
+
+  /**
+   * CAIP-2 chain identifier.
    */
   caip2: string;
 
   /**
-   * Status of an EVM step in a wallet action.
+   * ISO 8601 timestamp of when the wallet action was created.
    */
-  status: EvmWalletActionStepStatus;
+  created_at: string;
 
   /**
-   * The transaction hash for this step. May change while the step status is
-   * non-terminal.
+   * Base-unit amount of asset deposited (e.g. "1500000").
    */
-  transaction_hash: string | null;
+  raw_amount: string;
 
-  type: 'evm_transaction';
+  /**
+   * Vault shares received in base units. Populated after on-chain confirmation.
+   */
+  share_amount: string | null;
+
+  /**
+   * Status of a wallet action.
+   */
+  status: WalletActionStatus;
+
+  type: 'earn_deposit';
+
+  /**
+   * 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 asset deposited (e.g. "1.5"). Only present when
+   * the token is known in the asset registry.
+   */
+  amount?: string;
+
+  /**
+   * 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>;
 }
 
 /**
- * A wallet action step consisting of an EVM user operation.
+ * Input for depositing assets into an ERC-4626 vault. Exactly one of `amount` or
+ * `raw_amount` must be provided.
  */
-export interface EvmUserOperationWalletActionStep {
+export interface EarnDepositRequestBody {
   /**
-   * Transaction hash of the bundle in which this user operation was included. Null
-   * until included by a bundler.
+   * The ID of the vault to deposit into.
    */
-  bundle_transaction_hash: string | null;
+  vault_id: string;
 
   /**
-   * CAIP-2 network identifier, containing the chain ID of the user operation.
+   * Human-readable decimal amount to deposit (e.g. "1.5" for 1.5 USDC). Exactly one
+   * of `amount` or `raw_amount` must be provided.
+   */
+  amount?: string;
+
+  /**
+   * Amount in smallest unit to deposit (e.g. "1500000" for 1.5 USDC with 6
+   * decimals). Exactly one of `amount` or `raw_amount` must be provided.
+   */
+  raw_amount?: string;
+}
+
+/**
+ * Response for an earn incentive claim action.
+ */
+export interface EarnIncentiveClaimActionResponse {
+  /**
+   * The ID of the wallet action.
+   */
+  id: string;
+
+  /**
+   * EVM chain name (e.g. "base", "ethereum").
+   */
+  chain: string;
+
+  /**
+   * ISO 8601 timestamp of when the wallet action was created.
+   */
+  created_at: string;
+
+  /**
+   * Claimed reward tokens. Populated after the preparation step fetches from Merkl.
+   */
+  rewards: Array<EarnIncetiveClaimRewardEntry> | null;
+
+  /**
+   * Status of a wallet action.
+   */
+  status: WalletActionStatus;
+
+  type: 'earn_incentive_claim';
+
+  /**
+   * The ID of the wallet involved in the action.
+   */
+  wallet_id: string;
+
+  /**
+   * 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 claiming incentive rewards.
+ */
+export interface EarnIncentiveClaimRequestBody {
+  /**
+   * The blockchain network on which to perform the incentive claim. Supported chains
+   * include: 'ethereum', 'base', 'arbitrum', 'polygon', 'solana', and more, along
+   * with their respective testnets.
+   */
+  chain: string;
+}
+
+/**
+ * A specific reward token and amount associated with an earn incentive claim.
+ */
+export interface EarnIncetiveClaimRewardEntry {
+  /**
+   * Claimable amount in base units.
+   */
+  amount: string;
+
+  /**
+   * Address of the reward token.
+   */
+  token_address: string;
+
+  /**
+   * Symbol of the reward token (e.g. "MORPHO").
+   */
+  token_symbol: string;
+
+  /**
+   * Number of decimal places for the reward token.
+   */
+  token_decimals?: number;
+}
+
+/**
+ * Response for an earn withdraw action.
+ */
+export interface EarnWithdrawActionResponse {
+  /**
+   * The ID of the wallet action.
+   */
+  id: string;
+
+  /**
+   * Underlying asset token address.
+   */
+  asset_address: string;
+
+  /**
+   * CAIP-2 chain identifier.
    */
   caip2: string;
 
   /**
-   * The entrypoint version of the user operation.
+   * ISO 8601 timestamp of when the wallet action was created.
    */
-  entrypoint_version: '0.6' | '0.7' | '0.8' | '0.9';
+  created_at: string;
 
   /**
-   * Status of an EVM step in a wallet action.
+   * Base-unit amount of asset withdrawn (e.g. "1500000").
    */
-  status: EvmWalletActionStepStatus;
+  raw_amount: string;
 
-  type: 'evm_user_operation';
+  /**
+   * Vault shares burned in base units. Populated after on-chain confirmation.
+   */
+  share_amount: string | null;
 
   /**
-   * The user operation hash for this step. May change while the step status is
-   * non-terminal.
+   * Status of a wallet action.
    */
-  user_operation_hash: string | null;
+  status: WalletActionStatus;
+
+  type: 'earn_withdraw';
+
+  /**
+   * 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 asset withdrawn (e.g. "1.5"). Only present when
+   * the token is known in the asset registry.
+   */
+  amount?: string;
+
+  /**
+   * 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>;
 }
 
 /**
- * A step within a wallet action, representing a single onchain action.
+ * Input for withdrawing assets from an ERC-4626 vault. Exactly one of `amount` or
+ * `raw_amount` must be provided.
+ */
+export interface EarnWithdrawRequestBody {
+  /**
+   * The ID of the vault to withdraw from.
+   */
+  vault_id: string;
+
+  /**
+   * Human-readable decimal amount to withdraw (e.g. "1.5" for 1.5 USDC). Exactly one
+   * of `amount` or `raw_amount` must be provided.
+   */
+  amount?: string;
+
+  /**
+   * Amount in smallest unit to withdraw (e.g. "1500000" for 1.5 USDC with 6
+   * decimals). Exactly one of `amount` or `raw_amount` must be provided.
+   */
+  raw_amount?: string;
+}
+
+/**
+ * Query parameters for fetching an earn vault position.
+ */
+export interface EthereumEarnPositionQuery {
+  /**
+   * The vault ID to get position for.
+   */
+  vault_id: string;
+}
+
+/**
+ * A wallet's position in an earn vault.
+ */
+export interface EthereumEarnPositionResponse {
+  /**
+   * Asset metadata for an earn vault position.
+   */
+  asset: EarnAsset;
+
+  /**
+   * Current asset value in the vault (realtime from ERC-4626), in smallest unit.
+   */
+  assets_in_vault: string;
+
+  /**
+   * Current vault shares held (realtime from ERC-4626).
+   */
+  shares_in_vault: string;
+
+  /**
+   * Total amount deposited into the vault, in smallest unit.
+   */
+  total_deposited: string;
+
+  /**
+   * Total amount withdrawn from the vault, in smallest unit.
+   */
+  total_withdrawn: string;
+}
+
+/**
+ * Supported earn provider protocols.
+ */
+export type EthereumEarnProvider = 'morpho' | 'aave';
+
+/**
+ * Detailed vault information including current APY, liquidity, and asset metadata.
+ */
+export interface EthereumEarnVaultDetailsResponse {
+  /**
+   * Vault identifier.
+   */
+  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;
+
+  /**
+   * Supported earn provider protocols.
+   */
+  provider: EthereumEarnProvider;
+
+  /**
+   * Total value locked in USD.
+   */
+  tvl_usd: number | null;
+
+  /**
+   * Current annual percentage yield 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 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.
+ */
+export interface SvmTransactionWalletActionStep {
+  /**
+   * CAIP-2 chain identifier for the Solana network.
+   */
+  caip2: string;
+
+  /**
+   * Status of an SVM step in a wallet action.
+   */
+  status: SvmWalletActionStepStatus;
+
+  /**
+   * The Solana transaction signature (base58-encoded). Null until broadcast.
+   */
+  transaction_signature: string | null;
+
+  type: 'svm_transaction';
+
+  /**
+   * A description of why a wallet action (or a step within a wallet action) failed.
+   */
+  failure_reason?: FailureReason;
+}
+
+/**
+ * Status of an SVM step in a wallet action.
  */
-export type WalletActionStep = EvmTransactionWalletActionStep | EvmUserOperationWalletActionStep;
+export type SvmWalletActionStepStatus =
+  | 'preparing'
+  | 'queued'
+  | 'pending'
+  | 'confirmed'
+  | 'finalized'
+  | 'rejected'
+  | 'reverted'
+  | 'failed';
 
 /**
  * Response for a swap action.
@@ -171,6 +613,11 @@ export interface SwapActionResponse {
    */
   wallet_id: string;
 
+  /**
+   * 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.
    */
@@ -196,16 +643,6 @@ export interface TransferActionResponse {
    */
   destination_address: string;
 
-  /**
-   * Decimal amount as the user provided (e.g. "1.5").
-   */
-  source_amount: string;
-
-  /**
-   * Asset identifier (e.g. "usdc", "eth").
-   */
-  source_asset: string;
-
   /**
    * Chain name (e.g. "base", "ethereum").
    */
@@ -223,6 +660,51 @@ 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.
+   */
+  destination_amount?: string;
+
+  /**
+   * Destination asset for cross-asset transfers. Omitted for same-asset transfers.
+   */
+  destination_asset?: string;
+
+  /**
+   * Destination chain for cross-chain transfers. Omitted for same-chain transfers.
+   */
+  destination_chain?: string;
+
+  /**
+   * A description of why a wallet action (or a step within a wallet action) failed.
+   */
+  failure_reason?: FailureReason;
+
+  /**
+   * Decimal amount sent on the source chain (e.g. "1.5"). Omitted for exact_output
+   * cross-chain transfers until the source amount is determined.
+   */
+  source_amount?: string;
+
+  /**
+   * Asset identifier (e.g. "usdc", "eth"). Present when the transfer was initiated
+   * with a named asset; omitted for custom-token transfers.
+   */
+  source_asset?: string;
+
+  /**
+   * Token contract address (EVM) or mint address (Solana). Present when the transfer
+   * was initiated with `asset_address`.
+   */
+  source_asset_address?: string;
+
+  /**
+   * Number of decimals for the transferred token. Present when the transfer was
+   * initiated with `asset_address` and the decimals were resolved on-chain.
+   */
+  source_asset_decimals?: number;
+
   /**
    * The steps of the wallet action. Only returned if `?include=steps` is provided.
    */
@@ -232,20 +714,67 @@ export interface TransferActionResponse {
 /**
  * Response for a wallet action, discriminated on type.
  */
-export type WalletActionResponse = SwapActionResponse | TransferActionResponse;
+export type WalletActionResponse =
+  | SwapActionResponse
+  | TransferActionResponse
+  | EarnDepositActionResponse
+  | EarnWithdrawActionResponse
+  | EarnIncentiveClaimActionResponse;
+
+/**
+ * Status of a wallet action.
+ */
+export type WalletActionStatus = 'pending' | 'succeeded' | 'rejected' | 'failed';
+
+/**
+ * A step within a wallet action, representing a single onchain action.
+ */
+export type WalletActionStep =
+  | EvmTransactionWalletActionStep
+  | EvmUserOperationWalletActionStep
+  | SvmTransactionWalletActionStep;
+
+/**
+ * Type of a wallet action step.
+ */
+export type WalletActionStepType = 'evm_transaction' | 'evm_user_operation' | 'svm_transaction';
+
+/**
+ * Type of wallet action
+ */
+export type WalletActionType =
+  | 'swap'
+  | 'transfer'
+  | 'earn_deposit'
+  | 'earn_withdraw'
+  | 'earn_incentive_claim';
 
 export declare namespace WalletActions {
   export {
-    type WalletActionType as WalletActionType,
-    type WalletActionStatus as WalletActionStatus,
-    type WalletActionStepType as WalletActionStepType,
-    type EvmWalletActionStepStatus as EvmWalletActionStepStatus,
-    type FailureReason as FailureReason,
     type EvmTransactionWalletActionStep as EvmTransactionWalletActionStep,
     type EvmUserOperationWalletActionStep as EvmUserOperationWalletActionStep,
-    type WalletActionStep as WalletActionStep,
+    type EvmWalletActionStepStatus as EvmWalletActionStepStatus,
+    type EarnAsset as EarnAsset,
+    type EarnDepositActionResponse as EarnDepositActionResponse,
+    type EarnDepositRequestBody as EarnDepositRequestBody,
+    type EarnIncentiveClaimActionResponse as EarnIncentiveClaimActionResponse,
+    type EarnIncentiveClaimRequestBody as EarnIncentiveClaimRequestBody,
+    type EarnIncetiveClaimRewardEntry as EarnIncetiveClaimRewardEntry,
+    type EarnWithdrawActionResponse as EarnWithdrawActionResponse,
+    type EarnWithdrawRequestBody as EarnWithdrawRequestBody,
+    type EthereumEarnPositionQuery as EthereumEarnPositionQuery,
+    type EthereumEarnPositionResponse as EthereumEarnPositionResponse,
+    type EthereumEarnProvider as EthereumEarnProvider,
+    type EthereumEarnVaultDetailsResponse as EthereumEarnVaultDetailsResponse,
+    type FailureReason as FailureReason,
+    type SvmTransactionWalletActionStep as SvmTransactionWalletActionStep,
+    type SvmWalletActionStepStatus as SvmWalletActionStepStatus,
     type SwapActionResponse as SwapActionResponse,
     type TransferActionResponse as TransferActionResponse,
     type WalletActionResponse as WalletActionResponse,
+    type WalletActionStatus as WalletActionStatus,
+    type WalletActionStep as WalletActionStep,
+    type WalletActionStepType as WalletActionStepType,
+    type WalletActionType as WalletActionType,
   };
 }