Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (softxpay) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

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

📄 License

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

🆘 Support

📧 Email: admin@softbuilders.com
🐛 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