softXpay SDK

Official Node.js SDK for softXpay - Easy cryptocurrency payment integration for your applications.

🚀 Features

• 🔐 Secure Authentication - Automatic token management and refresh
• 💰 Multiple Cryptocurrencies - Support for USDT, USDC, and more
• 🌐 Multiple Networks - Ethereum, Tron, and other blockchain networks
• 📱 QR Code Generation - Automatic QR code generation for payments
• 🔍 Real-time Payment Tracking - Monitor payment status in real-time
• 📊 Settings & Fees - Get deposit/withdraw settings and fee information
• 📝 Full TypeScript Support - Complete TypeScript definitions included
• 🛡️ Comprehensive Error Handling - Robust error handling with custom error types
• 🔄 Built-in Retry Logic - Automatic retry for failed requests
• 📚 Rich Examples - Comprehensive examples for all use cases

📦 Installation

npm install softxpay

⚡ Quick Start

const { SoftXpay } = require('softxpay');

// Initialize the SDK
const softxpay = new SoftXpay({
  apiKey: 'sk_sb_sec_your_api_key_here',
  baseUrl: 'url', // Optional
});

// Generate a payment address
const payment = await softxpay.generatePaymentAddress({
  request_id: 'unique-payment-id-123',
  network: 'ethereum',
  token: 'usdt',
  user_identify: 'user_123' // conditional (if static address geneartion then require , if dynamic then optional) || username, email, id, phone others 
});

console.log('Payment Address:', payment.data.address);
console.log('QR Code:', payment.data.qrCode);

TypeScript Usage

import { SoftXpay, SoftXpayConfig } from 'softxpay';

const config: SoftXpayConfig = {
  apiKey: 'sk_sb_sec_your_api_key_here'
};

const softxpay = new SoftXpay(config, { debug: true });

🔧 Configuration

Required Configuration

interface SoftXpayConfig {
  apiKey: string;           // Your API key from softXpay dashboard
  baseUrl?: string;         // API base URL (optional, defaults to https://api.softxpay.io)
}

SDK Options

interface SoftXpayOptions {
  debug?: boolean;          // Enable debug logging
  retry?: {                 // Custom retry configuration
    attempts: number;
    delay: number;
  };
}

📖 API Reference

🔑 Authentication

The SDK automatically handles authentication and token management. Tokens are refreshed automatically when needed.

// Manual token refresh (usually not needed)
const tokenResponse = await softxpay.getAccessToken();
console.log('Token expires in:', tokenResponse.data.expiresIn, 'seconds');

💰 Payment Generation

Create a new payment address for cryptocurrency payments.

const payment = await softxpay.generatePaymentAddress({
  request_id: 'unique-payment-id-123',  // Unique identifier for this payment
  network: 'ethereum',                  // Blockchain network
  token: 'usdt',                        // Cryptocurrency token
  user_identify: 'user_123'             // Optional user identifier
});

// Response includes:
// - address: Cryptocurrency address for payment
// - qrCode: Base64 encoded QR code image
// - token: Token symbol
// - network: Network name
// - requestId: Unique request identifier

📊 Payment Status

Check the payment status for a specific request.

const status = await softxpay.getPaymentStatus({
  request_id: 'unique-payment-id-123'
});

console.log('Payment Status:', status.data.status);
console.log('Address:', status.data.address);
console.log('Amount:', status.data.amount);
console.log('Token:', status.data.token.symbol);

🪙 Available Tokens

Get all available tokens supported by the platform.

const tokens = await softxpay.getTokens();
console.log('Available tokens:', tokens.data.tokens.map(t => ({
  name: t.tokenName,
  symbol: t.symbol,
  icon: t.icon,
  status: t.status
})));

🌐 Network Information

Get supported networks for a specific token.

const networks = await softxpay.getNetworksByTokenSymbol('usdt');
console.log('USDT Networks:', networks.data.networks.map(n => ({
  name: n.networkName,
  symbol: n.symbol,
  status: n.status
})));

