JavaScript/TypeScript SDK for Ultrade platform integration.

Overview

The @ultrade/ultrade-js-sdk package provides a JavaScript/TypeScript interface for interacting with ULTRADE's V2 platform, the Native Exchange (NEX) with Bridgeless Crosschain Orderbook technology. It offers a simple interface for creating and managing orders, as well as for interacting with the Ultrade API and WebSocket streams.

Dependencies

This package uses @ultrade/shared as a core dependency. Many types, interfaces, enums, and utility functions are imported from the shared package, which provides common code, utilities, and types for Ultrade platform packages.

Shared Package Repository: https://github.com/ultrade-org/ultrade-shared

Key Features

• Deposits: Always credited to the logged in account
• Order Creation: Orders are created via this SDK by cryptographically signing order messages and sending them to the API
• Gas-Free Trading: This process does not involve on-chain transactions and does not incur any gas costs
• Trading Keys: Can be associated with a specific login account and its balances. Trading keys are used for managing orders but cannot withdraw funds. This is useful for working with market maker (MM) clients on their own accounts

Important Notes

Atomic Units: Token amounts and prices stated in Atomic Units represent the smallest indivisible units of the token based on its number of decimals, in an unsigned integer format.

• Example: 1 ETH (Ethereum, 18 decimals) = 1000000000000000000 (1 with 18 zeros)
• Example: 1 USDC (Algorand, 6 decimals) = 1000000 (1 with 6 zeros)

Price Denomination: The price is denominated based on the Price (Quote) token, while amounts of a base token are denominated according to that base token's decimals.

Repository: https://github.com/ultrade-org/ultrade-js-sdk

Package Info

• Name: @ultrade/ultrade-js-sdk
• Main Entry: ./dist/index.js
• Types: ./dist/index.d.ts

Installation

Install the package using your preferred package manager:

npm install @ultrade/ultrade-js-sdk

yarn add @ultrade/ultrade-js-sdk

pnpm add @ultrade/ultrade-js-sdk

Quick Start

Creating a Client

import { Client } from '@ultrade/ultrade-js-sdk';
import algosdk from 'algosdk';

// Create Algorand SDK client
const algodClient = new algosdk.Algodv2(
  '', // token
  'https://testnet-api.algonode.cloud', // server
  '' // port
);

// Initialize Ultrade client
const client = new Client({
  network: 'testnet', // or 'mainnet'
  apiUrl: 'https://api.testnet.ultrade.org',
  algoSdkClient: algodClient,
  websocketUrl: 'wss://ws.testnet.ultrade.org',
});

Client Options

| Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | network | 'mainnet' \| 'testnet' | Yes | Algorand network | - | | algoSdkClient | Algodv2 | Yes | Algorand SDK client instance | - | | websocketUrl | string | Yes | WebSocket server URL | - | | companyId | number | No | Company ID | 1 | | apiUrl | string | No | Override API URL | Auto-detected |

Table of Contents

1. Authentication & Wallet
2. System
3. Market Data
4. Trading
5. Account & Balances
6. Wallet Operations
7. Whitelist & Withdrawal Wallets
8. KYC
9. WebSocket
10. Notifications
11. Affiliates
12. Social
13. Social Integrations

Authentication & Wallet

login

Authenticate a user with their wallet.

Type imports:

import { PROVIDERS, ILoginData } from '@ultrade/shared/browser/interfaces';

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | data | ILoginData | Yes | Login data object |

ILoginData interface (from @ultrade/shared):

| Property | Type | Required | Description | |----------|------|----------|-------------| | address | string | Yes | Wallet address | | provider | PROVIDERS | Yes | Wallet provider enum (imported from @ultrade/shared/browser/interfaces, see PROVIDERS enum) | | chain | string | No | Blockchain chain | | referralToken | string | No | Referral token | | loginMessage | string | No | Custom login message |

Returns: Promise<string> - Authentication token

Example:

import { PROVIDERS, ILoginData } from '@ultrade/shared/browser/interfaces';
import algosdk from 'algosdk';
import { encodeBase64 } from '@ultrade/shared/browser/helpers';

// Example signer implementation
const signMessage = async (data: string, encoding?: BufferEncoding): Promise<string> => {
  // For Pera Wallet
  const message = typeof data === 'string' 
    ? new Uint8Array(Buffer.from(data, encoding))
    : data;
  
  const signedData = await peraWallet.signData([{
    data: message,
    message: 'Please sign this message'
  }], walletAddress);
  
  return encodeBase64(signedData[0]);
};

// For trading key signing
const signMessageByToken = async (data: string, encoding?: BufferEncoding): Promise<string> => {
  const message = typeof data === 'string' ? data : JSON.stringify(data);
  const bytes = new Uint8Array(Buffer.from(message, encoding));
  
  // Get trading key from secure storage
  const keyData = secureStorage.getKeyFromLocalStorage();
  const { sk } = algosdk.mnemonicToSecretKey(keyData.mnemonic);
  
  const signature = algosdk.signBytes(bytes, sk);
  return encodeBase64(signature);
};

// Set signer before login
client.setSigner({
  signMessage,
  signMessageByToken
});

// Login with wallet
const token = await client.login({
  address: 'NWQVUPGM7TBQO5FGRWQ45VD45JLFJFRKYVVNGVI6NZA4CVWZH7SDNWCHQU',
  provider: PROVIDERS.PERA,
  chain: 'algorand',
  referralToken: 'REF_ABC123XYZ'
});

console.log('Logged in with token:', token);

// Save wallet data
client.mainWallet = {
  address: 'NWQVUPGM7TBQO5FGRWQ45VD45JLFJFRKYVVNGVI6NZA4CVWZH7SDNWCHQU',
  provider: PROVIDERS.PERA,
  token,
  chain: 'algorand'
};

addTradingKey

Create a new trading key for automated trading.

Type imports:

import { ITradingKeyData, TradingKeyType } from '@ultrade/shared/browser/interfaces';

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | data | ITradingKeyData | Yes | Trading key data object |

ITradingKeyData interface (from @ultrade/shared):

| Property | Type | Required | Description | |----------|------|----------|-------------| | tkAddress | string | Yes | Trading key address | | device | string | No | Device identifier (user agent string, e.g., "Chrome 123.0.0.0 Blink Linux, desktop", "Chrome 121.0.0.0 Blink Android, mobile") | | type | TradingKeyType | No | Key type enum (imported from @ultrade/shared/browser/interfaces, see TradingKeyType enum) | | expiredDate | number | No | Expiration timestamp (ms) | | loginAddress | string | Yes | Login wallet address | | loginChainId | number | Yes | Login chain ID |

Returns: Promise<TradingKeyView>

Example:

import { ITradingKeyData, TradingKeyType } from '@ultrade/shared/browser/interfaces';
import algosdk from 'algosdk';

// Generate new trading key account
const generatedAccount = algosdk.generateAccount();
const mnemonic = algosdk.secretKeyToMnemonic(generatedAccount.sk);

// Expiration: 30 days from now (in milliseconds)
const expirationTime = Date.now() + 30 * 24 * 60 * 60 * 1000;

