Skip to content

Baltexio/baltex-api-nodejs

BranchesTags

Repository files navigation

@baltex/api

Official Baltex Partner API client for Node.js. A lightweight, fully-typed TypeScript client for interacting with the Baltex cryptocurrency exchange platform.

Features

  • ✨ Full TypeScript support with comprehensive type definitions
  • 🚀 ESM module format
  • 🔐 Built-in API key authentication
  • 📦 Zero external dependencies (uses native Node.js fetch)
  • 🎯 Full coverage of Baltex Partner API endpoints
  • 💡 Simple and intuitive API design

Requirements

  • Node.js >= 16.0.0

Installation

yarn add @baltex/api

or with npm:

npm install @baltex/api

Quick Start

import { BaltexClient } from '@baltex/api';

// Initialize the client
const client = new BaltexClient({
  apiKey: 'your-api-key-here'
});

// Get available currencies
const currencies = await client.crossChain.getAvailableCurrencies();

// Get exchange rate
const rate = await client.crossChain.getRate({
  fromCurrency: 'BTC',
  fromNetwork: 'bitcoin',
  toCurrency: 'ETH',
  toNetwork: 'ethereum',
  amount: '1'
});

// Create an exchange
const exchange = await client.crossChain.createExchange({
  fromCurrency: 'BTC',
  toCurrency: 'ETH',
  fromNetwork: 'bitcoin',
  toNetwork: 'ethereum',
  fromAmount: '0.1',
  address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
});

Configuration

Client Options

const client = new BaltexClient({
  apiKey: 'your-api-key',        // Required: Your Baltex Partner API key
  baseUrl: 'https://api.baltex.io', // Optional: Custom API base URL
  timeout: 30000                  // Optional: Request timeout in ms (default: 30000)
});

API Reference

Cross-Chain Exchange API

Get Available Currencies

const currencies = await client.crossChain.getAvailableCurrencies();

Returns a list of available currencies for CEX operations.

Get Exchange Rate

const rate = await client.crossChain.getRate({
  fromCurrency: 'BTC',
  fromNetwork: 'bitcoin',
  toCurrency: 'ETH',
  toNetwork: 'ethereum',
  amount: '1',           // Optional, default: "1"
  flow: 'standard'       // Optional: 'standard' | 'fixed-rate'
});

Returns an exchange rate quote for the specified currencies and networks.

Get Private Exchange Rate

const privateRate = await client.crossChain.getPrivateRate({
  fromCurrency: 'BTC',
  fromNetwork: 'bitcoin',
  toCurrency: 'ETH',
  toNetwork: 'ethereum',
  privateType: 'type1',
  amount: '1',
  flow: 'standard'
});

Returns a private exchange rate quote.

Get Exchange Status

// Generic status check
const status = await client.crossChain.getExchangeStatus('exchange-id');

// Standard exchange status
const standardStatus = await client.crossChain.getStandardExchangeStatus('exchange-id');

// Private exchange status
const privateStatus = await client.crossChain.getPrivateExchangeStatus('exchange-id');

Returns the status of an exchange by its ID.

Get Partner Exchanges

const exchanges = await client.crossChain.getPartnerExchanges({
  status: 'finished',        // Optional filter
  fromCurrency: 'BTC',       // Optional filter
  fromNetwork: 'bitcoin',    // Optional filter
  toCurrency: 'ETH',         // Optional filter
  toNetwork: 'ethereum',     // Optional filter
  exchangeType: 'standard'   // Optional: 'standard' | 'private'
});

Returns all exchanges for the partner from the last 24 hours with optional filters.

Create Standard Exchange

const exchange = await client.crossChain.createExchange({
  fromCurrency: 'BTC',
  toCurrency: 'ETH',
  fromNetwork: 'bitcoin',
  toNetwork: 'ethereum',
  fromAmount: '0.1',
  address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  memo: 'optional-memo',           // Optional
  refundAddress: '1A1zP1...',      // Optional
  refundMemo: 'refund-memo',       // Optional
  flow: 'standard',                 // Optional: 'standard' | 'fixed-rate'
  rateId: 'rate-id'                // Optional
});

Creates a standard exchange order.

Create Private Exchange

const privateExchange = await client.crossChain.createPrivateExchange({
  fromCurrency: 'BTC',
  toCurrency: 'ETH',
  fromNetwork: 'bitcoin',
  toNetwork: 'ethereum',
  fromAmount: '0.1',
  privateType: 'type1',
  address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  memo: 'optional-memo',           // Optional
  refundAddress: '1A1zP1...',      // Optional
  refundMemo: 'refund-memo'        // Optional
});

Creates a private exchange order.

DeFi/DEX API

Get Currency Info

const currencyInfo = await client.defi.getCurrencyInfo({
  network: 'ethereum',
  address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
});

Returns currency information for the specified network and token address.

Get Available Currencies

const currencies = await client.defi.getAvailableCurrencies({
  network: 'ethereum',
  page: '1',      // Optional
  limit: '50'     // Optional
});

