@venturialstd/bitso

A comprehensive NestJS SDK for Bitso API v3, developed by Venturial, that provides full integration with Bitso's exchange and withdrawal infrastructure. This module enables currency conversions, crypto swaps, fiat withdrawals (CLABE, debit card), and crypto withdrawals, along with webhook support for funding and withdrawal events.

Features

• Currency Conversions: Get quotes and conversion rates for fiat and crypto pairs (MXN, USD, USDC, USDT, BTC, ETH)
• Exchange/Swap: Execute currency swaps between supported pairs
• Fiat Withdrawals: Withdraw MXN via CLABE (SPEI) or debit card
• Crypto Withdrawals: Withdraw crypto to external addresses
• Webhook Integration: Receive real-time notifications for funding and withdrawal events
• HMAC-SHA256 Authentication: Secure API request signing
• Environment Support: Staging and production environments
• Type Safety: Full TypeScript support with comprehensive type definitions

Installation

npm install @venturialstd/bitso
# or
yarn add @venturialstd/bitso

Peer Dependencies

This package requires the following peer dependencies:

npm install @nestjs/common@^11.0.11 @nestjs/core@^11.0.5 @nestjs/axios@^4.0.0 @venturialstd/core@^1.0.16 crypto-js@^4.2.0

Basic Usage

1. Import the Module

import { Module } from '@nestjs/common';
import { BitsoModule } from '@venturialstd/bitso';

@Module({
  imports: [
    BitsoModule,
  ],
})
export class AppModule {}

2. Inject and Use Services

import { Injectable } from '@nestjs/common';
import { BitsoExchangeService, BitsoWithdrawService } from '@venturialstd/bitso';

@Injectable()
export class PaymentService {
  constructor(
    private readonly bitsoExchangeService: BitsoExchangeService,
    private readonly bitsoWithdrawService: BitsoWithdrawService,
  ) {}

  async getQuote(fromCurrency: string, toCurrency: string, amount: string) {
    const quote = await this.bitsoExchangeService.getQuote(
      fromCurrency.toLowerCase(),
      toCurrency.toLowerCase(),
      amount,
    );
    return quote; // { rate, toAmount }
  }

  async withdrawToClabe(amount: string, clabe: string, beneficiary: string) {
    const withdrawal = await this.bitsoWithdrawService.withdrawClabe(
      amount,
      clabe,
      beneficiary,
      'Payment concept',
    );
    return withdrawal;
  }
}

3. Configuration

The module uses SettingsService from @venturialstd/core to retrieve credentials. Configure the following settings:

• GLOBAL:BITSO:GENERAL:ENVIRONMENT: Environment (STAGING or PRODUCTION)
• GLOBAL:BITSO:GENERAL:API_KEY: Your Bitso API key
• GLOBAL:BITSO:GENERAL:API_SECRET: Your Bitso API secret

Settings can be stored in the database or via the admin settings UI. The module loads settings from @venturialstd/core SettingsService.

API

BitsoClient

Low-level client for Bitso API. Uses HMAC-SHA256 for request signing.

| Method | Description | |--------|-------------| | getCurrencyWalletPublicKey(currency) | Get wallet public key for a currency | | getCurrencyConversionRate(fromCurrency, toCurrency, spendAmount) | Get conversion rate (returns number) | | getCurrencyQuote(fromCurrency, toCurrency, spendAmount) | Get quote with rate and converted amount | | swapBetweenCurrency(fromCurrency, toCurrency, spendAmount) | Execute a currency swap | | sendWithdrawalFiatClabe(amount, clabe, beneficiary, concept?) | Withdraw MXN via CLABE (SPEI) | | sendWithdrawalFiatDebitCard(amount, debitCard, institutionCode, beneficiary, concept?) | Withdraw MXN via debit card | | sendWithdrawalCrypto(wireId, amount, address, currency, network) | Withdraw crypto to external address |

BitsoExchangeService

| Method | Description | |--------|-------------| | requestExchange(data: BitsoRequestExchange) | Create and execute an exchange, persisting to database | | getUsdToMxnRate() | Get USD to MXN conversion rate | | getConversionRate(fromCurrency, toCurrency, amount?) | Get conversion rate for a currency pair | | getQuote(fromCurrency, toCurrency, amount) | Get quote for dashboard/calculator (rate + toAmount) |

BitsoWithdrawService

| Method | Description | |--------|-------------| | withdrawClabe(amount, clabe, beneficiary, concept?) | Withdraw MXN to CLABE (SPEI) | | withdrawDebitCard(amount, debitCard, bankId, beneficiary, concept?) | Withdraw MXN to debit card | | updateById(id, data) | Update withdrawal record by ID |

Supported Currencies

Bitso uses lowercase currency codes. Supported pairs include:

• Fiat: mxn, usd
• Crypto: usdc, usdt, btc, eth

Webhooks

The module includes a webhook controller for Bitso events:

• Funding: funding events (pending, complete)
• Withdrawal: withdrawal events (pending, complete)

Configure your webhook URL in the Bitso dashboard to receive real-time notifications.

Error Handling

The module includes error handling that:

• Logs errors via AppLogger from @venturialstd/core
• Returns null for client methods when operations fail
• Throws errors for service methods when operations fail (e.g., withdrawClabe)

Notes

• Environment Support: The module supports STAGING (https://stage.bitso.com/api/v3) and PRODUCTION (https://bitso.com/api/v3).
• Currency Format: All currency codes must be lowercase when calling Bitso API (mxn, usd, btc, etc.).
• Authentication: HMAC-SHA256 signing is required for all requests. API Key and API Secret are stored as secrets.
• Type Safety: All request and response types are fully typed for better IDE support.
• Rate Limits: Be aware of Bitso's rate limits when making multiple API calls.
• Quote Expiration: Currency conversion quotes may have expiration times. Execute swaps promptly after obtaining a quote.

License

MIT

Support

For issues, questions, or contributions, please contact the Venturial development team.