// Get device info (returns full user agent string)
// Examples: "Chrome 123.0.0.0 Blink Linux, desktop", 
//           "Chrome 121.0.0.0 Blink Android, mobile",
//           "Miui 14.4.0 Blink Android, mobile"
const device = navigator.userAgent;

// Create trading key data
const tkData = {
  tkAddress: generatedAccount.addr,
  expiredDate: expirationTime,
  loginAddress: client.mainWallet.address,
  loginChainId: 1, // Chain ID (e.g., 1 for Algorand)
  device: device, // e.g., "Chrome 123.0.0.0 Blink Linux, desktop"
  type: TradingKeyType.User
};

// Add trading key to account
const tradingKey = await client.addTradingKey(tkData);

console.log('Trading key created:', {
  address: tradingKey.address,
  type: tradingKey.type,
  expiresAt: new Date(tradingKey.expiredAt)
});

// Save mnemonic securely for signing
secureStorage.setKeyToLocalStorage({
  address: generatedAccount.addr,
  mnemonic,
  expiredAt: expirationTime
});

// Set trading key to client
client.mainWallet.tradingKey = generatedAccount.addr;

revokeTradingKey

Revoke an existing trading key.

Type imports:

import { ITradingKeyData, TradingKeyType } from '@ultrade/shared/browser/interfaces';

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | data | ITradingKeyData | Yes | Trading key data object |

ITradingKeyData interface (from @ultrade/shared):

| Property | Type | Required | Description | |----------|------|----------|-------------| | tkAddress | string | Yes | Trading key address to revoke | | device | string | No | Device identifier (user agent string, e.g., "Chrome 123.0.0.0 Blink Linux, desktop", "Chrome 121.0.0.0 Blink Android, mobile") | | type | TradingKeyType | No | Key type enum (imported from @ultrade/shared/browser/interfaces, see TradingKeyType enum) | | loginAddress | string | Yes | Login wallet address | | loginChainId | number | Yes | Login chain ID |

Returns: Promise<IRevokeTradingKeyResponse>

Example:

import { ITradingKeyData, TradingKeyType } from '@ultrade/shared/browser/interfaces';

await client.revokeTradingKey({
  tkAddress: 'TK_ADDRESS_HERE',
  device: navigator.userAgent, // e.g., "Chrome 123.0.0.0 Blink Linux, desktop"
  type: TradingKeyType.User,
  loginAddress: client.mainWallet?.address || '',
  loginChainId: 1 // Chain ID (e.g., 1 for Algorand)
});

console.log('Trading key revoked');

System

getSettings

Get platform settings.

Returns: Promise<SettingsInit>

Note: Returns an object with dynamic keys based on SettingIds enum. Common properties include:

• partnerId: Partner ID
• isUltrade: Whether it's Ultrade platform
• companyId: Company ID
• currentCountry: Current country (optional)
• Various setting values indexed by SettingIds enum keys

Example:

const settings = await client.getSettings();

console.log('Company ID:', settings.companyId);
console.log('Partner ID:', settings.partnerId);
console.log('Is Ultrade:', settings.isUltrade);
console.log('Current country:', settings.currentCountry);
// Access specific settings by SettingIds enum
console.log('App title:', settings[SettingIds.APP_TITLE]);

getVersion

Get API version information.

Returns: Promise<ISystemVersion>

ISystemVersion interface:

| Property | Type | Description | |----------|------|-------------| | version | string \| null | API version string |

Example:

const version = await client.getVersion();

console.log('API version:', version.version);

getMaintenance

Get maintenance status.

Returns: Promise<ISystemMaintenance>

ISystemMaintenance interface:

| Property | Type | Description | |----------|------|-------------| | mode | MaintenanceMode | Maintenance mode enum |

Example:

import { MaintenanceMode } from '@ultrade/ultrade-js-sdk';

const maintenance = await client.getMaintenance();

if (maintenance.mode === MaintenanceMode.ACTIVE) {
  console.log('Platform is under maintenance');
}

ping

Check latency to the server.

Returns: Promise<number> - Latency in milliseconds

Example:

const latency = await client.ping();

console.log(`Server latency: ${latency}ms`);

getChains

Get supported blockchain chains.

Returns: Promise<Chain[]>

Chain interface:

| Property | Type | Description | |----------|------|-------------| | chainId | number | Chain ID | | whChainId | string | Wormhole chain ID | | tmc | string | TMC identifier | | name | BLOCKCHAINS | Blockchain name enum |

Example:

const chains = await client.getChains();

chains.forEach(chain => {
  console.log(`${chain.name} (Chain ID: ${chain.chainId}, WH Chain ID: ${chain.whChainId})`);
});

getDollarValues

Get USD values for assets.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | assetIds | number[] | No | Array of asset IDs (default: empty array for all) |

Returns: Promise<IGetDollarValues>

Note: Returns an object with dynamic keys ([key: string]: number), where keys are asset IDs and values are USD prices.

Example:

// Get prices for specific assets
const prices = await client.getDollarValues([0, 1, 2]);

// Get prices for all assets
const allPrices = await client.getDollarValues();

// Access prices by asset ID
Object.keys(prices).forEach(assetId => {
  console.log(`Asset ${assetId}: $${prices[assetId]}`);
});

getTransactionDetalis

Get detailed transaction information.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | transactionId | number | Yes | Transaction ID |

Returns: Promise<ITransactionDetails>

Example:

const details = await client.getTransactionDetalis(12345);

console.log('Transaction:', {
  id: details.id,
  primaryId: details.primaryId,
  actionType: details.action_type,
  amount: details.amount,
  status: details.status,
  targetAddress: details.targetAddress,
  timestamp: details.timestamp,
  createdAt: details.createdAt,
  fee: details.fee
});

getWithdrawalFee

Get withdrawal fee for an asset.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | assetAddress | string | Yes | Asset address | | chainId | number | Yes | Chain ID |

Returns: Promise<IWithdrawalFee>

IWithdrawalFee interface:

| Property | Type | Description | |----------|------|-------------| | fee | string | Withdrawal fee amount | | dollarValue | string | Fee value in USD |

Example:

const fee = await client.getWithdrawalFee('ASSET_ADDRESS', 1);

console.log('Withdrawal fee:', fee.fee);
console.log('Fee in USD:', fee.dollarValue);

Market Data

getPairList

Retrieve list of all trading pairs.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | companyId | number | No | Filter by company ID |

Returns: Promise<IPairDto[]>

Example:

const pairs = await client.getPairList();

pairs.forEach(pair => {
  console.log(`${pair.pair_name}: ${pair.base_currency}/${pair.price_currency}`);
  console.log(`Pair ID: ${pair.id}, Active: ${pair.is_active}`);
});

getPair

Get detailed information about a specific trading pair.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | symbol | string \| number | Yes | Trading pair symbol or ID |

Returns: Promise<IPairDto>

IPairDto interface:

