@frontiertower/frontier-sdk 0.11.2 → 0.12.0

package/README.md

@@ -30,12 +30,12 @@ if (!isInFrontierApp()) {
 // Access wallet information
 /**
  * The wallet balance is split into two types:
- * - Frontier Dollar (FTD): Freely convertible to fiat currency.
- * - Internal Frontier Dollar: Only convertible by Frontier Tower representatives;
+ * - Frontier Network Dollar (FND): Freely convertible to fiat currency.
+ * - Internal Frontier Network Dollar (iFND): Only convertible by Frontier Tower representatives;
  *   designed for circulation within the Network Society.
  */
 const balance = await sdk.getWallet().getBalance();
-console.log('Total FTD:', balance.total.toString());
+console.log('Total FND:', balance.total.toString());
 const address = await sdk.getWallet().getAddress();
 
 // Use persistent storage
@@ -58,12 +58,18 @@ Your app must declare required permissions in the Frontier app registry:
 - `wallet:transferNative` - Transfer native currency (ETH)
 - `wallet:transferFrontierDollar` - Transfer Frontier Dollars
 - `wallet:transferInternalFrontierDollar` - Transfer Internal Frontier Dollars
-- `wallet:transferOverallFrontierDollar` - Transfer Frontier Dollars with iFTD preferred
+- `wallet:transferOverallFrontierDollar` - Transfer Frontier Dollars with iFND preferred
 - `wallet:executeCall` - Execute arbitrary contract calls
 - `wallet:executeBatchCall` - Execute multiple contract calls atomically
 - `wallet:getSupportedTokens` - Get list of supported tokens for swaps
 - `wallet:swap` - Execute token swaps (same-chain or cross-chain)
 - `wallet:quoteSwap` - Get quotes for token swaps
+- `wallet:getUsdDepositInstructions` - Get USD bank deposit instructions for fiat on-ramp
+- `wallet:getEurDepositInstructions` - Get EUR (SEPA) deposit instructions for fiat on-ramp
+- `wallet:getLinkedBanks` - Get linked bank accounts for withdrawals (off-ramp)
+- `wallet:linkUsBankAccount` - Link a US bank account for USD withdrawals
+- `wallet:linkEuroAccount` - Link a EUR/IBAN bank account for EUR withdrawals
+- `wallet:deleteLinkedBank` - Delete a linked bank account
 
 ### Storage Permissions
 - `storage:get` - Read from storage
@@ -77,6 +83,7 @@ Your app must declare required permissions in the Frontier app registry:
 - `user:getReferralOverview` - Access referral statistics
 - `user:getReferralDetails` - Access detailed referral information
 - `user:addUserContact` - Add user contact information
+- `user:getOrCreateKyc` - Get or create KYC verification status
 
 ### Partnerships Permissions
 - `partnerships:listSponsors` - List sponsors you manage (paginated)

package/dist/index.d.mts

@@ -23,12 +23,12 @@ interface SmartAccount {
  * Wallet balance breakdown
  */
 interface WalletBalance {
-    /** Total balance including both native and internal FTD */
+    /** Total balance including both native and internal FND */
     total: bigint;
-    /** Native Frontier Dollar balance */
-    ftd: bigint;
-    /** Internal Frontier Dollar balance (for Network Society) */
-    internalFtd: bigint;
+    /** Native Frontier Network Dollar balance */
+    fnd: bigint;
+    /** Internal Frontier Network Dollar balance (for Network Society) */
+    internalFnd: bigint;
 }
 /**
  * Formatted wallet balance breakdown
@@ -36,10 +36,10 @@ interface WalletBalance {
 interface WalletBalanceFormatted {
     /** Total balance formatted with currency symbol */
     total: string;
-    /** Native Frontier Dollar balance formatted with currency symbol */
-    ftd: string;
-    /** Internal Frontier Dollar balance formatted with currency symbol */
-    internalFtd: string;
+    /** Native Frontier Network Dollar balance formatted with currency symbol */
+    fnd: string;
+    /** Internal Frontier Network Dollar balance formatted with currency symbol */
+    internalFnd: string;
 }
 /**
  * Transaction receipt from a user operation
@@ -130,6 +130,107 @@ interface SwapQuote {
     /** Minimum output amount in human-readable format */
     minAmountOut: string;
 }
