Onchain Module

The onchain module provides comprehensive onchain transaction capabilities across multiple EVM chains (Sepolia, Amoy, Neon) with automated logging, fee management, and transaction history tracking.

Import

const onchain = await brdzSDK.onchain;

Methods Overview

Method	Description	Auth Required	HTTP Endpoint
executeTransaction	Execute onchain transaction	✅	POST /onchain/execute
logTransaction	Log confirmed transaction	✅	POST /onchain/log
getTransactionHistory	Get transaction history	✅	GET /onchain/history/:user_id
getTransactionDetails	Get transaction details	✅	GET /onchain/details/:tx_hash
getFeeSettings	Get platform fee settings	✅	GET /onchain/admin/fee-settings

Admin Operations

Method	Description	Auth Required	HTTP Endpoint
admin.getFeeSettings	Get fee settings (admin)	✅	GET /onchain/admin/fee-settings
admin.updateFeeSettings	Update fee settings	✅	PUT /onchain/admin/fee-settings

---

executeTransaction

Execute an onchain transaction using backend wallet management with encrypted private keys.

Syntax

const result = await onchain.executeTransaction(data);

Parameters

interface ExecuteTransactionData {
  wallet_address: string;    // User's wallet address (looked up to get bw_id)
  chain_id: string;          // Chain ID (sepolia, amoy, neon)
  token_symbol: string;      // Token symbol (ETH, POL, NEON, USDC)
  token_contract: string;    // Contract address or 'native'
  to_address: string;        // Recipient address
  amount: string;            // Transaction amount
  decimals?: number;         // Token decimals (default: 18)
}

Returns

Promise<{
  success: boolean;
  message: string;
  data: {
    transaction: {
      tx_hash: string;
      block_number: number;
      gas_used: string;
      gas_price: string;
      gas_fee: number;
      platform_fee: number;
      status: "CONFIRMED";
      explorer_url: string;
    };
    log_id: number;
  };
  timestamp: string;
}>

Example

const result = await onchain.executeTransaction({
  wallet_address: "0x742d35Cc6834C0532925a3b8D93b3C3e1DEF3e4D",
  chain_id: "sepolia",
  token_symbol: "USDC",
  token_contract: "0xEA6B04272f9f62F997F666F07D3a974134f7FFb9",
  to_address: "0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
  amount: "10.50",
  decimals: 6
});

console.log('Transaction hash:', result.data.transaction.tx_hash);
console.log('Explorer URL:', result.data.transaction.explorer_url);
console.log('Platform fee:', result.data.transaction.platform_fee);

---

logTransaction

Log a confirmed onchain transaction that was executed from frontend/external wallet.

Syntax

const result = await onchain.logTransaction(data);

Parameters

interface LogTransactionData {
  bw_id: number;             // Blockchain wallet ID
  tx_hash: string;           // Transaction hash (64-char hex)
  amount: string;            // Transaction amount
  to_address: string;        // Recipient address
  token_symbol: string;      // Token symbol
  chain_id: string;          // Chain ID
  token_contract: string;    // Contract address or 'native'
  gas_fee: number;           // Gas fee paid
  platform_fee: number;     // Platform fee charged
}

Returns

Promise<{
  success: boolean;
  message: string;
  data: {
    transaction_log: {
      id: number;
      tx_hash: string;
      amount: string;
      token_symbol: string;
      chain_id: string;
      status: "CONFIRMED";
      created_at: string;
      explorer_url: string;
    };
  };
  timestamp: string;
}>

Example

const result = await onchain.logTransaction({
  bw_id: 123,
  tx_hash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  amount: "10.50",
  to_address: "0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
  token_symbol: "USDC",
  chain_id: "sepolia",
  token_contract: "0xEA6B04272f9f62F997F666F07D3a974134f7FFb9",
  gas_fee: 0.00042,
  platform_fee: 0.10
});

console.log('Transaction logged with ID:', result.data.transaction_log.id);

