@fystack/sdk 0.1.10 → 0.1.11

package/readme.md

@@ -1,6 +1,6 @@
 # Fystack Platform SDK
 
-A Typescript SDK for Fystack's wallet and payment services, providing seamless integration with both EVM and Solana blockchains.
+A TypeScript SDK for Fystack's wallet and payment services, providing seamless integration with EVM, Solana, and Tron blockchains.
 
 ## Installation
 
@@ -8,199 +8,244 @@ A Typescript SDK for Fystack's wallet and payment services, providing seamless i
 npm install @fystack/sdk
 ```
 
-## Usage
-
-### Wallet Management
-
-Create and manage blockchain wallets with minimal code.
+## Quick Start
 
 ```typescript
-import { FystackSDK } from '@fystack/sdk'
-import { Environment, WalletType } from '@fystack/sdk'
+import { FystackSDK, Environment } from '@fystack/sdk'
 
-// Initialize the SDK
+// Find your workspace ID at https://app.fystack.io -> Developers -> API Key
 const sdk = new FystackSDK({
   credentials: {
     apiKey: 'YOUR_API_KEY',
     apiSecret: 'YOUR_API_SECRET'
   },
+  workspaceId: 'YOUR_WORKSPACE_ID',
   environment: Environment.Production,
-  logger: true // Enable logging
+  debug: true // Enable debug logging
 })
+```
 
-const response = await sdk.createWallet({
-  name: 'My Blockchain Wallet',
-  walletType: WalletType.MPC, // Multi-Party Computation wallet
-  walletPurpose: WalletPurpose.User,
-  sweepTaskParams: {
-    minTriggerValueUsd: 100,
-    destinationWalletId: '0e123131211323xx1213',
-    destinationType: DestinationType.InternalWallet
-  }
+## Create Wallet
+
+Fystack supports two wallet types:
+
+- **Hyper** — Instantly created wallet. No async provisioning needed.
+- **MPC** — Multi-Party Computation wallet with distributed key management. Creation is async and requires polling for status.
+
+### Hyper Wallet
+
+```typescript
+import { WalletType, WalletPurpose } from '@fystack/sdk'
+
+const wallet = await sdk.createWallet({
+  name: 'Treasury Wallet',
+  walletType: WalletType.Hyper,
+  walletPurpose: WalletPurpose.General
 })
 
-console.log('Wallet ID:', response.wallet_id)
-console.log('Status:', response.status)
+console.log('Wallet ID:', wallet.wallet_id)
+```
+
+### MPC Wallet
+
+MPC wallets are provisioned asynchronously. By default, `createWallet` waits for provisioning to complete before returning:
+
+```typescript
+const wallet = await sdk.createWallet({
+  name: 'MPC Wallet',
+  walletType: WalletType.MPC,
+  walletPurpose: WalletPurpose.General
+})
 
-// Check wallet creation status
-const statusResponse = await sdk.getWalletCreationStatus(response.wallet_id)
-console.log('WalletID:', statusResponse.wallet_id)
+console.log('Wallet ID:', wallet.wallet_id)
+console.log('Status:', wallet.status) // 'success' or 'error'
 ```
 
-### Solana Transaction Signing
+To return immediately and poll status manually:
 
 ```typescript