Returns a list of available currencies for the specified network with pagination support.

Get Swap Quote

const quote = await client.defi.getQuote({
  network: 'ethereum',
  fromTokenAddress: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
  toTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  amount: '1000000000000000000', // 1 ETH in wei
  slippage: '0.5',               // 0.5%
  referrerFee: '0'               // 0%
});

Returns a quote for swapping tokens.

Build Swap Transaction

const swapTx = await client.defi.swapTransaction({
  account: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  fromTokenAddress: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
  toTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  amount: '1000000000000000000',
  slippage: '0.5',
  referrerFee: '0',
  network: 'ethereum'
});

Builds a token swap transaction on the blockchain.

Send Transaction

const result = await client.defi.sendTransaction({
  account: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  amountFrom: '1000000000000000000',
  amountTo: '2000000000',
  fromTokenAddress: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
  toTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  network: 'ethereum',
  commissionPercentage: '0.3',
  rawTx: 'raw-transaction-data',    // Optional
  hash: 'transaction-hash',          // Optional
  to: 'recipient-address',           // Optional
  isExchange: true                   // Optional
});

Sends a transaction to the blockchain.

Get Partner DEX Exchanges

const dexExchanges = await client.defi.getPartnerExchanges({
  status: 'completed',                  // Optional filter
  fromTokenAddress: '0xC02aaA...',     // Optional filter
  toTokenAddress: '0xA0b869...',       // Optional filter
  network: 'ethereum'                   // Optional filter
});

Returns all DEX exchanges for the partner from the last 24 hours.

Error Handling

The client throws BaltexApiError objects when requests fail:

import { BaltexClient } from '@baltex/api';
import type { BaltexApiError } from '@baltex/api';

const client = new BaltexClient({ apiKey: 'your-api-key' });

try {
  const rate = await client.crossChain.getRate({
    fromCurrency: 'BTC',
    fromNetwork: 'bitcoin',
    toCurrency: 'ETH',
    toNetwork: 'ethereum'
  });
} catch (error) {
  const apiError = error as BaltexApiError;
  console.error('Status:', apiError.status);
  console.error('Message:', apiError.message);
  console.error('Data:', apiError.data);
}

Error Structure

interface ApiError {
  status: number;      // HTTP status code (0 for network errors)
  message: string;     // Error message
  data?: unknown;      // Additional error data from API
}

TypeScript Support

The library is written in TypeScript and provides full type definitions. All API methods accept and return typed objects:

import type {
  CreateExchangeRequest,
  GetRateParams,
  ExchangeStatus,
  ExchangeFlow
} from '@baltex/api';

const rateParams: GetRateParams = {
  fromCurrency: 'BTC',
  fromNetwork: 'bitcoin',
  toCurrency: 'ETH',
  toNetwork: 'ethereum',
  amount: '1'
};

const exchangeData: CreateExchangeRequest = {
  fromCurrency: 'BTC',
  toCurrency: 'ETH',
  fromNetwork: 'bitcoin',
  toNetwork: 'ethereum',
  fromAmount: '0.1',
  address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
};

Available Types

Request Types

  • BaltexClientConfig - Client configuration options
  • CreateExchangeRequest - Standard exchange creation payload
  • CreatePrivateExchangeRequest - Private exchange creation payload
  • GetRateParams - Rate query parameters
  • GetPrivateRateParams - Private rate query parameters
  • GetPartnerExchangesParams - Exchange list filter parameters
  • SendDexTransactionRequest - DEX transaction send payload
  • SwapDexTransactionRequest - DEX swap transaction payload
  • GetCurrencyInfoParams - Currency info query parameters
  • GetAvailableDefiCurrenciesParams - DeFi currencies list parameters
  • GetQuoteParams - Swap quote parameters
  • GetPartnerDexExchangesParams - DEX exchange list filter parameters

Response Types

  • AvailableCurrenciesResponse - Available currencies list response
  • ExchangeRateResponse - Exchange rate information
  • ExchangeResponse - Exchange order details
  • PartnerExchangesResponse - Partner exchanges list
  • AllRatesResponse - All rates information
  • CurrencyInfoResponse - Token/currency information
  • AvailableDefiCurrenciesResponse - Available DeFi currencies with pagination
  • SwapQuoteResponse - Swap quote details
  • SwapTransactionResponse - Built swap transaction
  • SendTransactionResponse - Transaction send result
  • DexExchangeResponse - DEX exchange details
  • PartnerDexExchangesResponse - Partner DEX exchanges list

Other Types

  • BaltexApiError - Error response structure
  • ExchangeFlow - Exchange flow type: 'standard' | 'fixed-rate'
  • ExchangeStatus - Exchange status enum
  • ExchangeType - Exchange type: 'standard' | 'private'
  • Currency - Currency information structure

Development

Building

yarn build

Testing

yarn test

Watch Mode

yarn test:watch

License

MIT

Support

For API documentation and support, visit Baltex Documentation or contact support@baltex.io.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Code of conduct

Code of conduct
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages