npm package: @baltex/api
Description: Official Baltex Partner API client for Node.js
Author: Baltex
Latest version: 0.0.1

# @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

```bash
yarn add @baltex/api
```

or with npm:

```bash
npm install @baltex/api
```

## Quick Start

```typescript
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

```typescript
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

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

Returns a list of available currencies for CEX operations.

#### Get Exchange Rate

```typescript
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

```typescript
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

```typescript
// 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

```typescript
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

```typescript
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

```typescript
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

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

Returns currency information for the specified network and token address.

#### Get Available Currencies

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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

```bash
yarn build
```

### Testing

```bash
yarn test
```

### Watch Mode

```bash
yarn test:watch
```

## License

MIT

## Support

For API documentation and support, visit [Baltex Documentation](https://docs.baltex.io) or contact support@baltex.io.

## Contributing

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