⚙️ Settings & Fees

Get deposit/withdraw settings and fee information.

const settings = await softxpay.getSettings('deposit');
console.log('Deposit settings:', settings.data.settings.map(s => ({
  token: s.token.symbol,
  network: s.network.symbol,
  fee: s.fee,
  feeType: s.fee_type,
  minAmount: s.min_amount,
  maxAmount: s.max_amount
})));

🧪 Test Deposit

Test deposit functionality (for development/testing purposes).

const testDeposit = await softxpay.depositTestnet({
  amount: 100.50,
  address: '0x742d35Cc6634C0532925a3b8D8E1b1b4c6B8c9A2',
  tokenSymbol: 'usdt',
  networkSymbol: 'ethereum'
});

🌐 Supported Networks and Tokens

Networks

• ethereum - Ethereum (ERC20)
• tron - Tron (TRC20)

Tokens

• usdt - Tether USD
• usdc - USD Coin

Note: More networks and tokens are being added regularly. Use the getTokens() and getNetworksByTokenSymbol() methods to get the current list.

🛡️ Error Handling

The SDK provides comprehensive error handling with custom error types.

try {
  const payment = await softxpay.generatePaymentAddress(request);
} catch (error) {
  if (error instanceof SoftXpayError) {
    console.error('SoftXpay Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Method:', error.method);
    console.error('Timestamp:', error.timestamp);
  } else {
    console.error('Unexpected error:', error);
  }
}

Error Types

• AuthenticationError (401) - Invalid credentials or expired tokens
• ValidationError (400) - Invalid request parameters
• NotFoundError (404) - Resource not found
• RateLimitError (429) - API rate limit exceeded
• ServerError (5xx) - Server-side errors
• NetworkError (0) - Network connectivity issues

📚 Examples

We provide comprehensive examples in the examples/ directory:

Basic Usage

node examples/basic-usage.js

Shows the most common use cases: getting tokens, generating payments, checking status.

Complete Payment Flow

node examples/payment-flow.js

Demonstrates a complete payment processing workflow with monitoring.

Error Handling

node examples/error-handling.js

Shows proper error handling techniques and retry logic.

TypeScript Usage

npx ts-node examples/typescript-example.ts

Demonstrates TypeScript usage with proper typing.

🔧 Advanced Usage

Environment Configuration

const softxpay = new SoftXpay({
  apiKey: process.env.SOFTXPAY_API_KEY
});

Production Payment Service

class PaymentService {
  constructor() {
    this.softxpay = new SoftXpay({
      apiKey: process.env.SOFTXPAY_API_KEY,
    });
  }

  async createPayment(amount, currency, userId) {
    const requestId = `payment_${Date.now()}_${userId}`;
    
    try {
      const payment = await this.softxpay.generatePaymentAddress({
        request_id: requestId,
        network: 'ethereum',
        token: 'usdt',
        user_identify: userId
      });

      return {
        requestId,
        address: payment.data.address,
        qrCode: payment.data.qrCode,
        network: payment.data.network,
        token: payment.data.token
      };
    } catch (error) {
      console.error('Payment creation failed:', error);
      throw error;
    }
  }

  async checkPaymentStatus(requestId) {
    try {
      const status = await this.softxpay.getPaymentStatus({
        request_id: requestId
      });

      return status.data;
    } catch (error) {
      console.error('Payment status check failed:', error);
      throw error;
    }
  }
}

🛠️ Development

Building the SDK

npm run build

Running Tests

npm test

Linting

npm run lint
npm run lint:fix

Development Mode

npm run dev

📋 API Endpoints

The SDK provides methods for all available API endpoints:

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki

📈 Changelog

• Initial release
• Support for Ethereum and Tron networks
• Support for USDT and USDC tokens
• Automatic token management
• QR code generation
• Real-time payment status checking
• Settings and fee information
• TypeScript support
• Comprehensive error handling
• Built-in retry logic
• Rich examples and documentation

Made with ❤️ by SoftBuilders