---

getTransactionHistory

Get user's onchain transaction history with pagination and filtering.

Syntax

const result = await onchain.getTransactionHistory(user_id, params);

Parameters

• user_id (number): User ID to get history for
• params (object, optional): Query parameters

interface HistoryParams {
  limit?: number;        // Max records (1-100, default: 50)
  offset?: number;       // Records to skip (default: 0)
  chain_id?: string;     // Filter by chain
  token_symbol?: string; // Filter by token
}

Returns

Promise<{
  success: boolean;
  message: string;
  data: {
    user_id: number;
    transactions: Array<{
      id: number;
      bw_id: number;
      tx_type: "ONCHAIN_SEND";
      amount: string;
      tx_hash: string;
      status: "CONFIRMED";
      destination_wallet: string;
      tx_flow: "OUT";
      token_symbol: string;
      chain_id: string;
      token_contract: string;
      gas_fee: string;
      platform_fee: string;
      created_at: string;
      wallet_name: string;
      wallet_label: string;
      explorer_url: string;
    }>;
    pagination: {
      total: number;
      limit: number;
      offset: number;
      has_more: boolean;
    };
    filters_applied: {
      chain_id: string | null;
      token_symbol: string | null;
    };
  };
  timestamp: string;
}>

Example

const history = await onchain.getTransactionHistory(123, {
  limit: 10,
  chain_id: "sepolia",
  token_symbol: "USDC"
});

history.data.transactions.forEach(tx => {
  console.log(`${tx.tx_flow}: ${tx.amount} ${tx.token_symbol} on ${tx.chain_id}`);
  console.log(`Explorer: ${tx.explorer_url}`);
});

console.log('Total transactions:', history.data.pagination.total);
console.log('Has more pages:', history.data.pagination.has_more);

---

getTransactionDetails

Get detailed information about a specific transaction by hash.

Syntax

const result = await onchain.getTransactionDetails(tx_hash);

Parameters

• tx_hash (string): Transaction hash (64-char hex starting with 0x)

Returns

Promise<{
  success: boolean;
  message: string;
  data: {
    transaction: {
      id: number;
      bw_id: number;
      tx_type: "ONCHAIN_SEND";
      amount: string;
      tx_hash: string;
      status: "CONFIRMED";
      destination_wallet: string;
      tx_flow: "OUT";
      token_symbol: string;
      chain_id: string;
      token_contract: string;
      gas_fee: string;
      platform_fee: string;
      created_at: string;
      wallet_name: string;
      wallet_label: string;
      user_id: number;
      explorer_url: string;
    };
    requested_by: number;
    access_level: string;
  };
  timestamp: string;
}>

Example

const details = await onchain.getTransactionDetails(
  "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
);

const tx = details.data.transaction;
console.log(`Transaction: ${tx.amount} ${tx.token_symbol}`);
console.log(`Status: ${tx.status}`);
console.log(`Wallet: ${tx.wallet_name}`);
console.log(`Explorer: ${tx.explorer_url}`);

---

getFeeSettings

Get current platform fee settings (alias for admin.getFeeSettings).

Syntax

const result = await onchain.getFeeSettings();

Returns

Promise<{
  success: boolean;
  message: string;
  data: {
    platform_fee_settings: {
      platform_fee_percentage: number;
      minimum_platform_fee_usd: number;
      gas_price_multiplier: number;
      updated_at: string;
      created_at: string;
    };
    is_default: boolean;
  };
  timestamp: string;
}>

Example

const feeSettings = await onchain.getFeeSettings();
const settings = feeSettings.data.platform_fee_settings;

console.log('Platform fee:', settings.platform_fee_percentage + '%');
console.log('Minimum fee:', '$' + settings.minimum_platform_fee_usd);
console.log('Gas multiplier:', settings.gas_price_multiplier);