| Property | Type | Description | |----------|------|-------------| | id | number | Pair ID | | pairId | number | Pair ID (alternative) | | pair_key | string | Pair key | | pair_name | string | Pair name | | base_currency | string | Base currency symbol | | base_decimal | number | Base token decimals | | base_id | string | Base token ID | | base_chain_id | number | Base chain ID | | price_currency | string | Price currency symbol | | price_decimal | number | Price token decimals | | price_id | string | Price token ID | | price_chain_id | number | Price chain ID | | min_order_size | string | Minimum order size | | min_price_increment | string | Minimum price increment | | min_size_increment | string | Minimum size increment | | is_active | boolean | Whether pair is active | | current_price | string | Current price (optional) | | volume_24 | string | 24h volume (optional) | | change_24 | string | 24h change (optional) |

Example:

const pair = await client.getPair('ALGO/USDC');

console.log('Pair info:', {
  id: pair.id,
  pairId: pair.pairId,
  pairName: pair.pair_name,
  baseCurrency: pair.base_currency,
  priceCurrency: pair.price_currency,
  minOrderSize: pair.min_order_size,
  minPriceIncrement: pair.min_price_increment,
  isActive: pair.is_active,
  currentPrice: pair.current_price
});

getPrice

Get current market price for a trading pair.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | symbol | string | Yes | Trading pair symbol |

Returns: Promise<IGetPrice>

IGetPrice interface:

| Property | Type | Description | |----------|------|-------------| | ask | number | Ask price (sell orders) | | bid | number | Bid price (buy orders) | | last | number | Last trade price |

Example:

const price = await client.getPrice('ALGO/USDC');

console.log('Ask price:', price.ask);
console.log('Bid price:', price.bid);
console.log('Last price:', price.last);

getDepth

Get order book depth for a trading pair.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | symbol | string | Yes | Trading pair symbol | | depth | number | Yes | Number of price levels (max 20) |

Returns: Promise<IGetDepth>

IGetDepth interface:

| Property | Type | Description | |----------|------|-------------| | buy | string[][] | Buy orders (bids) array | | sell | string[][] | Sell orders (asks) array | | pair | string | Trading pair symbol | | ts | number | Timestamp | | U | number | Update ID (upper) | | u | number | Update ID (lower) |

Example:

const depth = await client.getDepth('ALGO/USDC', 10);

console.log('Bids (buy orders):', depth.buy);
console.log('Asks (sell orders):', depth.sell);
console.log('Pair:', depth.pair);
console.log('Last update ID:', depth.U);

getSymbols

Get list of trading pairs matching a pattern.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | mask | string | No | Search mask (e.g., 'ALGO') |

Returns: Promise<IGetSymbols>

Note: Returns an array of IGetSymbolsItem objects.

IGetSymbolsItem interface:

| Property | Type | Description | |----------|------|-------------| | pairKey | string | Trading pair key |

Example:

const symbols = await client.getSymbols('ALGO');

symbols.forEach(symbol => {
  console.log('Pair:', symbol.pairKey);
});

getLastTrades

Get recent trades for a trading pair.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | symbol | string | Yes | Trading pair symbol |

Returns: Promise<IGetLastTrades>

Note: Returns a single IGetLastTrades object, not an array.

IGetLastTrades interface:

| Property | Type | Description | |----------|------|-------------| | tradeId | number | Trade ID | | amount | string | Trade amount | | createdAt | number | Creation timestamp | | price | string | Trade price | | isBuyerMaker | boolean | Whether buyer is maker |

Example:

const trade = await client.getLastTrades('ALGO/USDC');

console.log(`Trade ${trade.tradeId}: ${trade.amount} @ ${trade.price}`);
console.log(`Buyer is maker: ${trade.isBuyerMaker}`);
console.log(`Created: ${new Date(trade.createdAt)}`);

getHistory

Get historical candlestick data.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | symbol | string | Yes | Trading pair symbol | | interval | string | Yes | Candle interval ('1m', '5m', '1h', '1d', etc.) | | startTime | number | No | Start timestamp (ms) | | endTime | number | No | End timestamp (ms) | | limit | number | No | Number of candles (default: 500) | | page | number | No | Page number (default: 1) |

Returns: Promise<IGetHistoryResponse>

IGetHistoryResponse interface:

| Property | Type | Description | |----------|------|-------------| | t | number[] | Timestamps array | | o | number[] | Open prices array | | c | number[] | Close prices array | | l | number[] | Low prices array | | h | number[] | High prices array | | v | number[] | Volumes array | | q | number[] | Quote volumes array | | s | string | Symbol | | b | number | Base value |

Example:

const history = await client.getHistory(
  'ALGO/USDC',
  '1h',
  Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
  Date.now(),
  100,
  1
);

// Access candle data by index
for (let i = 0; i < history.t.length; i++) {
  console.log(`[${new Date(history.t[i])}] O:${history.o[i]} H:${history.h[i]} L:${history.l[i]} C:${history.c[i]} V:${history.v[i]}`);
}

Trading

createSpotOrder

Place a new order.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | order | CreateSpotOrderArgs | Yes | Order creation data object |

CreateSpotOrderArgs interface:

| Property | Type | Required | Description | |----------|------|----------|-------------| | pairId | number | Yes | Trading pair ID | | companyId | number | Yes | Company ID | | orderSide | 'S' \| 'B' | Yes | Order side (S=SELL, B=BUY) | | orderType | 'L' \| 'I' \| 'P' \| 'M' | Yes | Order type | | amount | string | Yes | Order quantity | | price | string | Yes | Order price | | decimalPrice | number | Yes | Price decimal places | | address | string | Yes | Trading key address | | chainId | number | Yes | Chain ID | | baseTokenAddress | string | Yes | Base token address | | baseTokenChainId | number | Yes | Base token chain ID | | baseChain | string | Yes | Base chain name | | baseCurrency | string | Yes | Base currency symbol | | baseDecimal | number | Yes | Base token decimals | | priceTokenAddress | string | Yes | Price token address | | priceTokenChainId | number | Yes | Price token chain ID | | priceChain | string | Yes | Price chain name | | priceCurrency | string | Yes | Price currency symbol | | priceDecimal | number | Yes | Price token decimals |

Returns: Promise<IOrderDto>

Example:

const order = await client.createSpotOrder({
  pairId: 1,
  companyId: 1,
  orderSide: 'B',
  orderType: 'L',
  amount: '100',
  price: '1.25',
  decimalPrice: 2,
  address: client.mainWallet?.tradingKey || '',
  chainId: 1,
  baseTokenAddress: 'ALGO_ADDRESS',
  baseTokenChainId: 1,
  baseChain: 'algorand',
  baseCurrency: 'ALGO',
  baseDecimal: 6,
  priceTokenAddress: 'USDC_ADDRESS',
  priceTokenChainId: 1,
  priceChain: 'algorand',
  priceCurrency: 'USDC',
  priceDecimal: 6
});

console.log('Order created:', order.id);
console.log('Status:', order.status);

cancelOrder

Cancel an existing order.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | order | CancelOrderArgs | Yes | Order cancellation data object |

CancelOrderArgs interface:

| Property | Type | Required | Description | |----------|------|----------|-------------| | orderId | number | Yes | Order ID to cancel | | orderSide | 'S' \| 'B' | Yes | Order side (S=SELL, B=BUY) | | orderType | 'L' \| 'I' \| 'P' \| 'M' | Yes | Order type | | amount | string | Yes | Order amount | | price | string | Yes | Order price | | baseTokenAddress | string | Yes | Base token address | | baseChain | string | Yes | Base chain name | | baseCurrency | string | Yes | Base currency symbol | | baseDecimal | number | Yes | Base token decimals | | priceTokenAddress | string | Yes | Price token address | | priceChain | string | Yes | Price chain name | | priceCurrency | string | Yes | Price currency symbol | | priceDecimal | number | Yes | Price token decimals |

Returns: Promise<ICancelOrderResponse>

ICancelOrderResponse interface:

| Property | Type | Description | |----------|------|-------------| | orderId | number | Order ID | | isCancelled | boolean | Whether order was cancelled | | amount | string | Order amount (optional) | | filledAmount | string | Filled amount (optional) | | filledTotal | string | Filled total (optional) | | averageExecutedPrice | string | Average executed price (optional) |

Example:

const result = await client.cancelOrder({
  orderId: 12345,
  orderSide: 'B',
  orderType: 'L',
  amount: '100',
  price: '1.25',
  baseTokenAddress: 'ALGO_ADDRESS',
  baseChain: 'algorand',
  baseCurrency: 'ALGO',
  baseDecimal: 6,
  priceTokenAddress: 'USDC_ADDRESS',
  priceChain: 'algorand',
  priceCurrency: 'USDC',
  priceDecimal: 6
});

console.log('Order cancelled:', result.isCancelled);
console.log('Order ID:', result.orderId);
if (result.filledAmount) {
  console.log('Filled amount:', result.filledAmount);
}

cancelMultipleOrders

Cancel multiple orders at once.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | orderIds | number[] | No* | Array of order IDs | | pairId | number | No* | Cancel all orders for pair |

*At least one parameter is required

Returns: Promise<ICancelMultipleOrdersResponse>

Note: Returns an array of ICancelMultipleOrdersResponseItem objects.

ICancelMultipleOrdersResponseItem interface:

| Property | Type | Description | |----------|------|-------------| | orderId | number | Order ID | | pairId | number | Pair ID | | isCancelled | boolean | Whether order was cancelled | | reason | string | Cancellation reason (optional) | | amount | string | Order amount (optional) | | filledAmount | string | Filled amount (optional) | | filledTotal | string | Filled total (optional) |

Example:

// Cancel specific orders
const results = await client.cancelMultipleOrders({
  orderIds: [123, 456, 789]
});

results.forEach(result => {
  console.log(`Order ${result.orderId}: ${result.isCancelled ? 'Cancelled' : 'Failed'}`);
  if (result.reason) {
    console.log(`Reason: ${result.reason}`);
  }
});

// Cancel all orders for a pair
const pairResults = await client.cancelMultipleOrders({
  pairId: 1
});

getOrders

Get user's orders with filters.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | symbol | string | No | Filter by trading pair | | status | number | No | Filter by status (1=Open, 2=Closed) | | limit | number | No | Max results (default: 50) | | endTime | number | No | End timestamp (ms) | | startTime | number | No | Start timestamp (ms) |

Returns: Promise<IOrderDto[]>

Example:

// Get all open orders
const openOrders = await client.getOrders(undefined, 1);

// Get ALGO/USDC orders
const algoOrders = await client.getOrders('ALGO/USDC');

// Get last 100 orders
const recentOrders = await client.getOrders(undefined, undefined, 100);

// Get orders with time range
const timeRangeOrders = await client.getOrders(
  'ALGO/USDC',
  1,
  50,
  Date.now(),
  Date.now() - 24 * 60 * 60 * 1000
);

getOrderById

Get detailed information about a specific order.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | orderId | number | Yes | Order ID |

Returns: Promise<Order>

Order interface:

Extends IOrderDto with additional properties:

• executed: boolean - Whether order is executed
• updateStatus: OrderUpdateStaus - Update status (optional)
• base_currency: string - Base currency symbol
• base_decimal: number - Base token decimals
• price_currency: string - Price currency symbol
• price_decimal: number - Price token decimals
• min_size_increment: string - Minimum size increment
• min_price_increment: string - Minimum price increment
• price_id: number - Price token ID

IOrderDto properties:

| Property | Type | Description | |----------|------|-------------| | id | number | Order ID | | pairId | number | Pair ID | | pair | string | Pair symbol | | status | OrderStatus | Order status | | side | 0 \| 1 | Order side (0=Buy, 1=Sell) | | type | OrderTypeEnum | Order type | | price | string | Order price | | amount | string | Order amount | | filledAmount | string | Filled amount | | total | string | Total value | | filledTotal | string | Filled total | | avgPrice | string | Average execution price | | createdAt | number | Creation timestamp | | updatedAt | number | Update timestamp (optional) | | completedAt | number | Completion timestamp (optional) | | trades | ITradeDto[] | Trade history (optional) |

Example:

const order = await client.getOrderById(12345);

console.log('Order details:', {
  id: order.id,
  pair: order.pair,
  side: order.side === 0 ? 'BUY' : 'SELL',
  price: order.price,
  amount: order.amount,
  filledAmount: order.filledAmount,
  status: order.status,
  executed: order.executed,
  baseCurrency: order.base_currency,
  priceCurrency: order.price_currency
});

Account & Balances

getBalances

Get user's balances for all assets.

Returns: Promise<CodexBalanceDto[]>

CodexBalanceDto interface:

| Property | Type | Description | |----------|------|-------------| | hash | string | Balance hash | | loginAddress | string | Login wallet address | | loginChainId | number | Login chain ID | | tokenId | number | Token ID | | tokenAddress | string | Token address | | tokenChainId | number | Token chain ID | | amount | string | Available amount | | lockedAmount | string | Locked amount |

Example:

const balances = await client.getBalances();

balances.forEach(balance => {
  console.log(`Token ${balance.tokenId} (${balance.tokenAddress}):`);
  console.log(`  Available: ${balance.amount}`);
  console.log(`  Locked: ${balance.lockedAmount}`);
});

getCodexAssets

Get all available Codex assets.

Returns: Promise<CodexBalanceDto>

Note: Returns a single CodexBalanceDto object, not an array.

Example:

const assets = await client.getCodexAssets();

console.log('Available assets:', assets);

getCCTPAssets

Get CCTP (Cross-Chain Transfer Protocol) assets.

Returns: Promise<MappedCCTPAssets>

Note: Returns an object with dynamic keys ([key: string]: CCTPAssets[]), where keys are asset identifiers and values are arrays of CCTP assets.

CCTPAssets interface:

| Property | Type | Description | |----------|------|-------------| | chainId | number | Wormhole chain ID | | address | string | Token address | | unifiedChainId | number | Unified chain ID |

Example:

const cctpAssets = await client.getCCTPAssets();

Object.keys(cctpAssets).forEach(assetKey => {
  console.log(`Asset ${assetKey}:`);
  cctpAssets[assetKey].forEach(asset => {
    console.log(`  Chain ${asset.chainId}: ${asset.address}`);
  });
});

getCCTPUnifiedAssets

Get unified CCTP assets across chains.

Returns: Promise<CCTPUnifiedAssets[]>

CCTPUnifiedAssets interface:

| Property | Type | Description | |----------|------|-------------| | id | number | Asset ID | | chainId | number | Chain ID | | address | string | Token address | | symbol | string | Token symbol |

Example:

const unifiedAssets = await client.getCCTPUnifiedAssets();

unifiedAssets.forEach(asset => {
  console.log(`${asset.symbol} on chain ${asset.chainId}: ${asset.address}`);
});

Wallet Operations

withdraw

Withdraw funds from the exchange.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | withdrawData | IWithdrawData | Yes | Withdrawal data object | | prettyMsg | string | No | Custom withdrawal message |

IWithdrawData interface:

| Property | Type | Required | Description | |----------|------|----------|-------------| | assetId | number | Yes | Asset ID to withdraw | | amount | string | Yes | Withdrawal amount | | recipient | string | Yes | Recipient address | | chainId | number | No | Target chain ID |

Returns: Promise<IWithdrawResponse>

Example:

const withdrawal = await client.withdraw({
  assetId: 0, // ALGO
  amount: '100',
  recipient: 'RECIPIENT_ADDRESS_HERE',
  chainId: 1
}, 'Withdrawal to my wallet');

console.log('Withdrawal operation ID:', withdrawal.operationId);
console.log('Withdrawal txn:', withdrawal.txnId);

transfer

Transfer funds between accounts.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | transferData | ITransferData | Yes | Transfer data object |

ITransferData interface:

| Property | Type | Required | Description | |----------|------|----------|-------------| | assetId | number | Yes | Asset ID | | amount | string | Yes | Transfer amount | | recipient | string | Yes | Recipient address | | memo | string | No | Transfer memo |

Returns: Promise<ITransfer>

Example:

const transfer = await client.transfer({
  assetId: 0,
  amount: '50',
  recipient: 'RECIPIENT_ADDRESS',
  memo: 'Payment for services'
});

console.log('Transfer ID:', transfer.transferId);
console.log('Status:', transfer.status);

getWalletTransactions

Get wallet transaction history.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | type | string | Yes | Transaction type ('DEPOSIT', 'WITHDRAWAL', etc.) | | page | number | Yes | Page number | | limit | number | No | Results per page (default: 100) |

Returns: Promise<PaginatedResult<ITransaction>>

Example:

const transactions = await client.getWalletTransactions('DEPOSIT', 1, 50);

console.log(`Page ${transactions.page} of ${transactions.totalPages}`);
console.log('Transactions:', transactions.data);

getTransfers

Get transfer history.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | page | number | Yes | Page number | | limit | number | No | Results per page (default: 100) |

Returns: Promise<PaginatedResult<ITransfer>>

Example:

const transfers = await client.getTransfers(1, 20);

transfers.data.forEach(transfer => {
  console.log(`Transfer ${transfer.transferId}: ${transfer.amount} from ${transfer.senderAddress} to ${transfer.recipientAddress}`);
  console.log(`Status: ${transfer.status}, Completed: ${transfer.completedAt}`);
});

getPendingTransactions

Get pending transactions.

Returns: Promise<IPendingTxn[]>

Example:

const pending = await client.getPendingTransactions();

console.log('Pending transactions:', pending.length);

getTradingKeys

Get user's trading keys.

Type imports:

import { ITradingKey } from '@ultrade/ultrade-js-sdk';
import { TradingKeyType } from '@ultrade/shared/browser/interfaces';

Returns: Promise<ITradingKey>

Note: Returns a single ITradingKey object, not an array.

ITradingKey interface:

| Property | Type | Description | |----------|------|-------------| | address | string | Trading key address | | createdAt | Date | Creation timestamp | | expiredAt | Date | Expiration timestamp | | orders | number | Number of orders | | device | string | Device identifier (user agent string, e.g., "Chrome 123.0.0.0 Blink Linux, desktop", "Chrome 121.0.0.0 Blink Android, mobile") | | type | TradingKeyType | Key type enum (optional, imported from @ultrade/shared/browser/interfaces, see TradingKeyType enum) |

Example:

import { TradingKeyType } from '@ultrade/shared/browser/interfaces';

const tradingKey = await client.getTradingKeys();

console.log('Trading key address:', tradingKey.address);
console.log('Expires at:', tradingKey.expiredAt);
console.log('Orders count:', tradingKey.orders);

Whitelist & Withdrawal Wallets

getWhitelist

Get withdrawal whitelist.

Returns: Promise<PaginatedResult<IGetWhiteList>>

IGetWhiteList interface:

| Property | Type | Description | |----------|------|-------------| | id | number | Whitelist entry ID | | recipientAddress | string | Recipient wallet address | | tkAddress | string | Trading key address | | expiredAt | number | Expiration timestamp |

Example:

const whitelist = await client.getWhitelist();

whitelist.data.forEach(item => {
  console.log(`${item.recipientAddress} - expires: ${new Date(item.expiredAt)}`);
});

addWhitelist

Add address to withdrawal whitelist.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | data | IWhiteList | Yes | Whitelist data object |

IWhiteList interface:

| Property | Type | Required | Description | |----------|------|----------|-------------| | id | number | No | Whitelist entry ID (for updates) | | loginAddress | string | Yes | Login wallet address | | loginChainId | number | Yes | Login chain ID | | recipient | string | Yes | Recipient wallet address | | recipientChainId | number | Yes | Recipient chain ID | | tkAddress | string | Yes | Trading key address | | expiredDate | number | No | Expiration timestamp in milliseconds (will be converted to seconds internally) |

Returns: Promise<IGetWhiteList>

Example:

const whitelisted = await client.addWhitelist({
  loginAddress: client.mainWallet?.address || '',
  loginChainId: 1,
  recipient: 'WHITELISTED_ADDRESS',
  recipientChainId: 1,
  tkAddress: client.mainWallet?.tradingKey || '',
  expiredDate: Date.now() + 365 * 24 * 60 * 60 * 1000 // 1 year
});

console.log('Address whitelisted:', whitelisted.id);

deleteWhitelist

Remove address from whitelist.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | whitelistId | number | Yes | Whitelist entry ID |

Returns: Promise<void>

Example:

await client.deleteWhitelist(123);

getAllWithdrawalWallets

Get all withdrawal wallets.

Returns: Promise<ISafeWithdrawalWallets[]>

ISafeWithdrawalWallets interface:

| Property | Type | Description | |----------|------|-------------| | name | string | Wallet name | | type | WithdrawalWalletType | Wallet type | | address | string | Wallet address | | description | string | Wallet description | | createdAt | Date | Creation timestamp |

Example:

const wallets = await client.getAllWithdrawalWallets();

wallets.forEach(wallet => {
  console.log(`${wallet.name}: ${wallet.address}`);
  console.log(`Type: ${wallet.type}, Description: ${wallet.description}`);
});

createWithdrawalWallet

