ClanzSDK - TypeScript/JavaScript

Official SDK for integrating with the Clanz Exchange API. Supports React Native, Node.js, and web browsers.

Installation

npm install clanz-sdk
# or
yarn add clanz-sdk

Quick Start

import { ClanzSDK } from 'clanz-sdk';

// Initialize the SDK
const sdk = new ClanzSDK({
  baseUrl: 'https://api.clanz.com',
  debug: true, // Enable for development
});

// Login
const { token, user } = await sdk.user.login({
  email: '[email protected]',
  password: 'YourSecurePassword123!',
});

// Get wallet balance
const balance = await sdk.asset.getWalletBalance();
console.log('Total equity:', balance.list[0].totalEquity);

// Place a trade
const order = await sdk.order.marketBuy('BTCUSDT', '0.01');
console.log('Order filled at:', order.avgPrice);

Configuration

import { ClanzSDK, ClanzConfig, TokenStorage } from 'clanz-sdk';

// Custom token storage for React Native
const tokenStorage: TokenStorage = {
  async getToken() {
    return await AsyncStorage.getItem('clanz_token');
  },
  async setToken(token: string) {
    await AsyncStorage.setItem('clanz_token', token);
  },
  async removeToken() {
    await AsyncStorage.removeItem('clanz_token');
  },
};

const sdk = new ClanzSDK({
  baseUrl: 'https://api.clanz.com',
  timeout: 30000,
  debug: false,
  tokenStorage,
});

API Reference

Authentication

// Register a new account
const result = await sdk.user.register({
  email: '[email protected]',
  password: 'SecurePass123!',
  name: 'John Doe',
});

// Login
const loginResult = await sdk.user.login({
  email: '[email protected]',
  password: 'password',
});

// Handle 2FA if required
if (loginResult.requires2FA) {
  const verified = await sdk.user.verify2FA({
    userId: loginResult.userId!,
    sessionToken: loginResult.sessionToken!,
    code: '123456', // From authenticator app
  });
}

// Get profile
const profile = await sdk.user.getProfile();

// Update profile
await sdk.user.updateProfile({ name: 'New Name' });

// Setup 2FA
const setup = await sdk.user.setup2FA();
// Display setup.qrCode to user

// Enable 2FA
await sdk.user.enable2FA('123456');

// Disable 2FA
await sdk.user.disable2FA('123456');

// Change password
await sdk.user.changePassword({
  currentPassword: 'oldPassword',
  newPassword: 'NewSecure123!',
});

// Forgot password
await sdk.user.forgotPassword({ email: '[email protected]' });

// Reset password
await sdk.user.resetPassword({
  email: '[email protected]',
  code: '123456',
  newPassword: 'NewPassword123!',
});

// Logout
sdk.user.logout();

Market Data

// Get all tickers
const tickers = await sdk.market.getTickers();

// Get specific ticker
const btcTicker = await sdk.market.getTickers({ symbol: 'BTCUSDT' });

// Get orderbook
const orderbook = await sdk.market.getOrderbook({ symbol: 'BTCUSDT', limit: 25 });

// Get kline/candlestick data
const klines = await sdk.market.getKline({
  symbol: 'BTCUSDT',
  interval: '60', // 1 hour
  limit: 100,
});

// Get recent trades
const trades = await sdk.market.getRecentTrades({ symbol: 'BTCUSDT' });

// Get all assets with prices
const assets = await sdk.market.getAssets();

// Get trading pairs
const pairs = await sdk.market.getTradingPairs();

// Get market overview (top gainers/losers)
const overview = await sdk.market.getOverview();

Wallet & Assets

// Get all balances
const balances = await sdk.asset.getCoinBalances();

// Get specific coin balance
const btcBalance = await sdk.asset.getCoinBalances({ coin: 'BTC' });

// Get wallet balance with portfolio info
const wallet = await sdk.asset.getWalletBalance();

// Get deposit address
const address = await sdk.asset.getDepositAddress({ coin: 'BTC' });

// Get deposit history
const deposits = await sdk.asset.getDepositRecords({ coin: 'BTC' });

// Confirm pending deposits
await sdk.asset.confirmDeposits('BTC');

// Create withdrawal
const withdrawal = await sdk.asset.createWithdrawal({
  coin: 'BTC',
  chain: 'BTC',
  address: 'bc1q...',
  amount: '0.1',
});