-import { SolanaSigner } from '@fystack/sdk'
-import { Connection, PublicKey, SystemProgram, Transaction } from '@solana/web3.js'
+const wallet = await sdk.createWallet(
+  { name: 'MPC Wallet', walletType: WalletType.MPC },
+  false // don't wait for completion
+)
+
+// Poll status every 2 seconds until provisioned
+const interval = setInterval(async () => {
+  const status = await sdk.getWalletCreationStatus(wallet.wallet_id)
+  console.log('Status:', status.status)
+
+  if (status.status === 'success' || status.status === 'error') {
+    clearInterval(interval)
+  }
+}, 2000)
+```
+
+## Get Deposit Address
+
+Retrieve deposit addresses for a specific wallet and address type.
+
+```typescript
+import { AddressType } from '@fystack/sdk'
+
+// Get EVM deposit address
+const evm = await sdk.getDepositAddress(wallet.wallet_id, AddressType.Evm)
+console.log('EVM Address:', evm.address)
+
+// Get Solana deposit address
+const sol = await sdk.getDepositAddress(wallet.wallet_id, AddressType.Solana)
+console.log('Solana Address:', sol.address)
+
+// Get Tron deposit address
+const tron = await sdk.getDepositAddress(wallet.wallet_id, AddressType.Tron)
+console.log('Tron Address:', tron.address)
+```
+
+## Create Withdrawal
+
+Request a withdrawal from a wallet to an external address.
+
+```typescript
+const withdrawal = await sdk.requestWithdrawal('WALLET_ID', {
+  assetId: 'ASSET_UUID',
+  amount: '10.5',
+  recipientAddress: '0xRecipientAddress',
+  notes: 'Monthly payout'
+})
 
-async function signSolanaTransaction() {
-  // Initialize the signer
-  const signer = new SolanaSigner(
-    {
-      apiKey: 'YOUR_API_KEY',
-      apiSecret: 'YOUR_API_SECRET'
-    },
-    Environment.Production
-  )
-
-  // Get signer's address
-  const fromAddress = await signer.getAddress()
-  const fromPubkey = new PublicKey(fromAddress)
-
-  // Set recipient address
-  const toAddress = 'RECIPIENT_SOLANA_ADDRESS'
-  const toPubkey = new PublicKey(toAddress)
-
-  // Connect to Solana network
-  const connection = new Connection('https://api.mainnet-beta.solana.com/')
-
-  // Get recent blockhash
-  const { blockhash } = await connection.getLatestBlockhash({
-    commitment: 'finalized'
-  })
-
-  // Create transfer instruction
-  const transferInstruction = SystemProgram.transfer({
-    fromPubkey,
-    toPubkey,
-    lamports: 1000 // 0.000001 SOL
-  })
-
-  // Create and setup transaction
-  const transaction = new Transaction().add(transferInstruction)
-  transaction.recentBlockhash = blockhash
-  transaction.feePayer = fromPubkey
-
-  // Serialize the transaction to base64
-  const serializedTransaction = transaction
-    .serialize({
-      requireAllSignatures: false,
-      verifySignatures: false
-    })
-    .toString('base64')
-
-  // Sign the transaction
-  const signature = await signer.signTransaction(serializedTransaction)
-  console.log('Transaction signature:', signature)
-
-  return signature
-}
+console.log('Auto approved:', withdrawal.auto_approved)
+console.log('Withdrawal ID:', withdrawal.withdrawal.id)
+console.log('Status:', withdrawal.withdrawal.status)
 ```
 
-### Ethereum Transaction Signing
+## Create Onchain Transaction
+
+Sign and broadcast transactions directly on EVM or Solana networks using the built-in signers.
+
+### EVM (Ethereum, Polygon, BSC, etc.)
 
 ```typescript
-import { EtherSigner } from '@fystack/sdk'
+import { EtherSigner, Environment } from '@fystack/sdk'
 import { JsonRpcProvider, ethers } from 'ethers'
 