// Calculate fee for transaction
const transactionAmount = 100;
const calculatedFee = Math.max(
  transactionAmount * (settings.platform_fee_percentage / 100),
  settings.minimum_platform_fee_usd
);
console.log(`Fee for $${transactionAmount}:`, `$${calculatedFee.toFixed(2)}`);

---

Admin Operations

admin.getFeeSettings

Get current platform fee settings (admin access required).

Syntax

const result = await onchain.admin.getFeeSettings();

Returns

Same as getFeeSettings() above.

Example

const adminFeeSettings = await onchain.admin.getFeeSettings();
console.log('Admin fee settings:', adminFeeSettings.data.platform_fee_settings);

---

admin.updateFeeSettings

Update platform fee configuration (admin access required).

Syntax

const result = await onchain.admin.updateFeeSettings(settings);

Parameters

interface FeeSettingsData {
  platform_fee_percentage: number;     // 0-10
  minimum_platform_fee_usd: number;    // Positive number
  gas_price_multiplier: number;        // 1.0-3.0
}

Returns

Promise<{
  success: boolean;
  message: string;
  data: {
    updated_settings: {
      id: number;
      platform_fee_percentage: number;
      minimum_platform_fee_usd: number;
      gas_price_multiplier: number;
      updated_by_admin_id: number;
      is_active: boolean;
      created_at: string;
      updated_at: string;
    };
    updated_by: number;
    previous_settings_deactivated: boolean;
  };
  timestamp: string;
}>

Example

const result = await onchain.admin.updateFeeSettings({
  platform_fee_percentage: 0.5,
  minimum_platform_fee_usd: 0.10,
  gas_price_multiplier: 1.2
});

console.log('Settings updated:', result.data.updated_settings);
console.log('Updated by admin:', result.data.updated_by);

---

Utility Functions

The onchain module includes utility functions accessible via the utils property:

utils.getSupportedChains

const chains = onchain.utils.getSupportedChains();
// Returns: ['sepolia', 'amoy', 'neon']

utils.getSupportedTokens

const tokens = onchain.utils.getSupportedTokens();
// Returns: ['ETH', 'POL', 'NEON', 'USDC']

utils.isValidChain

const isValid = onchain.utils.isValidChain('sepolia');
// Returns: true

utils.isValidTxHash

const isValid = onchain.utils.isValidTxHash('0x1234567890abcdef...');
// Returns: true

utils.isValidAddress

const isValid = onchain.utils.isValidAddress('0x742d35Cc6834C0532925a3b8D93b3C3e1DEF3e4D');
// Returns: true

utils.getExplorerUrl

const url = onchain.utils.getExplorerUrl('sepolia', '0x1234567890abcdef...');
// Returns: 'https://sepolia.etherscan.io/tx/0x1234567890abcdef...'

utils.getChainName

const name = onchain.utils.getChainName('sepolia');
// Returns: 'Sepolia Testnet'

utils.getNativeSymbol

const symbol = onchain.utils.getNativeSymbol('amoy');
// Returns: 'POL'

utils.calculatePlatformFee

const fee = onchain.utils.calculatePlatformFee('100', 0.5, 0.10);
// Returns: 0.50 (max of 0.5% of 100 or minimum 0.10)

utils.formatAmount

const formatted = onchain.utils.formatAmount('10.123456', 2);
// Returns: '10.12'

utils.parseTransactionType

const type = onchain.utils.parseTransactionType('OUT');
// Returns: 'Sent'

---

Supported Chains

Chain ID	Name	Native Token	Contract Type
sepolia	Sepolia Testnet	ETH	EVM
amoy	Polygon Amoy	POL	EVM
neon	Neon EVM	NEON	EVM

Error Handling

All onchain methods can throw errors. Always wrap calls in try-catch blocks:

try {
  const result = await onchain.executeTransaction({
    wallet_address: "0x...",
    chain_id: "sepolia",
    token_symbol: "USDC",
    token_contract: "0x...",
    to_address: "0x...",
    amount: "10.50"
  });
  
  console.log('Transaction successful:', result.data.transaction.tx_hash);
} catch (error) {
  if (error.message.includes('INSUFFICIENT_FUNDS')) {
    console.log('Insufficient balance for transaction');
  } else if (error.message.includes('WALLET_NOT_FOUND')) {
    console.log('Wallet not found or access denied');
  } else if (error.message.includes('INVALID_ADDRESS')) {
    console.log('Invalid recipient address');
  } else {
    console.error('Transaction failed:', error.message);
  }
}

Complete Transaction Flow Example

class OnchainTransactionManager {
  constructor(sdk) {
    this.sdk = sdk;
    this.onchain = null;
    this.initOnchain();
  }

  async initOnchain() {
    this.onchain = await this.sdk.onchain;
  }

  async executeAndTrack(transactionData) {
    try {
      // Get current fee settings
      const feeSettings = await this.onchain.getFeeSettings();
      console.log('Current platform fee:', feeSettings.data.platform_fee_settings.platform_fee_percentage + '%');

      // Execute transaction
      const result = await this.onchain.executeTransaction(transactionData);
      
      console.log('Transaction executed successfully!');
      console.log('Transaction hash:', result.data.transaction.tx_hash);
      console.log('Platform fee charged:', result.data.transaction.platform_fee);
      console.log('View on explorer:', result.data.transaction.explorer_url);

      return {
        success: true,
        tx_hash: result.data.transaction.tx_hash,
        explorer_url: result.data.transaction.explorer_url,
        fees: {
          gas_fee: result.data.transaction.gas_fee,
          platform_fee: result.data.transaction.platform_fee
        }
      };

    } catch (error) {
      console.error('Transaction failed:', error.message);
      return {
        success: false,
        error: error.message
      };
    }
  }

  async getMyTransactionHistory(userId, filters = {}) {
    try {
      const history = await this.onchain.getTransactionHistory(userId, {
        limit: 20,
        ...filters
      });

      const transactions = history.data.transactions.map(tx => ({
        hash: tx.tx_hash,
        amount: tx.amount,
        token: tx.token_symbol,
        chain: tx.chain_id,
        status: tx.status,
        date: new Date(tx.created_at).toLocaleDateString(),
        explorer: tx.explorer_url
      }));

      return {
        transactions,
        total: history.data.pagination.total,
        hasMore: history.data.pagination.has_more
      };

    } catch (error) {
      console.error('Failed to get transaction history:', error.message);
      return { transactions: [], total: 0, hasMore: false };
    }
  }

  async logExternalTransaction(transactionLog) {
    try {
      const result = await this.onchain.logTransaction(transactionLog);
      
      console.log('External transaction logged successfully');
      console.log('Log ID:', result.data.transaction_log.id);
      
      return result.data.transaction_log;
    } catch (error) {
      console.error('Failed to log transaction:', error.message);
      throw error;
    }
  }
}

// Usage
const txManager = new OnchainTransactionManager(brdzSDK);

// Execute transaction
const txResult = await txManager.executeAndTrack({
  wallet_address: "0x742d35Cc6834C0532925a3b8D93b3C3e1DEF3e4D",
  chain_id: "sepolia",
  token_symbol: "USDC",
  token_contract: "0xEA6B04272f9f62F997F666F07D3a974134f7FFb9",
  to_address: "0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359",
  amount: "25.00",
  decimals: 6
});

if (txResult.success) {
  console.log('Transaction completed:', txResult.tx_hash);
  
  // Get updated transaction history
  const history = await txManager.getMyTransactionHistory(123, {
    chain_id: "sepolia",
    token_symbol: "USDC"
  });
  
  console.log(`Found ${history.transactions.length} transactions`);
}

---

Access Control

• executeTransaction, logTransaction: User can only access own wallets
• getTransactionHistory, getTransactionDetails: Users can only access own data, admins can access any user
• admin methods: Admin role required
• All endpoints require valid JWT token + API key