+/**
+ * USD deposit instructions for fiat on-ramp
+ */
+interface UsdDepositInstructions {
+    /** Currency type */
+    currency: 'usd';
+    /** Bank name */
+    bankName: string;
+    /** Bank address */
+    bankAddress: string;
+    /** Bank routing number (ABA) */
+    bankRoutingNumber: string;
+    /** Bank account number */
+    bankAccountNumber: string;
+    /** Beneficiary name for the transfer */
+    bankBeneficiaryName: string;
+    /** Payment rail (e.g., 'ach', 'wire') */
+    paymentRail: string;
+}
+/**
+ * EUR deposit instructions for fiat on-ramp (SEPA)
+ */
+interface EurDepositInstructions {
+    /** Currency type */
+    currency: 'eur';
+    /** IBAN for SEPA transfer */
+    iban: string;
+    /** BIC/SWIFT code */
+    bic: string;
+    /** Bank name */
+    bankName: string;
+    /** Beneficiary name for the transfer */
+    beneficiaryName: string;
+}
+/**
+ * Response containing deposit instructions for fiat on-ramp
+ */
+interface OnRampResponse<T = UsdDepositInstructions | EurDepositInstructions> {
+    /** Currency type ('usd' or 'eur') */
+    currency: 'usd' | 'eur';
+    /** Deposit instructions specific to the currency */
+    depositInstructions: T;
+    /** Destination address where stablecoins will be sent */
+    destinationAddress: string;
+}
+/**
+ * Linked bank account for withdrawals (off-ramp)
+ */
+interface LinkedBank {
+    /** External account ID */
+    id: string;
+    /** Bank name */
+    bankName: string;
+    /** Last 4 digits of account number */
+    last4: string;
+    /** Withdrawal address for this bank */
+    withdrawalAddress: string;
+    /** Chain for withdrawals */
+    chain: string;
+}
+/**
+ * Response containing linked bank accounts
+ */
+interface LinkedBanksResponse {
+    /** List of linked bank accounts */
+    banks: LinkedBank[];
+}
+/**
+ * Response from linking a bank account
+ */
+interface LinkBankResponse {
+    /** External account ID */
+    externalAccountId: string;
+    /** Bank name */
+    bankName: string;
+    /** Withdrawal address for this bank */
+    withdrawalAddress: string;
+    /** Chain for withdrawals */
+    chain: string;
+}
+/**
+ * Billing address for bank account linking
+ */
+interface BillingAddress {
+    /** Street address line 1 */
+    streetLine1: string;
+    /** Street address line 2 (optional) */
+    streetLine2?: string;
+    /** City */
+    city: string;
+    /** State/Province */
+    state: string;
+    /** Postal/ZIP code */
+    postalCode: string;
+    /** Country code (e.g., 'USA') */
+    country: string;
+}
+/**
+ * Account owner type for IBAN accounts
+ */
+type AccountOwnerType = 'individual' | 'business';
 /**
  * Wallet access class for interacting with the user's wallet
  *
@@ -148,8 +249,8 @@ declare class WalletAccess {
     /**
      * Get the current wallet balance breakdown
      *
-     * Returns the balance breakdown including total, native FTD,
-     * and internal FTD amounts.
+     * Returns the balance breakdown including total, native FND,
+     * and internal FND amounts.
      *
      * @returns Balance breakdown object
      * @throws {Error} If no wallet exists
@@ -158,7 +259,7 @@ declare class WalletAccess {
      * ```typescript
      * const balance = await sdk.getWallet().getBalance();
      * console.log('Total Balance:', balance.total.toString());
-     * console.log('FTD Balance:', balance.ftd.toString());
+     * console.log('FND Balance:', balance.fnd.toString());
      * ```
      */
     getBalance(): Promise<WalletBalance>;