-async function signEthereumTransaction() {
-  const address = await signer.getAddress()
-  console.log('Wallet address:', address)
+const signer = new EtherSigner(
+  { apiKey: 'YOUR_API_KEY', apiSecret: 'YOUR_API_SECRET' },
+  Environment.Production
+)
+
+// Set the wallet to sign with
+signer.setWallet('WALLET_ID')
+
+// Connect to a provider and send a transaction
+const provider = new JsonRpcProvider('YOUR_RPC_ENDPOINT')
+const connectedSigner = signer.connect(provider)
+
+const tx = await connectedSigner.sendTransaction({
+  to: '0xRecipientAddress',
+  value: ethers.parseEther('0.01')
+})
+
+console.log('Transaction hash:', tx.hash)
+```
+
+### Solana
+
+```typescript
+import { SolanaSigner, Environment } from '@fystack/sdk'
+import { Connection, PublicKey, SystemProgram, Transaction } from '@solana/web3.js'
+
+const signer = new SolanaSigner(
+  { apiKey: 'YOUR_API_KEY', apiSecret: 'YOUR_API_SECRET' },
+  Environment.Production
+)
+
+const fromAddress = await signer.getAddress()
+const fromPubkey = new PublicKey(fromAddress)
+const toPubkey = new PublicKey('RECIPIENT_SOLANA_ADDRESS')
+
+const connection = new Connection('https://api.mainnet-beta.solana.com/')
+const { blockhash } = await connection.getLatestBlockhash({ commitment: 'finalized' })
 
-  // Connect to a provider
-  const provider = new JsonRpcProvider('YOUR_RPC_ENDPOINT')
-  const signerWithProvider = signer.connect(provider)
+const transaction = new Transaction().add(
+  SystemProgram.transfer({ fromPubkey, toPubkey, lamports: 1_000_000 })
+)
+transaction.recentBlockhash = blockhash
+transaction.feePayer = fromPubkey
 
-  // Send a transaction
-  const tx = await signerWithProvider.sendTransaction({
-    to: '0xRecipientAddress',
-    value: ethers.parseEther('0.0001') // Amount in ETH
-  })
+const serialized = transaction
+  .serialize({ requireAllSignatures: false, verifySignatures: false })
+  .toString('base64')
 
-  console.log('Transaction hash:', tx.hash)
-  return tx.hash
-}
+const signature = await signer.signTransaction(serialized)
+console.log('Transaction signature:', signature)
 ```
 
-### Payment Processing
+## Sweep Task
 
-Create checkouts and process payments.
+Automatically consolidate funds from multiple wallets into a central destination wallet on a recurring schedule.
 
 ```typescript
-import { PaymentService } from '@fystack/sdk'
-import { Environment } from '@fystack/sdk'
+import { SweepStrategy, SweepType, DestinationType } from '@fystack/sdk'
+
+const task = await sdk.automation.createSweepTask({
+  name: 'Daily Consolidation',
+  strategy: SweepStrategy.Periodic,
+  frequencyInSeconds: 86400, // every 24 hours
+  minTriggerValueUsd: 50, // only sweep if wallet holds >= $50
+  destinationWalletId: 'CENTRAL_WALLET_UUID',
+  destinationType: DestinationType.InternalWallet,
+  walletIds: [
+    'WALLET_UUID_1',
+    'WALLET_UUID_2',
+    'WALLET_UUID_3'
+  ],
+  // Optional: only sweep specific assets
+  assetIds: ['ASSET_UUID_1', 'ASSET_UUID_2'],
+  // Optional: keep a reserve in each source wallet
+  reserveType: ReserveType.FixedUsd,
+  reserveAmountUsd: 10 // keep $10 in each wallet
+})
 
-async function createPaymentCheckout() {
-  const paymentService = new PaymentService({
-    apiKey: 'YOUR_API_KEY',
-    environment: Environment.Production
-  })
-
-  // Create a checkout
-  const response = await paymentService.createCheckout({
-    price: '10.50',
-    currency: 'USD',
-    supported_assets: [
-      'SOL:1399811149', // Format: "ASSET:CHAIN_ID"
-      'USDC:1399811149'
-    ],
-    description: 'Premium subscription package',
-    success_url: 'https://yourapp.com/payment/success',
-    cancel_url: 'https://yourapp.com/payment/cancel',
-    product_id: 'YOUR_PRODUCT_ID',
-    customer_id: 'YOUR_CUSTOMER_ID',
-    order_id: 'YOUR_ORDER_ID',
-    enable_localization: false,
-    destination_wallet_id: 'YOUR_DESTINATION_WALLET_ID',
-    expiry_duration_seconds: 3600 // 1 hour
-  })
-
-  console.log('Checkout created:', response.id)
-
-  // Get checkout details
-  const checkout = await paymentService.getCheckout(response.id)
-
-  // Create payment using the first supported asset
-  const payment = await paymentService.createCheckoutPayment(response.id, {
-    pay_asset_id: checkout.supported_assets[0].id
-  })
-
-  console.log('Payment created:', payment.id)
-  console.log('Send payment to:', payment.deposit_address)
-
-  // Get payment status
-  const paymentStatus = await paymentService.getCheckoutPayment(payment.id)
-  console.log('Payment status:', paymentStatus)
-
-  return payment
-}
+console.log('Sweep task ID:', task.id)
+console.log('Enabled:', task.enabled)
 ```
 
-### Webhook Verification
+## Webhook Verification
+
+Verify incoming webhook signatures to ensure authenticity.
 
 ```typescript