// Confirm withdrawal with email code
await sdk.asset.confirmWithdrawal({
  withdrawId: withdrawal.withdrawId,
  emailCode: '123456',
  twoFactorCode: '654321', // if 2FA enabled
});

// Get withdrawal history
const withdrawals = await sdk.asset.getWithdrawalRecords();

// Transfer to another user
const transfer = await sdk.asset.transfer({
  coin: 'BTC',
  amount: '0.05',
  toEmail: '[email protected]',
});

Trading

// Market buy
const buyOrder = await sdk.order.marketBuy('BTCUSDT', '0.01');

// Market sell
const sellOrder = await sdk.order.marketSell('BTCUSDT', '0.01');

// Custom order
const order = await sdk.order.createOrder({
  symbol: 'BTCUSDT',
  side: 'Buy',
  orderType: 'Market',
  qty: '0.01',
});

// Get order history
const orders = await sdk.order.getOrderHistory({
  symbol: 'BTCUSDT',
  orderStatus: 'Filled',
});

// Get active orders
const activeOrders = await sdk.order.getActiveOrders();

// Get trade executions
const executions = await sdk.order.getExecutions({ symbol: 'BTCUSDT' });

// Get conversion quote
const quote = await sdk.order.getConversionQuote({
  fromCoin: 'BTC',
  toCoin: 'ETH',
  qty: '0.1',
});

// Convert currencies
const conversion = await sdk.order.convert({
  fromCoin: 'BTC',
  toCoin: 'ETH',
  qty: '0.1',
});

// Get conversion history
const conversions = await sdk.order.getConversionHistory();

Account Management

// Get account info
const accountInfo = await sdk.account.getInfo();

// Get fee rates
const fees = await sdk.account.getFeeRate();

// Get settings
const settings = await sdk.account.getSettings();

// Update settings
await sdk.account.updateSettings({
  theme: 'dark',
  notifications: true,
  currency: 'USD',
});

// Get KYC status
const kyc = await sdk.account.getKYCStatus();

// Upload KYC document
const upload = await sdk.account.uploadKYCDocument({
  documentType: 'passport',
  fileName: 'passport.jpg',
  fileData: base64Data,
  mimeType: 'image/jpeg',
});

// Delete pending KYC document
await sdk.account.deleteKYCDocument('doc-id');

// Get transaction history
const transactions = await sdk.account.getTransactions({
  type: 'deposit',
  coin: 'BTC',
  limit: 50,
});

// Get single transaction
const tx = await sdk.account.getTransaction('tx-id');

// Manage withdrawal addresses
const addresses = await sdk.account.getWithdrawalAddresses();
await sdk.account.addWithdrawalAddress({
  coin: 'BTC',
  address: 'bc1q...',
  label: 'Cold Wallet',
  network: 'BTC',
});
await sdk.account.removeWithdrawalAddress('address-id');

Error Handling

import { ClanzApiError, ErrorCodes } from 'clanz-sdk';

try {
  await sdk.order.marketBuy('BTCUSDT', '100');
} catch (error) {
  if (error instanceof ClanzApiError) {
    switch (error.retCode) {
      case ErrorCodes.INSUFFICIENT_BALANCE:
        console.error('Not enough balance');
        break;
      case ErrorCodes.ACCOUNT_NOT_APPROVED:
        console.error('Please complete KYC verification');
        break;
      case ErrorCodes.RATE_LIMIT_EXCEEDED:
        console.error('Too many requests, please wait');
        break;
      default:
        console.error(`Error: ${error.retMsg} (${error.retCode})`);
    }
  }
}

TypeScript Support

The SDK includes full TypeScript definitions. All types are exported:

import {
  User,
  Order,
  Ticker,
  CoinBalance,
  Transaction,
  KYCStatus,
  // ... and more
} from 'clanz-sdk';

React Native Setup

For React Native, install additional peer dependencies:

npm install @react-native-async-storage/async-storage

Create a token storage adapter:

import AsyncStorage from '@react-native-async-storage/async-storage';
import { ClanzSDK, TokenStorage } from 'clanz-sdk';

const tokenStorage: TokenStorage = {
  async getToken() {
    return await AsyncStorage.getItem('clanz_auth_token');
  },
  async setToken(token: string) {
    await AsyncStorage.setItem('clanz_auth_token', token);
  },
  async removeToken() {
    await AsyncStorage.removeItem('clanz_auth_token');
  },
};

export const clanz = new ClanzSDK({
  baseUrl: 'https://api.clanz.com',
  tokenStorage,
});

License

MIT