@@ -355,7 +456,7 @@ declare class WalletAccess {
      */
     transferInternalFrontierDollar(to: string, amount: string, overrides?: GasOverrides): Promise<UserOperationReceipt>;
     /**
-     * Transfer Frontier Dollars with Internal Frontier Dollars (iFTD) preferred
+     * Transfer Frontier Dollars with Internal Frontier Network Dollars (iFND) preferred
      *
      * This method will use Internal Frontier Dollars first, and if insufficient,
      * it will use regular Frontier Dollars to complete the transfer.
@@ -411,12 +512,12 @@ declare class WalletAccess {
      * Returns an array of token symbols that are supported for swaps
      * and other operations on the current network.
      *
-     * @returns Array of token symbols (e.g., ['FTD', 'USDC', 'WETH'])
+     * @returns Array of token symbols (e.g., ['FND', 'USDC', 'WETH'])
      *
      * @example
      * ```typescript
      * const tokens = await sdk.getWallet().getSupportedTokens();
-     * console.log('Supported tokens:', tokens); // ['FTD', 'USDC', 'WETH']
+     * console.log('Supported tokens:', tokens); // ['FND', 'USDC', 'WETH']
      * ```
      */
     getSupportedTokens(): Promise<string[]>;
@@ -472,6 +573,153 @@ declare class WalletAccess {
      * ```
      */
     quoteSwap(sourceToken: string, targetToken: string, sourceNetwork: string, targetNetwork: string, amount: string): Promise<SwapQuote>;
+    /**
+     * Get USD deposit instructions for fiat on-ramp
+     *
+     * Returns US bank details where user should send their USD deposit.
+     * The deposited fiat will be converted to stablecoins and sent to
+     * the user's wallet address.
+     *
+     * Requires approved KYC verification.
+     *
+     * @returns Bank details including routing number, account number, and beneficiary info
+     * @throws {Error} If KYC is not approved
+     *
+     * @example
+     * ```typescript
+     * const instructions = await sdk.getWallet().getUsdDepositInstructions();
+     * console.log('Bank:', instructions.depositInstructions.bankName);
+     * console.log('Routing:', instructions.depositInstructions.bankRoutingNumber);
+     * console.log('Account:', instructions.depositInstructions.bankAccountNumber);
+     * console.log('Beneficiary:', instructions.depositInstructions.bankBeneficiaryName);
+     * ```
+     */
+    getUsdDepositInstructions(): Promise<OnRampResponse<UsdDepositInstructions>>;
+    /**
+     * Get EUR deposit instructions for fiat on-ramp (SEPA)
+     *
+     * Returns SEPA bank details where user should send their EUR deposit.
+     * The deposited fiat will be converted to stablecoins and sent to
+     * the user's wallet address.
+     *
+     * Requires approved KYC verification.
+     *
+     * @returns SEPA bank details including IBAN, BIC, and beneficiary info
+     * @throws {Error} If KYC is not approved
+     *
+     * @example
+     * ```typescript
+     * const instructions = await sdk.getWallet().getEurDepositInstructions();
+     * console.log('IBAN:', instructions.depositInstructions.iban);
+     * console.log('BIC:', instructions.depositInstructions.bic);
+     * console.log('Bank:', instructions.depositInstructions.bankName);
+     * console.log('Beneficiary:', instructions.depositInstructions.beneficiaryName);
+     * ```
+     */
+    getEurDepositInstructions(): Promise<OnRampResponse<EurDepositInstructions>>;
+    /**
+     * Get all linked bank accounts for withdrawals (off-ramp)
+     *
+     * Returns a list of bank accounts that have been linked for
+     * withdrawing stablecoins to fiat.
+     *
+     * Requires approved KYC verification.
+     *
+     * @returns List of linked bank accounts with withdrawal addresses
+     * @throws {Error} If KYC is not approved
+     *
+     * @example
+     * ```typescript
+     * const { banks } = await sdk.getWallet().getLinkedBanks();
+     * banks.forEach(bank => {
+     *   console.log(`${bank.bankName} (****${bank.last4})`);
+     * });
+     * ```
+     */
+    getLinkedBanks(): Promise<LinkedBanksResponse>;
+    /**
+     * Link a US bank account for withdrawals (off-ramp)
+     *
+     * Links a US bank account (checking or savings) for withdrawing
+     * stablecoins to USD via ACH transfer.
+     *
+     * Requires approved KYC verification.
+     *
+     * @param accountOwnerName - Full name of the account owner
+     * @param bankName - Name of the bank (e.g., 'Chase', 'Bank of America')
+     * @param routingNumber - Bank routing number (9 digits)
+     * @param accountNumber - Bank account number
+     * @param checkingOrSavings - Account type: 'checking' or 'savings'
+     * @param address - Billing address for the account
+     * @returns Linked bank details with withdrawal address
+     * @throws {Error} If KYC is not approved or bank details are invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.getWallet().linkUsBankAccount(
+     *   'John Doe',
+     *   'Chase',
+     *   '121000248',
+     *   '1234567890',
+     *   'checking',
+     *   {
+     *     streetLine1: '123 Main St',
+     *     city: 'San Francisco',
+     *     state: 'CA',
+     *     postalCode: '94102',
+     *     country: 'USA'
+     *   }
+     * );
+     * console.log('Linked bank:', result.bankName);
+     * ```
+     */
+    linkUsBankAccount(accountOwnerName: string, bankName: string, routingNumber: string, accountNumber: string, checkingOrSavings: 'checking' | 'savings', address: BillingAddress): Promise<LinkBankResponse>;
+    /**
+     * Link a EUR/IBAN bank account for withdrawals (off-ramp)
+     *
+     * Links a European bank account via IBAN for withdrawing
+     * stablecoins to EUR via SEPA transfer.
+     *
+     * Requires approved KYC verification.
+     *
+     * @param accountOwnerName - Full name of the account owner
+     * @param accountOwnerType - Type of account owner: 'individual' or 'business'
+     * @param firstName - First name of the account owner
+     * @param lastName - Last name of the account owner
+     * @param ibanAccountNumber - IBAN account number
+     * @param bic - Optional BIC/SWIFT code
+     * @returns Linked bank details with withdrawal address
+     * @throws {Error} If KYC is not approved or bank details are invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.getWallet().linkEuroAccount(
+     *   'Hans Mueller',
+     *   'individual',
+     *   'Hans',
+     *   'Mueller',
+     *   'DE89370400440532013000',
+     *   'COBADEFFXXX' // optional BIC
+     * );
+     * console.log('Linked bank:', result.bankName);
+     * ```
+     */
+    linkEuroAccount(accountOwnerName: string, accountOwnerType: AccountOwnerType, firstName: string, lastName: string, ibanAccountNumber: string, bic?: string): Promise<LinkBankResponse>;
+    /**
+     * Delete a linked bank account
+     *
+     * Removes a previously linked bank account from the user's off-ramp options.
+     *
+     * @param bankId - The ID of the linked bank account to delete
+     * @throws {Error} If the bank account doesn't exist or deletion fails
+     *
+     * @example
+     * ```typescript
+     * await sdk.getWallet().deleteLinkedBank('bank_abc123');
+     * console.log('Bank account deleted');
+     * ```
+     */
+    deleteLinkedBank(bankId: string): Promise<void>;
 }
 
 /**
@@ -767,6 +1015,33 @@ interface UserContact {
     /** Contact name */
     name: string;
 }
