@privy-io/api-types 0.9.0 → 0.10.0

package/src/resources/wallet-actions.ts

@@ -4,55 +4,6 @@ import { APIResource } from '../core/resource';
 
 export class WalletActions extends APIResource {}
 
-/**
- * Type of wallet action
- */
-export type WalletActionType =
-  | 'swap'
-  | 'transfer'
-  | 'earn_deposit'
-  | 'earn_withdraw'
-  | 'earn_incentive_claim';
-
-/**
- * Status of a wallet action.
- */
-export type WalletActionStatus = 'pending' | 'succeeded' | 'rejected' | 'failed';
-
-/**
- * Type of a wallet action step.
- */
-export type WalletActionStepType = 'evm_transaction' | 'evm_user_operation';
-
-/**
- * Status of an EVM step in a wallet action.
- */
-export type EvmWalletActionStepStatus =
-  | 'preparing'
-  | 'queued'
-  | 'pending'
-  | 'retrying'
-  | 'confirmed'
-  | 'rejected'
-  | 'reverted'
-  | 'replaced'
-  | 'abandoned';
-
-/**
- * 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 EVM transaction.
  */
@@ -121,21 +72,55 @@ export interface EvmUserOperationWalletActionStep {
 }
 
 /**
- * A step within a wallet action, representing a single onchain action.
+ * Status of an EVM step in a wallet action.
+ */
+export type EvmWalletActionStepStatus =
+  | 'preparing'
+  | 'queued'
+  | 'pending'
+  | 'retrying'
+  | 'confirmed'
+  | 'rejected'
+  | 'reverted'
+  | 'replaced'
+  | 'abandoned';
+
+/**
+ * Asset metadata for an earn vault position.
  */
-export type WalletActionStep = EvmTransactionWalletActionStep | EvmUserOperationWalletActionStep;
+export interface EarnAsset {
+  /**
+   * Token contract address.
+   */
+  address: string;
+
+  /**
+   * Number of decimals for the asset (e.g. 6 for USDC).
+   */
+  decimals: number;
+
+  /**
+   * Lowercase token symbol (e.g. "usdc").
+   */
+  symbol: string;
+}
 
 /**
- * Response for a swap action.
+ * Response for an earn deposit action.
  */