Create a new withdrawal wallet.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | body | CreateWithdrawalWallet | Yes | Withdrawal wallet creation data object |

CreateWithdrawalWallet interface:

Extends ISignedMessage<WithdrawalWalletData> with:

• data: Contains address, name, type, description?
• message: Signed message
• signature: Message signature

Returns: Promise<ISafeWithdrawalWallets>

ISafeWithdrawalWallets interface:

| Property | Type | Description | |----------|------|-------------| | name | string | Wallet name | | type | WithdrawalWalletType | Wallet type | | address | string | Wallet address | | description | string | Wallet description | | createdAt | Date | Creation timestamp |

Example:

const wallet = await client.createWithdrawalWallet({
  data: {
    address: 'WALLET_ADDRESS',
    name: 'Main wallet',
    type: WithdrawalWalletType.SAFE,
    description: 'My main withdrawal wallet'
  },
  message: 'SIGNED_MESSAGE',
  signature: 'SIGNATURE'
});

console.log('Wallet created:', wallet.address);
console.log('Name:', wallet.name);

updateWithdrawalWallet

Update withdrawal wallet.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | params | UpdateWithdrawalWallet | Yes | Withdrawal wallet update data object |

UpdateWithdrawalWallet interface:

Extends ISignedMessage<UpdateWithdrawalWalletData> with:

• data: Contains oldAddress, address, name, type, description?
• message: Signed message
• signature: Message signature

Returns: Promise<boolean>

Example:

await client.updateWithdrawalWallet({
  data: {
    oldAddress: 'OLD_WALLET_ADDRESS',
    address: 'NEW_WALLET_ADDRESS',
    name: 'Updated wallet name',
    type: WithdrawalWalletType.SAFE,
    description: 'Updated description'
  },
  message: 'SIGNED_MESSAGE',
  signature: 'SIGNATURE'
});

deleteWithdrawalWallet

Delete withdrawal wallet.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | address | string | Yes | Wallet address |

Returns: Promise<boolean>

Example:

await client.deleteWithdrawalWallet('WALLET_ADDRESS');

KYC

getKycStatus

Get user's KYC verification status.

Returns: Promise<IGetKycStatus>

IGetKycStatus interface:

| Property | Type | Description | |----------|------|-------------| | kycStatus | KYCAuthenticationStatus | KYC authentication status (optional) |

Example:

import { KYCAuthenticationStatus } from '@ultrade/ultrade-js-sdk';

const kycStatus = await client.getKycStatus();

if (kycStatus.kycStatus) {
  console.log('KYC status:', kycStatus.kycStatus);
}

getKycInitLink

Initialize KYC verification process.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | embeddedAppUrl | string \| null | Yes | Callback URL after KYC |

Returns: Promise<IGetKycInitLink>

Example:

const kycLink = await client.getKycInitLink('https://myapp.com/kyc-callback');

console.log('KYC verification URL:', kycLink.url);
window.open(kycLink.url, '_blank');

WebSocket

subscribe

Subscribe to real-time WebSocket streams.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | subscribeOptions | SubscribeOptions | Yes | Subscription options object | | callback | Function | Yes | Event callback function |

SubscribeOptions interface:

| Property | Type | Required | Description | |----------|------|----------|-------------| | symbol | string | Yes | Trading pair symbol | | streams | STREAMS[] | Yes | Array of streams to subscribe | | options | object | Yes | Subscription options (e.g., address, depth, token, tradingKey) |

Returns: number - Handler ID for unsubscribing

Example:

import { STREAMS } from '@ultrade/ultrade-js-sdk';

const handlerId = client.subscribe(
  {
    symbol: 'ALGO/USDC',
    streams: [STREAMS.DEPTH, STREAMS.TRADES, STREAMS.TICKER],
    options: {
      address: client.mainWallet?.address || '',
      depth: 10
    }
  },
  (event: string, data: any) => {
    console.log('WebSocket event:', event, data);
    
    switch(event) {
      case 'depth':
        console.log('Order book update:', data);
        break;
      case 'trade':
        console.log('New trade:', data);
        break;
      case 'ticker':
        console.log('Price ticker:', data);
        break;
    }
  }
);

// Save handler ID for cleanup

unsubscribe

Unsubscribe from WebSocket streams.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | handlerId | number | Yes | Handler ID from subscribe |

Returns: void

Example:

// Unsubscribe using handler ID
client.unsubscribe(handlerId);

Notifications

getNotifications

Get user notifications.

Returns: Promise<UserNotification[]>

UserNotification interface:

| Property | Type | Description | |----------|------|-------------| | id | number | Notification ID | | globalNotificationId | number | Global notification ID | | priority | any | Notification priority | | status | any | Notification status | | type | any | Notification type | | message | string | Notification message | | createdAt | Date | Creation timestamp |

Example:

const notifications = await client.getNotifications();

notifications.forEach(notif => {
  console.log(`[${notif.type}] ${notif.message}`);
  console.log('Status:', notif.status);
  console.log('Created:', notif.createdAt);
});

getNotificationsUnreadCount

Get count of unread notifications.

Returns: Promise<IUnreadNotificationsCount>

Example:

const { count } = await client.getNotificationsUnreadCount();

console.log(`You have ${count} unread notifications`);

readNotifications

Mark notifications as read.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | notifications | UpdateUserNotificationDto[] | Yes | Array of notifications to update |

UpdateUserNotificationDto interface:

| Property | Type | Required | Description | |----------|------|----------|-------------| | id | number | No | Notification ID | | globalNotificationId | number | No | Global notification ID | | status | NotificationStatusEnum | Yes | Notification status |

Returns: Promise<UpdateUserNotificationDto[]>

Example:

import { NotificationStatusEnum } from '@ultrade/ultrade-js-sdk';

await client.readNotifications([
  { id: 1, status: NotificationStatusEnum.READ },
  { globalNotificationId: 2, status: NotificationStatusEnum.READ }
]);

Affiliates

getAffiliatesStatus

Get affiliate program status.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | companyId | number | Yes | Company ID |

Returns: Promise<IAffiliateDashboardStatus>

IAffiliateDashboardStatus interface:

| Property | Type | Description | |----------|------|-------------| | enabled | boolean | Whether affiliate program is enabled | | isAffiliate | boolean | Whether user is an affiliate |

Example:

const status = await client.getAffiliatesStatus(1);

console.log('Is affiliate:', status.isAffiliate);
console.log('Program enabled:', status.enabled);

createAffiliate

Register as an affiliate.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | companyId | number | Yes | Company ID |

Returns: Promise<DashboardInfo>

DashboardInfo interface:

| Property | Type | Description | |----------|------|-------------| | feeShare | number | Fee share percentage | | referralLink | string | Referral link | | summaryStats | AffiliateSummaryStats | Summary statistics | | trendStats | AffiliateTrendStats \| null | Trend statistics (optional) |

Example:

const affiliate = await client.createAffiliate(1);

console.log('Referral link:', affiliate.referralLink);
console.log('Fee share:', affiliate.feeShare);
console.log('Summary stats:', affiliate.summaryStats);

getAffiliateProgress