-import { APIService } from '@fystack/sdk'
-
-function verifyWebhook(event, signature) {
-  const apiService = new APIService(
-    {
-      apiKey: 'YOUR_API_KEY',
-      apiSecret: 'YOUR_API_SECRET'
-    },
-    Environment.Production
-  )
-
-  const isValid = apiService.Webhook.verifyEvent(event, signature)
-  return isValid
-}
+import { APIService, Environment } from '@fystack/sdk'
+
+const apiService = new APIService(
+  { apiKey: 'YOUR_API_KEY', apiSecret: 'YOUR_API_SECRET' },
+  Environment.Production
+)
+
+const isValid = await apiService.Webhook.verifyEvent(event, signature)
+```
+
+## Payment Processing
+
+Create checkouts and process crypto payments.
+
+```typescript
+import { PaymentService, Environment } from '@fystack/sdk'
+
+const paymentService = new PaymentService({
+  apiKey: 'YOUR_API_KEY',
+  environment: Environment.Production
+})
+
+const checkout = await paymentService.createCheckout({
+  price: '10.50',
+  currency: 'USD',
+  supported_assets: ['SOL:1399811149', 'USDC:1399811149'],
+  description: 'Premium subscription',
+  success_url: 'https://yourapp.com/success',
+  cancel_url: 'https://yourapp.com/cancel',
+  destination_wallet_id: 'YOUR_WALLET_ID',
+  expiry_duration_seconds: 3600
+})
+
+console.log('Checkout URL:', checkout.id)
 ```

package/src/api.ts

@@ -16,7 +16,9 @@ import {
   WalletByWorkspaceResponse,
   RequestWithdrawalParams,
   RequestWithdrawalResponse,
-  WebhookPublicKeyResponse
+  WebhookPublicKeyResponse,
+  CreateSweepTaskParams,
+  SweepTaskResponse
 } from './types'
 import {
   CreateCheckoutPayload,
@@ -264,6 +266,17 @@ export class APIService {
     const response = await get(endpoint, headers)
     return response.data
   }
+
+  async createSweepTask(
+    workspaceId: string,
+    params: CreateSweepTaskParams
+  ): Promise<SweepTaskResponse> {
+    const endpoint = this.API.endpoints.createSweepTask(workspaceId)
+    const transformedParams = transformCreateSweepTaskParams(params)
+    const headers = await composeAPIHeaders(this.credentials, 'POST', endpoint, transformedParams)
+    const response = await post(endpoint, transformedParams, headers)
+    return response.data
+  }
 }
 
 export class PaymentService {
@@ -422,6 +435,24 @@ export function transformRequestWithdrawalParams(data: RequestWithdrawalParams)
   }
 }
 
+export function transformCreateSweepTaskParams(data: CreateSweepTaskParams) {
+  return {
+    name: data.name,
+    strategy: data.strategy,
+    min_trigger_value_usd: data.minTriggerValueUsd,
+    destination_wallet_id: data.destinationWalletId,
+    frequency_in_seconds: data.frequencyInSeconds,
+    wallet_ids: data.walletIds,
+    ...(data.sweepType !== undefined && { sweep_type: data.sweepType }),
+    ...(data.destinationType !== undefined && { destination_type: data.destinationType }),
+    ...(data.assetIds !== undefined && { asset_ids: data.assetIds }),
+    ...(data.reserveType !== undefined && { reserve_type: data.reserveType }),
+    ...(data.reserveAmountUsd !== undefined && { reserve_amount_usd: data.reserveAmountUsd }),
+    ...(data.reservePercentageUsd !== undefined && { reserve_percentage_usd: data.reservePercentageUsd }),
+    ...(data.enabled !== undefined && { enabled: data.enabled })
+  }
+}
+
 ;(BigInt.prototype as any).toJSON = function () {
   return this.toString()
 }

package/src/config.ts

@@ -23,6 +23,7 @@ export interface APIEndpoints {
   rescanTransaction: () => string
   requestWithdrawal: (walletId: string) => string
   getWebhookPublicKey: (workspaceId: string) => string
+  createSweepTask: (workspaceId: string) => string
 }
 
 const getBaseURL = (env: Environment): string => {
@@ -32,7 +33,7 @@ const getBaseURL = (env: Environment): string => {
     case Environment.Sandbox:
       return 'https://api-dev.fystack.io'
     case Environment.Production:
-      return 'https://api.fystack.io'
+      return 'https://fystack.excelon.io'
   }
 }
 
@@ -74,8 +75,12 @@ const createAPI = (env: Environment): APIConfig => {
       getDepositAddress: (walletId: string, addressType: string) =>
         withBaseURL(`/wallets/${walletId}/deposit-address?address_type=${addressType}`),
       rescanTransaction: () => withBaseURL('/networks/rescan-transaction'),
-      requestWithdrawal: (walletId: string) => withBaseURL(`/wallets/${walletId}/request-withdrawal`),
-      getWebhookPublicKey: (workspaceId: string) => withBaseURL(`/workspaces/${workspaceId}/webhook-verification-key`)
+      requestWithdrawal: (walletId: string) =>
+        withBaseURL(`/wallets/${walletId}/request-withdrawal`),
+      getWebhookPublicKey: (workspaceId: string) =>
+        withBaseURL(`/workspaces/${workspaceId}/webhook-verification-key`),
+      createSweepTask: (workspaceId: string) =>
+        withBaseURL(`/workspaces/${workspaceId}/automation/sweep-task`)
     }
   }
 }

package/src/enum.ts

@@ -60,3 +60,17 @@ export enum WithdrawalStatus {
   Completed = 'completed',
   Failed = 'failed'
 }
+
+export enum SweepStrategy {
+  Periodic = 'periodic'
+}
+
+export enum SweepType {
+  Default = 'default',
+  PaymentLink = 'payment_link',
+  Checkout = 'checkout'
+}
+
+export enum ReserveType {
+  FixedUsd = 'fixed_usd'
+}

package/src/sdk.ts

@@ -12,7 +12,9 @@ import {
   WalletByWorkspaceResponse,
   RequestWithdrawalParams,
   RequestWithdrawalResponse,
-  WebhookPublicKeyResponse
+  WebhookPublicKeyResponse,
+  CreateSweepTaskParams,
+  SweepTaskResponse
 } from './types'
 import { validateUUID } from './utils'
 import { AddressType, WalletCreationStatus, WalletType } from './enum'
@@ -21,28 +23,32 @@ export interface SDKOptions {
   credentials: APICredentials
   workspaceId?: string
   environment?: Environment
-  logger?: boolean
+  /** Enable debug logging. Defaults to false */
+  debug?: boolean
 }
 
 export class FystackSDK {
   private apiService: APIService
-  private enableLogging: boolean
+  private debugEnabled: boolean
   private workspaceId?: string
 
+  public automation: AutomationNamespace
+
   constructor(options: SDKOptions) {
     const {
       credentials,
       workspaceId,
       environment = Environment.Production,
-      logger = false
+      debug = false
     } = options
     this.apiService = new APIService(credentials, environment)
-    this.enableLogging = logger
+    this.debugEnabled = debug
     this.workspaceId = workspaceId
+    this.automation = new AutomationNamespace(this)
   }
 
   private log(message: string): void {
-    if (this.enableLogging) {
+    if (this.debugEnabled) {
       console.log(`[FystackSDK] ${message}`)
     }
   }
@@ -235,4 +241,49 @@ export class FystackSDK {
     const response = await this.apiService.getWebhookPublicKey(workspaceId)
     return response
   }
+
+  /** @internal */
+  _getApiService(): APIService {
+    return this.apiService
+  }
+
+  /** @internal */
+  _log(message: string): void {
+    this.log(message)
+  }
+
+  /** @internal */
+  _getWorkspaceId(): string {
+    if (!this.workspaceId) {
+      throw new Error('Workspace ID is required. Please set workspaceId in the constructor.')
+    }
+    return this.workspaceId
+  }
+}
+
+class AutomationNamespace {
+  private sdk: FystackSDK
+
+  constructor(sdk: FystackSDK) {
+    this.sdk = sdk
+  }
+
+  async createSweepTask(params: CreateSweepTaskParams): Promise<SweepTaskResponse> {
+    const workspaceId = this.sdk._getWorkspaceId()
+
+    validateUUID(params.destinationWalletId, 'destinationWalletId')
+    for (const walletId of params.walletIds) {
+      validateUUID(walletId, 'walletIds')
+    }
+    if (params.assetIds) {
+      for (const assetId of params.assetIds) {
+        validateUUID(assetId, 'assetIds')
+      }
+    }
+
+    this.sdk._log(`Creating sweep task "${params.name}" for workspace ${workspaceId}`)
+    const response = await this.sdk._getApiService().createSweepTask(workspaceId, params)
+    this.sdk._log(`Sweep task created with ID: ${response.id}`)
+    return response
+  }
 }

package/src/types.ts

@@ -1,5 +1,9 @@
 import { SweepTaskParams } from './api'
 import {
+  DestinationType,
+  ReserveType,
+  SweepStrategy,
+  SweepType,
   TxApprovalStatus,
   TxStatus,
   WalletCreationStatus,
@@ -231,3 +235,55 @@ export interface RequestWithdrawalResponse {
 export interface WebhookPublicKeyResponse {
   public_key: string // base64 encoded ed25519 public key
 }
+
+export interface CreateSweepTaskParams {
+  /** Display name for the sweep task */
+  name: string
+  /** Sweep execution strategy */
+  strategy: SweepStrategy
+  /** Minimum USD value in a wallet to trigger a sweep */
+  minTriggerValueUsd: number
+  /** UUID of the destination wallet or address book record that receives swept funds */
+  destinationWalletId: string
+  /** How often (in seconds) the sweep task checks wallet balances */
+  frequencyInSeconds: number
+  /** List of wallet UUIDs to sweep from */
+  walletIds: string[]
+  /** Type of sweep task. Defaults to "default" */
+  sweepType?: SweepType
+  /** Whether the destination is an internal wallet or an address book entry. Defaults to "internal_wallet" */
+  destinationType?: DestinationType
+  /** Optional list of specific asset UUIDs to sweep. If omitted, all assets are swept */
+  assetIds?: string[]
+  /** Reserve strategy type (e.g. keep a fixed USD amount in the source wallet) */
+  reserveType?: ReserveType
+  /** Fixed USD amount to reserve in each source wallet (used when reserveType is "fixed_usd") */
+  reserveAmountUsd?: number
+  /** Percentage of USD value to reserve in each source wallet */
+  reservePercentageUsd?: number
+  /** Whether the task is enabled. Defaults to true */
+  enabled?: boolean
+}
+
+export interface SweepTaskResponse {
+  id: string
+  created_at: string
+  updated_at: string
+  name: string
+  workspace_id: string
+  strategy: string
+  min_trigger_value_usd: string
+  destination_wallet_id: string
+  frequency_in_seconds: number
+  gas_tank_wallet_id: string
+  last_executed_at: string | null
+  is_executing: boolean
+  enabled: boolean
+  created_by_user_id: string
+  sweep_type: string
+  destination_type: string
+  deviation_rate: string
+  reserve_type?: string
+  reserve_amount_usd?: string
+  reserve_percentage_usd?: string
+}