+/**
+ * KYC verification status
+ */
+type KycStatus = 'not_started' | 'pending' | 'in_review' | 'approved' | 'rejected';
+/**
+ * Terms of Service acceptance status
+ */
+type TosStatus = 'pending' | 'approved';
+/**
+ * KYC status response
+ */
+interface KycStatusResponse {
+    /** Current KYC status */
+    status: KycStatus;
+    /** Whether KYC is approved */
+    isApproved: boolean;
+    /** Reason for rejection (if rejected) */
+    rejectionReason: string | null;
+    /** KYC link ID (if KYC has been started) */
+    kycLinkId: string | null;
+    /** URL to complete KYC verification (if KYC has been started) */
+    kycLinkUrl: string | null;
+    /** Terms of Service acceptance status */
+    tosStatus: TosStatus | null;
+    /** URL to accept Terms of Service */
+    tosLink: string | null;
+}
 /**
  * User contact information payload
  */
@@ -882,6 +1157,31 @@ declare class UserAccess {
      * ```
      */
     addUserContact(data: UserContactPayload): Promise<void>;
+    /**
+     * Get or create KYC status
+     *
+     * Returns the current KYC verification status. If KYC has not been started,
+     * it will be initiated and the response will include a URL to complete verification.
+     *
+     * @param redirectUri - Optional URL to redirect user after KYC completion
+     * @returns KycStatusResponse with status and verification link if applicable
+     * @throws {Error} If user is not authenticated
+     *
+     * @example
+     * ```typescript
+     * const kyc = await sdk.getUser().getOrCreateKyc();
+     * if (kyc.status === 'not_started' && kyc.kycLinkUrl) {
+     *   // Redirect user to complete KYC
+     *   window.open(kyc.kycLinkUrl, '_blank');
+     * } else if (kyc.isApproved) {
+     *   console.log('KYC approved!');
+     * }
+     *
+     * // With redirect URI
+     * const kycWithRedirect = await sdk.getUser().getOrCreateKyc('https://myapp.com/callback');
+     * ```
+     */
+    getOrCreateKyc(redirectUri?: string): Promise<KycStatusResponse>;
 }
 
 /**
@@ -1598,4 +1898,4 @@ interface SDKResponse {
     error?: string;
 }
 
-export { type App, type AppPermission, type AppStatus, ChainAccess, type ChainConfig, type CreateAppRequest, type CreateSponsorPassRequest, type CreateWebhookRequest, type Developer, type ExecuteCall, FrontierSDK, type GasOverrides, type ListParams, type ListSponsorsParams, type PaginatedResponse, PartnershipsAccess, type ReferralDetails, type ReferralOverview, type RotateKeyResponse, type RotateWebhookKeyResponse, type SDKRequest, type SDKResponse, type SmartAccount, type Sponsor, type SponsorPass, type StableCoin, StorageAccess, type SwapParams, type SwapQuote, type SwapResult, SwapResultStatus, ThirdPartyAccess, type Token, Underlying, type UpdateAppRequest, type UpdateDeveloperRequest, type UpdateWebhookRequest, type User, UserAccess, type UserContact, type UserContactPayload, type UserOperationReceipt, type UserProfile, WalletAccess, type WalletBalance, type WalletBalanceFormatted, type Webhook, type WebhookConfig, type WebhookEvent, type WebhookScope, type WebhookStatus };
+export { type AccountOwnerType, type App, type AppPermission, type AppStatus, type BillingAddress, ChainAccess, type ChainConfig, type CreateAppRequest, type CreateSponsorPassRequest, type CreateWebhookRequest, type Developer, type EurDepositInstructions, type ExecuteCall, FrontierSDK, type GasOverrides, type LinkBankResponse, type LinkedBank, type LinkedBanksResponse, type ListParams, type ListSponsorsParams, type OnRampResponse, type PaginatedResponse, PartnershipsAccess, type ReferralDetails, type ReferralOverview, type RotateKeyResponse, type RotateWebhookKeyResponse, type SDKRequest, type SDKResponse, type SmartAccount, type Sponsor, type SponsorPass, type StableCoin, StorageAccess, type SwapParams, type SwapQuote, type SwapResult, SwapResultStatus, ThirdPartyAccess, type Token, Underlying, type UpdateAppRequest, type UpdateDeveloperRequest, type UpdateWebhookRequest, type UsdDepositInstructions, type User, UserAccess, type UserContact, type UserContactPayload, type UserOperationReceipt, type UserProfile, WalletAccess, type WalletBalance, type WalletBalanceFormatted, type Webhook, type WebhookConfig, type WebhookEvent, type WebhookScope, type WebhookStatus };