Get affiliate progress.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | companyId | number | Yes | Company ID |

Returns: Promise<IAffiliateProgress>

IAffiliateProgress interface:

| Property | Type | Description | |----------|------|-------------| | totalTradingVolumeUsd | number | Total trading volume in USD | | unlockThreshold | number | Threshold to unlock affiliate status |

Example:

const progress = await client.getAffiliateProgress(1);

console.log('Trading volume (USD):', progress.totalTradingVolumeUsd);
console.log('Unlock threshold:', progress.unlockThreshold);
console.log('Progress:', (progress.totalTradingVolumeUsd / progress.unlockThreshold * 100).toFixed(2) + '%');

getAffiliateInfo

Get affiliate dashboard information.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | companyId | number | Yes | Company ID | | range | string | Yes | Date range ('day', 'week', 'month', 'all') |

Returns: Promise<DashboardInfo>

Example:

const info = await client.getAffiliateInfo(1, 'month');

console.log('Referral link:', info.referralLink);
console.log('Fee share:', info.feeShare);
console.log('Total revenue:', info.summaryStats.totalRevenue);
console.log('Link clicks:', info.summaryStats.linkClicks);
console.log('Registrations:', info.summaryStats.registrations);
console.log('Trading volume:', info.summaryStats.totalTradingVolume);

countAffiliateDepost

Count affiliate deposit.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | companyId | number | Yes | Company ID |

Returns: Promise<void>

Example:

await client.countAffiliateDepost(1);

countAffiliateClick

Track affiliate referral click.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | referralToken | string | Yes | Referral token |

Returns: Promise<void>

Example:

await client.countAffiliateClick('REF123');

Social

getSocialAccount

Get user's social account information.

Returns: Promise<ISocialAccount | undefined>

ISocialAccount interface:

| Property | Type | Description | |----------|------|-------------| | points | number | User points | | address | string | Wallet address | | email | string | Email address (optional) | | emailVerified | boolean | Email verification status | | twitterAccount | object | Twitter account info (optional) | | telegramAccount | object | Telegram account info (optional) | | discordAccount | object | Discord account info (optional) |

Example:

const social = await client.getSocialAccount();

if (social) {
  console.log('Address:', social.address);
  console.log('Points:', social.points);
  console.log('Email:', social.email);
  console.log('Email verified:', social.emailVerified);
  if (social.twitterAccount) {
    console.log('Twitter:', social.twitterAccount.userName);
  }
}

addSocialEmail

Add email to social account.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | email | string | Yes | Email address | | embeddedAppUrl | string | Yes | Callback URL |

Returns: Promise<void>

Example:

await client.addSocialEmail(
  '[email protected]',
  'https://myapp.com/verify'
);

console.log('Verification email sent');

verifySocialEmail

Verify email address.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | email | string | Yes | Email address | | hash | string | Yes | Verification hash |

Returns: Promise<void>

Example:

await client.verifySocialEmail(
  '[email protected]',
  'VERIFICATION_HASH'
);

console.log('Email verified');

getLeaderboards

Get leaderboard rankings.

Returns: Promise<ILeaderboardItem[]>

ILeaderboardItem interface:

| Property | Type | Description | |----------|------|-------------| | address | string | Wallet address | | currentPoints | number | Current points | | tasksCompleted | number | Number of completed tasks | | twitter | string | Twitter username (optional) | | discord | string | Discord username (optional) | | telegram | string | Telegram username (optional) | | order | number | Ranking position |

Example:

const leaderboard = await client.getLeaderboards();

leaderboard.forEach((item) => {
  console.log(`${item.order}. ${item.address} - ${item.currentPoints} points`);
  console.log(`Tasks completed: ${item.tasksCompleted}`);
});

getUnlocks

Get user's unlocked achievements.

Returns: Promise<IUnlock[]>

IUnlock interface:

| Property | Type | Description | |----------|------|-------------| | id | number | Unlock ID | | companyId | number | Company ID | | seasonId | number | Season ID | | name | string | Unlock name | | description | string | Unlock description | | points | number | Points required | | enabled | boolean | Whether unlock is enabled |

Example:

const unlocks = await client.getUnlocks();

unlocks.forEach(unlock => {
  console.log(`Unlocked: ${unlock.name} - ${unlock.description}`);
  console.log(`Points: ${unlock.points}`);
});

getSocialSettings

Get social feature settings.

Returns: Promise<ISocialSettings>

Note: Returns an object with dynamic key-value pairs ([key: string]: any).

Example:

const settings = await client.getSocialSettings();

console.log('Social settings:', settings);
// Access specific settings by key
console.log('Setting value:', settings['someKey']);

getSeason

Get current active season.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | ultradeId | number | No | Ultrade ID (optional) |

Returns: Promise<ISocialSeason>

Example:

// Get season for default company
const season = await client.getSeason();

// Get season for specific Ultrade ID
const ultradeSeason = await client.getSeason(1);

console.log('Season:', season.name);
console.log('Start:', new Date(season.startDate));
console.log('End:', season.endDate ? new Date(season.endDate) : 'Ongoing');

getPastSeasons

Get historical seasons.

Returns: Promise<ISocialSeason[]>

ISocialSeason interface:

| Property | Type | Description | |----------|------|-------------| | id | number | Season ID | | companyId | number | Company ID | | startDate | Date | Season start date | | endDate | Date | Season end date (optional) | | name | string | Season name | | isSelected | boolean | Whether season is selected | | status | string | Season status | | createdAt | Date | Creation timestamp | | updatedAt | Date | Update timestamp |

Example:

const pastSeasons = await client.getPastSeasons();

pastSeasons.forEach(season => {
  console.log(`${season.name} (${new Date(season.startDate)} - ${season.endDate ? new Date(season.endDate) : 'Ongoing'})`);
  console.log(`Status: ${season.status}, Selected: ${season.isSelected}`);
});

Social Integrations

Telegram

addTelegram

Connect Telegram account.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | data | TelegramData | Yes | Telegram authentication data |

TelegramData interface:

| Property | Type | Required | Description | |----------|------|----------|-------------| | auth_date | number | Yes | Authentication date timestamp | | id | number | Yes | Telegram user ID | | first_name | string | Yes | First name | | hash | string | Yes | Authentication hash | | photo_url | string | Yes | Profile photo URL | | username | string | Yes | Telegram username |

Returns: Promise<ITelegramConnectResponse>

Example:

const result = await client.addTelegram({
  auth_date: Math.floor(Date.now() / 1000),
  id: 123456789,
  first_name: 'John',
  hash: 'TELEGRAM_HASH',
  photo_url: 'https://t.me/photo.jpg',
  username: 'myusername'
});

console.log('Telegram connected:', result.address);
console.log('Telegram ID:', result.telegramId);

disconnectTelegram

Disconnect Telegram account.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | data | TelegramData | Yes | Telegram authentication data |

Returns: Promise<void>

Example:

await client.disconnectTelegram({
  auth_date: Math.floor(Date.now() / 1000),
  id: 123456789,
  first_name: 'John',
  hash: 'TELEGRAM_HASH',
  photo_url: 'https://t.me/photo.jpg',
  username: 'myusername'
});

