@unifold/core 0.1.21 → 0.1.22

package/dist/index.d.mts

@@ -117,6 +117,7 @@ interface AutoSwapResponse {
     };
     source_currency?: string;
     destination_currency?: string;
+    estimated_processing_time?: number | null;
 }
 declare const SOLANA_USDC_ADDRESS = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
 interface QueryExecutionsRequest {
@@ -307,6 +308,7 @@ interface DefaultTokenResponse {
     destination_network: string;
     destination_currency: string;
     destination_token_metadata: DefaultTokenMetadata;
+    estimated_processing_time: number | null;
 }
 /**
  * Get default onramp token for a given token/chain combination
@@ -384,6 +386,93 @@ interface IpAddressResponse {
  * This is a public endpoint that doesn't require authentication
  */
 declare function getIpAddress(): Promise<IpAddressResponse>;
+interface TokenIconUrl {
+    url: string;
+    format: string;
+}
+interface TokenInfo {
+    symbol: string;
+    name: string;
+    icon_url: string;
+    icon_urls: TokenIconUrl[];
+    token_address: string;
+    chain_id: string;
+    chain_name: string;
+    chain_type: string;
+    decimals: number;
+    minimum_deposit_amount_usd: number;
+    chain_icon_url: string;
+    chain_icon_urls: TokenIconUrl[];
+}
+interface TokenBalance {
+    amount: string;
+    amount_usd: string | null;
+    exchange_rate: string | null;
+    is_eligible: boolean;
+    token: TokenInfo;
+}
+interface AddressBalancesResponse {
+    address: string;
+    chain_type: string;
+    balances: TokenBalance[];
+}
+/**
+ * Get token balances for a wallet address
+ * Returns balances for all supported deposit tokens on the specified chain type
+ * @param address - Wallet address to check balances for
+ * @param chainType - Chain type to fetch balances for ('ethereum', 'solana', or 'bitcoin')
+ * @param publishableKey - Optional publishable key, defaults to configured key
+ */
+declare function getAddressBalances(address: string, chainType: 'ethereum' | 'solana' | 'bitcoin', publishableKey?: string): Promise<AddressBalancesResponse>;
+interface AddressBalanceResponse {
+    address: string;
+    chain_type: string;
+    chain_id: string;
+    token_address: string;
+    balance: TokenBalance | null;
+}
+/**
+ * Get balance for a specific token on a specific chain
+ * Returns the balance for a single token, or null if not found or zero balance
+ * @param address - Wallet address to check balance for
+ * @param chainType - Chain type ('ethereum', 'solana', or 'bitcoin')
+ * @param chainId - Chain ID (e.g., "1" for Ethereum mainnet)
+ * @param tokenAddress - Token contract address or "native" for native tokens
+ * @param publishableKey - Optional publishable key, defaults to configured key
+ */
+declare function getAddressBalance(address: string, chainType: 'ethereum' | 'solana' | 'bitcoin', chainId: string, tokenAddress: string, publishableKey?: string): Promise<AddressBalanceResponse>;
+interface VerifyAddressRequest {
+    chain_type: string;
+    chain_id: string;
+    token_address: string;
+    recipient_address: string;
+}
+/**
+ * Standard error codes for address validation failures.
+ * Used by frontend to display localized error messages.
+ */
+type AddressValidationFailureCode = 'token_not_supported' | 'not_opted_in' | 'insufficient_balance' | 'account_not_found' | 'validation_error';
+interface AddressValidationMetadata {
+    chain_name?: string;
+    token_symbol?: string;
+}
+interface VerifyAddressResponse {
+    valid: boolean;
+    /** Standardized error code for frontend i18n */
+    failure_code?: AddressValidationFailureCode;
+    /** Metadata for message interpolation */
+    metadata?: AddressValidationMetadata;
+}
+/**
+ * Verify if a recipient address can receive funds for a given chain/token
+ * This is useful to check before confirming a transfer, especially for Algorand
+ * where recipients must opt-in to assets before receiving them.
+ *
+ * @param request - Verification request with chain_type, chain_id, token_address, recipient_address
+ * @param publishableKey - Optional publishable key, defaults to configured key
+ * @returns Verification result with valid status and reason if invalid
+ */
+declare function verifyRecipientAddress(request: VerifyAddressRequest, publishableKey?: string): Promise<VerifyAddressResponse>;
 
 /**
  * User IP information interface
@@ -479,4 +568,4 @@ declare const i18n: {
 };
 type I18nStrings = typeof i18n;
 
-export { type AutoSwapRequest, type AutoSwapResponse, type CreateDepositAddressRequest, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddressResponse, ExecutionStatus, type FeaturedToken, type FiatCurrenciesResponse, type FiatCurrency, type I18nStrings, type IconUrl, type IpAddressResponse, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionRequest, type OnrampSessionResponse, type PaymentNetwork, type ProjectConfigResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, SOLANA_USDC_ADDRESS, type SupportedChain, type SupportedDepositTokensResponse, type SupportedToken, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenMetadata, type UserIpInfo, type Wallet, createDepositAddress, createOnrampSession, getApiBaseUrl, getChainName, getDefaultOnrampToken, getFiatCurrencies, getIconUrl, getIconUrlWithCdn, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getPreferredIconUrl, getProjectConfig, getSupportedDepositTokens, getTokenChains, getTokenMetadata, getWalletByChainType, i18n, queryExecutions, setApiConfig, useUserIp };
+export { type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, type AutoSwapRequest, type AutoSwapResponse, type CreateDepositAddressRequest, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddressResponse, ExecutionStatus, type FeaturedToken, type FiatCurrenciesResponse, type FiatCurrency, type I18nStrings, type IconUrl, type IpAddressResponse, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionRequest, type OnrampSessionResponse, type PaymentNetwork, type ProjectConfigResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, SOLANA_USDC_ADDRESS, type SupportedChain, type SupportedDepositTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenIconUrl, type TokenInfo, type TokenMetadata, type UserIpInfo, type VerifyAddressRequest, type VerifyAddressResponse, type Wallet, createDepositAddress, createOnrampSession, getAddressBalance, getAddressBalances, getApiBaseUrl, getChainName, getDefaultOnrampToken, getFiatCurrencies, getIconUrl, getIconUrlWithCdn, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getPreferredIconUrl, getProjectConfig, getSupportedDepositTokens, getTokenChains, getTokenMetadata, getWalletByChainType, i18n, queryExecutions, setApiConfig, useUserIp, verifyRecipientAddress };

package/dist/index.d.ts

@@ -117,6 +117,7 @@ interface AutoSwapResponse {
     };
     source_currency?: string;
     destination_currency?: string;
+    estimated_processing_time?: number | null;
 }
 declare const SOLANA_USDC_ADDRESS = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
 interface QueryExecutionsRequest {
@@ -307,6 +308,7 @@ interface DefaultTokenResponse {
     destination_network: string;
     destination_currency: string;
     destination_token_metadata: DefaultTokenMetadata;
+    estimated_processing_time: number | null;
 }
 /**
  * Get default onramp token for a given token/chain combination
@@ -384,6 +386,93 @@ interface IpAddressResponse {
  * This is a public endpoint that doesn't require authentication
  */
 declare function getIpAddress(): Promise<IpAddressResponse>;
+interface TokenIconUrl {
+    url: string;
+    format: string;
+}
+interface TokenInfo {
+    symbol: string;
+    name: string;
+    icon_url: string;
+    icon_urls: TokenIconUrl[];
+    token_address: string;
+    chain_id: string;
+    chain_name: string;
+    chain_type: string;
+    decimals: number;
+    minimum_deposit_amount_usd: number;
+    chain_icon_url: string;
+    chain_icon_urls: TokenIconUrl[];
+}
+interface TokenBalance {
+    amount: string;
+    amount_usd: string | null;
+    exchange_rate: string | null;
+    is_eligible: boolean;
+    token: TokenInfo;
+}
+interface AddressBalancesResponse {
+    address: string;
+    chain_type: string;
+    balances: TokenBalance[];
+}
+/**
+ * Get token balances for a wallet address
+ * Returns balances for all supported deposit tokens on the specified chain type
+ * @param address - Wallet address to check balances for
+ * @param chainType - Chain type to fetch balances for ('ethereum', 'solana', or 'bitcoin')
+ * @param publishableKey - Optional publishable key, defaults to configured key
+ */
+declare function getAddressBalances(address: string, chainType: 'ethereum' | 'solana' | 'bitcoin', publishableKey?: string): Promise<AddressBalancesResponse>;
+interface AddressBalanceResponse {
+    address: string;
+    chain_type: string;
+    chain_id: string;
+    token_address: string;
+    balance: TokenBalance | null;
+}
+/**
+ * Get balance for a specific token on a specific chain
+ * Returns the balance for a single token, or null if not found or zero balance
+ * @param address - Wallet address to check balance for
+ * @param chainType - Chain type ('ethereum', 'solana', or 'bitcoin')
+ * @param chainId - Chain ID (e.g., "1" for Ethereum mainnet)
+ * @param tokenAddress - Token contract address or "native" for native tokens
+ * @param publishableKey - Optional publishable key, defaults to configured key
+ */
+declare function getAddressBalance(address: string, chainType: 'ethereum' | 'solana' | 'bitcoin', chainId: string, tokenAddress: string, publishableKey?: string): Promise<AddressBalanceResponse>;
+interface VerifyAddressRequest {
+    chain_type: string;
+    chain_id: string;
+    token_address: string;
+    recipient_address: string;
+}
+/**
+ * Standard error codes for address validation failures.
+ * Used by frontend to display localized error messages.
+ */
+type AddressValidationFailureCode = 'token_not_supported' | 'not_opted_in' | 'insufficient_balance' | 'account_not_found' | 'validation_error';
+interface AddressValidationMetadata {
+    chain_name?: string;
+    token_symbol?: string;
+}
+interface VerifyAddressResponse {
+    valid: boolean;
+    /** Standardized error code for frontend i18n */
+    failure_code?: AddressValidationFailureCode;
+    /** Metadata for message interpolation */
+    metadata?: AddressValidationMetadata;
+}
+/**
+ * Verify if a recipient address can receive funds for a given chain/token
+ * This is useful to check before confirming a transfer, especially for Algorand
+ * where recipients must opt-in to assets before receiving them.
+ *
+ * @param request - Verification request with chain_type, chain_id, token_address, recipient_address
+ * @param publishableKey - Optional publishable key, defaults to configured key
+ * @returns Verification result with valid status and reason if invalid
+ */
+declare function verifyRecipientAddress(request: VerifyAddressRequest, publishableKey?: string): Promise<VerifyAddressResponse>;
 
 /**
  * User IP information interface
@@ -479,4 +568,4 @@ declare const i18n: {
 };
 type I18nStrings = typeof i18n;
 
-export { type AutoSwapRequest, type AutoSwapResponse, type CreateDepositAddressRequest, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddressResponse, ExecutionStatus, type FeaturedToken, type FiatCurrenciesResponse, type FiatCurrency, type I18nStrings, type IconUrl, type IpAddressResponse, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionRequest, type OnrampSessionResponse, type PaymentNetwork, type ProjectConfigResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, SOLANA_USDC_ADDRESS, type SupportedChain, type SupportedDepositTokensResponse, type SupportedToken, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenMetadata, type UserIpInfo, type Wallet, createDepositAddress, createOnrampSession, getApiBaseUrl, getChainName, getDefaultOnrampToken, getFiatCurrencies, getIconUrl, getIconUrlWithCdn, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getPreferredIconUrl, getProjectConfig, getSupportedDepositTokens, getTokenChains, getTokenMetadata, getWalletByChainType, i18n, queryExecutions, setApiConfig, useUserIp };
+export { type AddressBalanceResponse, type AddressBalancesResponse, type AddressValidationFailureCode, type AddressValidationMetadata, type AutoSwapRequest, type AutoSwapResponse, type CreateDepositAddressRequest, type DefaultTokenChain, type DefaultTokenMetadata, type DefaultTokenResponse, type DepositAddressResponse, ExecutionStatus, type FeaturedToken, type FiatCurrenciesResponse, type FiatCurrency, type I18nStrings, type IconUrl, type IpAddressResponse, type OnrampQuote, type OnrampQuotesRequest, type OnrampQuotesResponse, type OnrampSessionRequest, type OnrampSessionResponse, type PaymentNetwork, type ProjectConfigResponse, type QueryExecutionsRequest, type QueryExecutionsResponse, SOLANA_USDC_ADDRESS, type SupportedChain, type SupportedDepositTokensResponse, type SupportedToken, type TokenBalance, type TokenChain, type TokenChainIconUrl, type TokenChainsResponse, type TokenIconUrl, type TokenInfo, type TokenMetadata, type UserIpInfo, type VerifyAddressRequest, type VerifyAddressResponse, type Wallet, createDepositAddress, createOnrampSession, getAddressBalance, getAddressBalances, getApiBaseUrl, getChainName, getDefaultOnrampToken, getFiatCurrencies, getIconUrl, getIconUrlWithCdn, getIpAddress, getOnrampQuotes, getOnrampSessionStartUrl, getPreferredIconUrl, getProjectConfig, getSupportedDepositTokens, getTokenChains, getTokenMetadata, getWalletByChainType, i18n, queryExecutions, setApiConfig, useUserIp, verifyRecipientAddress };

package/dist/index.js

@@ -24,6 +24,8 @@ __export(index_exports, {
   SOLANA_USDC_ADDRESS: () => SOLANA_USDC_ADDRESS,
   createDepositAddress: () => createDepositAddress,
   createOnrampSession: () => createOnrampSession,
+  getAddressBalance: () => getAddressBalance,
+  getAddressBalances: () => getAddressBalances,
   getApiBaseUrl: () => getApiBaseUrl,
   getChainName: () => getChainName,
   getDefaultOnrampToken: () => getDefaultOnrampToken,
@@ -42,7 +44,8 @@ __export(index_exports, {
   i18n: () => i18n,
   queryExecutions: () => queryExecutions,
   setApiConfig: () => setApiConfig,
-  useUserIp: () => useUserIp
+  useUserIp: () => useUserIp,
+  verifyRecipientAddress: () => verifyRecipientAddress
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -330,12 +333,14 @@ async function getTokenChains() {
   return response.json();
 }
 function getChainName(chains, chainType, chainId) {
+  if (!chainType && !chainId) return "Unknown";
   const target = chains.find((c) => c.chain_id === chainId && c.chain_type === chainType);
   if (target) return target.chain_name;
   const byId = chains.find((c) => c.chain_id === chainId);
   if (byId) return byId.chain_name;
   const byType = chains.find((c) => c.chain_type === chainType);
   if (byType) return byType.chain_name;
+  if (!chainType) return chainId || "Unknown";
   return chainType.charAt(0).toUpperCase() + chainType.slice(1);
 }
 async function getProjectConfig(publishableKey) {
@@ -369,6 +374,71 @@ async function getIpAddress() {
   }
   return response.json();
 }
+async function getAddressBalances(address, chainType, publishableKey) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const url = `${API_BASE_URL}/v1/public/addresses/balances`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      accept: "application/json",
+      "x-publishable-key": pk
+    },
+    body: JSON.stringify({
+      address,
+      chain_type: chainType
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch address balances: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data;
+}
+async function getAddressBalance(address, chainType, chainId, tokenAddress, publishableKey) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const url = `${API_BASE_URL}/v1/public/addresses/balance`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      accept: "application/json",
+      "x-publishable-key": pk
+    },
+    body: JSON.stringify({
+      address,
+      chain_type: chainType,
+      chain_id: chainId,
+      token_address: tokenAddress
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch address balance: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data;
+}
+async function verifyRecipientAddress(request, publishableKey) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const response = await fetch(`${API_BASE_URL}/v1/public/addresses/verify`, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "x-publishable-key": pk,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(request)
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to verify recipient address: ${response.statusText}`
+    );
+  }
+  return response.json();
+}
 
 // src/hooks/use-user-ip.ts
 var import_react_query = require("@tanstack/react-query");
@@ -479,6 +549,8 @@ var i18n = en_default;
   SOLANA_USDC_ADDRESS,
   createDepositAddress,
   createOnrampSession,
+  getAddressBalance,
+  getAddressBalances,
   getApiBaseUrl,
   getChainName,
   getDefaultOnrampToken,
@@ -497,5 +569,6 @@ var i18n = en_default;
   i18n,
   queryExecutions,
   setApiConfig,
-  useUserIp
+  useUserIp,
+  verifyRecipientAddress
 });

package/dist/index.mjs

@@ -282,12 +282,14 @@ async function getTokenChains() {
   return response.json();
 }
 function getChainName(chains, chainType, chainId) {
+  if (!chainType && !chainId) return "Unknown";
   const target = chains.find((c) => c.chain_id === chainId && c.chain_type === chainType);
   if (target) return target.chain_name;
   const byId = chains.find((c) => c.chain_id === chainId);
   if (byId) return byId.chain_name;
   const byType = chains.find((c) => c.chain_type === chainType);
   if (byType) return byType.chain_name;
+  if (!chainType) return chainId || "Unknown";
   return chainType.charAt(0).toUpperCase() + chainType.slice(1);
 }
 async function getProjectConfig(publishableKey) {
@@ -321,6 +323,71 @@ async function getIpAddress() {
   }
   return response.json();
 }
+async function getAddressBalances(address, chainType, publishableKey) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const url = `${API_BASE_URL}/v1/public/addresses/balances`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      accept: "application/json",
+      "x-publishable-key": pk
+    },
+    body: JSON.stringify({
+      address,
+      chain_type: chainType
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch address balances: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data;
+}
+async function getAddressBalance(address, chainType, chainId, tokenAddress, publishableKey) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const url = `${API_BASE_URL}/v1/public/addresses/balance`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      accept: "application/json",
+      "x-publishable-key": pk
+    },
+    body: JSON.stringify({
+      address,
+      chain_type: chainType,
+      chain_id: chainId,
+      token_address: tokenAddress
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch address balance: ${response.statusText}`);
+  }
+  const data = await response.json();
+  return data;
+}
+async function verifyRecipientAddress(request, publishableKey) {
+  const pk = publishableKey || DEFAULT_PUBLISHABLE_KEY;
+  validatePublishableKey(pk);
+  const response = await fetch(`${API_BASE_URL}/v1/public/addresses/verify`, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "x-publishable-key": pk,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(request)
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to verify recipient address: ${response.statusText}`
+    );
+  }
+  return response.json();
+}
 
 // src/hooks/use-user-ip.ts
 import { useQuery } from "@tanstack/react-query";
@@ -430,6 +497,8 @@ export {
   SOLANA_USDC_ADDRESS,
   createDepositAddress,
   createOnrampSession,
+  getAddressBalance,
+  getAddressBalances,
   getApiBaseUrl,
   getChainName,
   getDefaultOnrampToken,
@@ -448,5 +517,6 @@ export {
   i18n,
   queryExecutions,
   setApiConfig,
-  useUserIp
+  useUserIp,
+  verifyRecipientAddress
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifold/core",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Unifold Core SDK - Core types, API client, and business logic",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",