-export interface SwapActionResponse {
+export interface EarnDepositActionResponse {
   /**
    * The ID of the wallet action.
    */
   id: string;
 
   /**
-   * CAIP-2 chain identifier for the swap.
+   * Underlying asset token address.
+   */
+  asset_address: string;
+
+  /**
+   * CAIP-2 chain identifier.
    */
   caip2: string;
 
@@ -145,37 +130,55 @@ export interface SwapActionResponse {
   created_at: string;
 
   /**
-   * Exact base-unit amount of input token. Populated after on-chain confirmation.
+   * Base-unit amount of asset deposited (e.g. "1500000").
    */
-  input_amount: string | null;
+  raw_amount: string;
 
   /**
-   * Token address or "native" for the token being sold.
+   * Vault shares received in base units. Populated after on-chain confirmation.
    */
-  input_token: string;
+  share_amount: string | null;
 
   /**
-   * Exact base-unit amount of output token. Populated after on-chain confirmation.
+   * Status of a wallet action.
    */
-  output_amount: string | null;
+  status: WalletActionStatus;
+
+  type: 'earn_deposit';
 
   /**
-   * Token address or "native" for the token being bought.
+   * ERC-4626 vault contract address.
    */
-  output_token: string;
+  vault_address: string;
 
   /**
-   * Status of a wallet action.
+   * The vault ID.
    */
-  status: WalletActionStatus;
-
-  type: 'swap';
+  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.
    */
@@ -188,45 +191,58 @@ export interface SwapActionResponse {
 }
 
 /**
- * Response for a transfer action.
+ * Input for depositing assets into an ERC-4626 vault. Exactly one of `amount` or
+ * `raw_amount` must be provided.
  */
-export interface TransferActionResponse {
+export interface EarnDepositRequestBody {
   /**
-   * The ID of the wallet action.
+   * The ID of the vault to deposit into.
    */
-  id: string;
+  vault_id: string;
 
   /**
-   * ISO 8601 timestamp of when the wallet action was created.
+   * Human-readable decimal amount to deposit (e.g. "1.5" for 1.5 USDC). Exactly one
+   * of `amount` or `raw_amount` must be provided.
    */
-  created_at: string;
+  amount?: string;
 
   /**
-   * Recipient address.
+   * 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.
    */
-  destination_address: string;
+  raw_amount?: string;
+}
+
+/**
+ * Response for an earn incentive claim action.
+ */
+export interface EarnIncentiveClaimActionResponse {
+  /**
+   * The ID of the wallet action.
+   */
+  id: string;
 
   /**
-   * Decimal amount as the user provided (e.g. "1.5").
+   * EVM chain name (e.g. "base", "ethereum").
    */
-  source_amount: string;
+  chain: string;
 
   /**
-   * Asset identifier (e.g. "usdc", "eth").
+   * ISO 8601 timestamp of when the wallet action was created.
    */
-  source_asset: string;
+  created_at: string;
 
   /**
-   * Chain name (e.g. "base", "ethereum").
+   * Claimed reward tokens. Populated after the preparation step fetches from Merkl.
    */
-  source_chain: string;
+  rewards: Array<EarnIncetiveClaimRewardEntry> | null;
 
   /**
    * Status of a wallet action.
    */
   status: WalletActionStatus;
 
-  type: 'transfer';
+  type: 'earn_incentive_claim';
 
   /**
    * The ID of the wallet involved in the action.
@@ -244,6 +260,18 @@ export interface TransferActionResponse {
   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.
  */
@@ -262,12 +290,17 @@ export interface EarnIncetiveClaimRewardEntry {
    * 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 deposit action.
+ * Response for an earn withdraw action.
  */
-export interface EarnDepositActionResponse {
+export interface EarnWithdrawActionResponse {
   /**
    * The ID of the wallet action.
    */
@@ -289,12 +322,12 @@ export interface EarnDepositActionResponse {
   created_at: string;
 
   /**
-   * Base-unit amount of asset deposited (e.g. "1500000").
+   * Base-unit amount of asset withdrawn (e.g. "1500000").
    */
   raw_amount: string;
 
   /**
-   * Vault shares received in base units. Populated after on-chain confirmation.
+   * Vault shares burned in base units. Populated after on-chain confirmation.
    */
   share_amount: string | null;
 
@@ -303,7 +336,7 @@ export interface EarnDepositActionResponse {
    */
   status: WalletActionStatus;
 
-  type: 'earn_deposit';
+  type: 'earn_withdraw';
 
   /**
    * ERC-4626 vault contract address.
@@ -321,7 +354,7 @@ export interface EarnDepositActionResponse {
   wallet_id: string;
 
   /**
-   * Human-readable decimal amount of asset deposited (e.g. "1.5"). Only present when
+   * Human-readable decimal amount of asset withdrawn (e.g. "1.5"). Only present when
    * the token is known in the asset registry.
    */
   amount?: string;
@@ -350,103 +383,198 @@ export interface EarnDepositActionResponse {
 }
 
 /**
- * Response for an earn withdraw action.
+ * Input for withdrawing assets from an ERC-4626 vault. Exactly one of `amount` or
+ * `raw_amount` must be provided.
  */
-export interface EarnWithdrawActionResponse {
+export interface EarnWithdrawRequestBody {
   /**
-   * The ID of the wallet action.
+   * 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;
 
   /**
-   * Underlying asset token address.
+   * Annual percentage yield earned by the app from fee wrapper fees, in basis
+   * points.
    */
-  asset_address: string;
+  app_apy: number | null;
 
   /**
-   * CAIP-2 chain identifier.
+   * Asset metadata for an earn vault position.
    */
-  caip2: string;
+  asset: EarnAsset;
 
   /**
-   * ISO 8601 timestamp of when the wallet action was created.
+   * Available liquidity in USD.
    */
-  created_at: string;
+  available_liquidity_usd: number | null;
 
   /**
-   * Base-unit amount of asset withdrawn (e.g. "1500000").
+   * CAIP-2 chain identifier (e.g. "eip155:8453").
    */
-  raw_amount: string;
+  caip2: string;
 
   /**
-   * Vault shares burned in base units. Populated after on-chain confirmation.
+   * Human-readable vault name from the yield provider.
    */
-  share_amount: string | null;
+  name: string;
 
   /**
-   * Status of a wallet action.
+   * Supported earn provider protocols.
    */
-  status: WalletActionStatus;
+  provider: EthereumEarnProvider;
 
-  type: 'earn_withdraw';
+  /**
+   * Total value locked in USD.
+   */
+  tvl_usd: number | null;
 
   /**
-   * ERC-4626 vault contract address.
+   * Current annual percentage yield in basis points (e.g. 500 for 5%). 1 basis point
+   * = 0.01%.
    */
-  vault_address: string;
+  user_apy: number | null;
 
   /**
-   * The vault ID.
+   * Onchain vault contract address.
    */
-  vault_id: string;
+  vault_address: string;
+}
 
+/**
+ * A description of why a wallet action (or a step within a wallet action) failed.
+ */
+export interface FailureReason {
   /**
-   * The ID of the wallet involved in the action.
+   * Human-readable failure message.
    */
-  wallet_id: string;
+  message: string;
 
   /**
-   * Human-readable decimal amount of asset withdrawn (e.g. "1.5"). Only present when
-   * the token is known in the asset registry.
+   * Additional error details, if available.
    */
-  amount?: string;
+  details?: unknown;
+}
 
+/**
+ * A wallet action step consisting of an SVM (Solana) transaction.
+ */
+export interface SvmTransactionWalletActionStep {
   /**
-   * Asset identifier (e.g. "usdc", "eth"). Only present when the token is known in
-   * the asset registry.
+   * CAIP-2 chain identifier for the Solana network.
    */
-  asset?: string;
+  caip2: 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.
+   * Status of an SVM step in a wallet action.
    */
-  decimals?: number;
+  status: SvmWalletActionStepStatus;
 
   /**
-   * A description of why a wallet action (or a step within a wallet action) failed.
+   * The Solana transaction signature (base58-encoded). Null until broadcast.
    */
-  failure_reason?: FailureReason;
+  transaction_signature: string | null;
+
+  type: 'svm_transaction';
 
   /**
-   * The steps of the wallet action. Only returned if `?include=steps` is provided.
+   * A description of why a wallet action (or a step within a wallet action) failed.
    */
-  steps?: Array<WalletActionStep>;
+  failure_reason?: FailureReason;
 }
 
 /**
- * Response for an earn incentive claim action.
+ * Status of an SVM step in a wallet action.
  */
-export interface EarnIncentiveClaimActionResponse {
+export type SvmWalletActionStepStatus =
+  | 'preparing'
+  | 'queued'
+  | 'pending'
+  | 'confirmed'
+  | 'finalized'
+  | 'rejected'
+  | 'reverted'
+  | 'failed';
+
+/**
+ * Response for a swap action.
+ */
+export interface SwapActionResponse {
   /**
    * The ID of the wallet action.
    */
   id: string;
 
   /**
-   * EVM chain name (e.g. "base", "ethereum").
+   * CAIP-2 chain identifier for the swap.
    */
-  chain: string;
+  caip2: string;
 
   /**
    * ISO 8601 timestamp of when the wallet action was created.
@@ -454,16 +582,31 @@ export interface EarnIncentiveClaimActionResponse {
   created_at: string;
 
   /**
-   * Claimed reward tokens. Populated after the preparation step fetches from Merkl.
+   * Exact base-unit amount of input token. Populated after on-chain confirmation.
    */
-  rewards: Array<EarnIncetiveClaimRewardEntry> | null;
+  input_amount: string | null;
+
+  /**
+   * Token address or "native" for the token being sold.
+   */
+  input_token: string;
+
+  /**
+   * Exact base-unit amount of output token. Populated after on-chain confirmation.
+   */
+  output_amount: string | null;
+
+  /**
+   * Token address or "native" for the token being bought.
+   */
+  output_token: string;
 
   /**
    * Status of a wallet action.
    */
   status: WalletActionStatus;
 
-  type: 'earn_incentive_claim';
+  type: 'swap';
 
   /**
    * The ID of the wallet involved in the action.
@@ -482,92 +625,156 @@ export interface EarnIncentiveClaimActionResponse {
 }
 
 /**
- * Response for a wallet action, discriminated on type.
+ * Response for a transfer action.
  */
-export type WalletActionResponse =
-  | SwapActionResponse
-  | TransferActionResponse
-  | EarnDepositActionResponse
-  | EarnWithdrawActionResponse
-  | EarnIncentiveClaimActionResponse;
+export interface TransferActionResponse {
+  /**
+   * The ID of the wallet action.
+   */
+  id: string;
 
-/**
- * Input for depositing assets into an ERC-4626 vault. Exactly one of `amount` or
- * `raw_amount` must be provided.
- */
-export interface EarnDepositRequestBody {
   /**
-   * The ID of the vault to deposit into.
+   * ISO 8601 timestamp of when the wallet action was created.
    */
-  vault_id: string;
+  created_at: string;
 
   /**
-   * Human-readable decimal amount to deposit (e.g. "1.5" for 1.5 USDC). Exactly one
-   * of `amount` or `raw_amount` must be provided.
+   * Recipient address.
    */
-  amount?: string;
+  destination_address: 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.
+   * Chain name (e.g. "base", "ethereum").
    */
-  raw_amount?: string;
-}
+  source_chain: string;
 
-/**
- * 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.
+   * Status of a wallet action.
    */
-  vault_id: string;
+  status: WalletActionStatus;
+
+  type: 'transfer';
 
   /**
-   * Human-readable decimal amount to withdraw (e.g. "1.5" for 1.5 USDC). Exactly one
-   * of `amount` or `raw_amount` must be provided.
+   * The ID of the wallet involved in the action.
    */
-  amount?: string;
+  wallet_id: 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.
+   * Amount received on the destination chain. Populated immediately for exact_output
+   * transfers, or after fill confirmation for exact_input transfers.
    */
-  raw_amount?: string;
-}
+  destination_amount?: string;
 
-/**
- * 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.
+   * Destination asset for cross-asset transfers. Omitted for same-asset transfers.
    */
-  chain: string;
+  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.
+   */
+  steps?: Array<WalletActionStep>;
 }
 
+/**
+ * Response for a wallet action, discriminated on type.
+ */
+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 SwapActionResponse as SwapActionResponse,
-    type TransferActionResponse as TransferActionResponse,
-    type EarnIncetiveClaimRewardEntry as EarnIncetiveClaimRewardEntry,
+    type EvmWalletActionStepStatus as EvmWalletActionStepStatus,
+    type EarnAsset as EarnAsset,
     type EarnDepositActionResponse as EarnDepositActionResponse,
-    type EarnWithdrawActionResponse as EarnWithdrawActionResponse,
-    type EarnIncentiveClaimActionResponse as EarnIncentiveClaimActionResponse,
-    type WalletActionResponse as WalletActionResponse,
     type EarnDepositRequestBody as EarnDepositRequestBody,
-    type EarnWithdrawRequestBody as EarnWithdrawRequestBody,
+    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,
   };
 }