Discord

getDiscordConnectionUrl

Get Discord OAuth URL.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | url | string | Yes | Callback URL |

Returns: Promise<string> - Discord OAuth URL

Example:

const discordUrl = await client.getDiscordConnectionUrl(
  'https://myapp.com/discord-callback'
);

window.open(discordUrl, '_blank');

disconnectDiscord

Disconnect Discord account.

Returns: Promise<void>

Example:

await client.disconnectDiscord();

Twitter

getTwitterConnectionUrl

Get Twitter OAuth URL.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | appUrl | string | Yes | Callback URL | | permissions | string | No | OAuth scopes |

Returns: Promise<string> - Twitter OAuth URL

Example:

const twitterUrl = await client.getTwitterConnectionUrl(
  'https://myapp.com/twitter-callback',
  'tweet.read tweet.write'
);

window.open(twitterUrl, '_blank');

disconnectTwitter

Disconnect Twitter account.

Returns: Promise<void>

Example:

await client.disconnectTwitter();

getTweets

Get company tweets for interaction.

Returns: Promise<ICompanyTweet[]>

ICompanyTweet interface:

| Property | Type | Description | |----------|------|-------------| | id | string | Tweet ID | | companyId | number | Company ID | | seasonId | number | Season ID | | type | string | Tweet type | | text | string | Tweet text | | enabled | boolean | Whether tweet is enabled | | isProcessed | boolean | Processing status | | expiresAt | Date | Expiration date | | createdAt | Date | Creation timestamp | | updatedAt | Date | Update timestamp |

Example:

const tweets = await client.getTweets();

tweets.forEach(tweet => {
  console.log('Tweet:', tweet.text);
  console.log('Type:', tweet.type);
  console.log('Enabled:', tweet.enabled);
  console.log('Expires:', tweet.expiresAt);
});

actionWithTweet

Perform actions on a tweet.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | data | { actions: Array<{ id: number; text?: string }>; tweetId?: string } | Yes | Action data object |

Returns: Promise<void>

Example:

await client.actionWithTweet({
  actions: [
    { id: 1 }, // Like
    { id: 2, text: 'Great project!' } // Comment
  ],
  tweetId: 'TWEET_ID'
});

getActions

Get available social actions.

Returns: Promise<IAction[]>

Example:

const actions = await client.getActions();

actions.forEach(action => {
  console.log(`${action.name}: ${action.points} points`);
});

getActionHistory

Get user's action history.

Returns: Promise<IActionHistory[]>

IActionHistory interface:

| Property | Type | Description | |----------|------|-------------| | id | number | History entry ID | | address | string | Wallet address | | companyId | number | Company ID | | actionId | number | Action ID | | seasonId | number | Season ID | | source | string | Action source | | points | number | Points earned | | referenceId | string | Reference ID (optional) | | createdAt | Date | Creation timestamp |

Example:

const history = await client.getActionHistory();

history.forEach(item => {
  console.log(`Action ${item.actionId} - ${item.points} points - ${item.source}`);
  console.log(`Date: ${item.createdAt}`);
});

getAIStyles

Get available AI comment styles.

Returns: Promise<IAIStyle[]>

IAIStyle interface:

| Property | Type | Description | |----------|------|-------------| | id | number | Style ID | | title | string | Style title | | content | string | Style content | | enabled | boolean | Whether style is enabled | | type | string | Style type | | createdAt | Date | Creation timestamp | | updatedAt | Date | Update timestamp |

Example:

const styles = await client.getAIStyles();

styles.forEach(style => {
  console.log(`${style.title}: ${style.content}`);
  console.log(`Type: ${style.type}, Enabled: ${style.enabled}`);
});

getAIComment

Generate AI comment for a tweet.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | styleId | number | Yes | AI style ID | | tweetId | string | Yes | Tweet ID |

Returns: Promise<IAIGeneratedComment>

Example:

const comment = await client.getAIComment(1, 'TWEET_ID');

console.log('Generated comment:', comment.comment);
console.log('Requests left:', comment.requestsLeft);

Structure

src/
├── argsAsObj/              # Method argument interfaces (RO-RO pattern)
│   ├── affiliates.args.ts  # Affiliate method arguments
│   ├── auth.args.ts        # Authentication arguments
│   ├── client.args.ts      # Client configuration arguments
│   ├── market.args.ts      # Market data arguments
│   ├── social.args.ts      # Social features arguments
│   ├── system.args.ts      # System method arguments
│   ├── trading.args.ts     # Trading operation arguments
│   ├── wallet.args.ts      # Wallet operation arguments
│   └── index.ts            # Barrel export
│
├── const/                  # Constants
│   ├── auth.const.ts       # Authentication constants
│   ├── client.const.ts     # Client configuration constants
│   └── index.ts
│
├── enum/                   # Enumerations
│   ├── account.enum.ts     # Account-related enums
│   ├── affiliates.enum.ts  # Affiliate enums
│   ├── common.enum.ts      # Common enums
│   ├── market.enum.ts      # Market enums
│   ├── social.enum.ts      # Social enums
│   ├── socket.enum.ts      # WebSocket stream enums
│   └── index.ts
│
├── interface/              # TypeScript interfaces
│   ├── account.interface.ts        # Account data interfaces
│   ├── affiliates.interface.ts     # Affiliate interfaces
│   ├── assets.interface.ts         # Asset interfaces
│   ├── auth.interface.ts           # Auth interfaces
│   ├── client.interface.ts         # Client interfaces
│   ├── common.interface.ts         # Common interfaces
│   ├── maintenance.interface.ts    # Maintenance interfaces
│   ├── market.interface.ts         # Market interfaces
│   ├── notification.interface.ts   # Notification interfaces
│   ├── social.interface.ts         # Social interfaces
│   ├── socket.interface.ts         # WebSocket interfaces
│   ├── system.interface.ts         # System interfaces
│   ├── trading.interface.ts        # Trading interfaces
│   ├── wallet.interface.ts         # Wallet interfaces
│   └── index.ts
│
├── utils/                  # Utility functions
│   ├── algodService.ts     # Algorand service
│   ├── algorand.util.ts    # Algorand utilities
│   ├── client.util.ts      # Client utilities
│   └── index.ts
│
├── client.ts               # Main SDK Client class
├── localStorage.ts         # Local storage service
├── sockets.ts              # WebSocket manager
└── index.ts                # Main entry point

TypeScript Path Aliases

Defined in tsconfig.alias.json:

| Alias | Path | Description | |-------|------|-------------| | @utils | ./src/utils/index.ts | Utility functions | | @interface | ./src/interface/index.ts | TypeScript interfaces | | @const | ./src/const/index.ts | Constants | | @enum | ./src/enum/index.ts | Enumerations |

Build Commands

Important: First install node_modules from monorepo root (npm_packages)

• npm run build - Production build
• npm run dev - Development build with watch mode
• npm run version:update - Bump patch version

Exports

The package exports:

• Client class - Main SDK client
• SocketManager - WebSocket connection manager
• All constants from @const
• All enums from @enum
• All interfaces f