ChainStream JavaScript/TypeScript SDK

A comprehensive JavaScript/TypeScript SDK for interacting with the ChainStream DEX Aggregator API and real-time streaming services. This SDK provides full TypeScript support and works seamlessly in Node.js, browser, and modern bundler environments.

Features

• 🔄 Real-time Streaming: WebSocket-based real-time data streaming for tokens, trades, wallets, and more
• 🪙 Token Management: Create, query, and manage tokens across multiple blockchains
• 💱 DEX Aggregation: Access to multiple decentralized exchanges with swap routing and quote services
• 💼 Wallet Operations: Track wallet balances, PnL, and token holdings
• 📊 Trading Data: Real-time trade data, market statistics, and ranking information
• 🔗 Multi-chain Support: Support for multiple blockchain networks
• 🎁 Red Packet: Create and manage red packet (hongbao) campaigns
• 📦 IPFS Integration: Upload and manage files on IPFS
• 🔍 Blockchain Data: Query blockchain information, gas prices, and transaction details
• ⚡ Job Management: Asynchronous job processing with SSE-based status tracking
• 📈 Rankings & Analytics: Token rankings, top traders, and market analytics
• 🎯 Watchlist: Manage token watchlists for monitoring

Installation

npm install @chainstream-io/sdk

or

yarn add @chainstream-io/sdk

Quick Start

Basic Usage

import { DexClient } from '@chainstream-io/sdk';

// Initialize client with access token
const client = new DexClient('your-access-token');

// Use API services
const tokens = await client.token.listTokens({
  chain: 'solana',
  limit: 10
});

console.log(tokens);

Using Token Provider

For dynamic token management:

import { DexClient, TokenProvider } from '@chainstream-io/sdk';

class MyTokenProvider implements TokenProvider {
  async getToken(): Promise<string> {
    // Fetch token from your auth service
    const response = await fetch('https://your-auth-service.com/token');
    const data = await response.json();
    return data.accessToken;
  }
}

const client = new DexClient(new MyTokenProvider());

Custom Configuration

const client = new DexClient('your-access-token', {
  serverUrl: 'https://api-dex.chainstream.io',
  streamUrl: 'wss://realtime-dex.chainstream.io/connection/websocket',
  debug: true
});

API Services

The SDK provides the following API services through the DexClient:

Token API (client.token)

• List and search tokens
• Get token details, metadata, and market data
• Query token holders and supply information
• Get token price data and statistics

DEX API (client.dex)

• List available DEXes
• Get swap quotes and routes
• Execute token swaps
• Create new tokens

DEX Pool API (client.dexpool)

• Query DEX pool information
• Get pool balances and liquidity data

Trade API (client.trade)

• Get trade history and details
• Query trade events and statistics

Wallet API (client.wallet)

• Get wallet balances
• Calculate wallet PnL (Profit and Loss)
• Query wallet token holdings

Ranking API (client.ranking)

• Get token rankings
• Query top traders
• Access gainers and losers data

Transaction API (client.transaction)

• Send transactions
• Estimate gas limits
• Get gas prices

Blockchain API (client.blockchain)

• Query blockchain information
• Get latest block data
• Access network identification data

Moonshot API (client.moonshot)

• Create tokens on Solana Moonshot platform
• Submit token creation transactions

Pumpfun API (client.pumpfun)

• Create tokens on Pumpfun platform
• Manage Pumpfun token operations

Red Packet API (client.redPacket)

• Create red packet campaigns
• Claim red packets
• Query red packet details and claims

IPFS API (client.ipfs)

• Upload files to IPFS
• Query IPFS file information

Watchlist API (client.watchlist)

• Create and manage watchlists
• Add/remove tokens from watchlists

Jobs API (client.jobs)

• Query job status
• Get job details

Real-time Streaming

The SDK includes a powerful streaming API for real-time data:

// Subscribe to token updates
const unsubscribe = client.stream.subscribeTokenMetadata(
  'solana',
  'token-address',
  (data) => {
    console.log('Token metadata updated:', data);
  }
);

// Subscribe to trade events
const unsubscribeTrade = client.stream.subscribeTradeActivity(
  'solana',
  { token: 'token-address' },
  (data) => {
    console.log('New trade:', data);
  }
);

// Subscribe to wallet balance changes
const unsubscribeBalance = client.stream.subscribeWalletBalance(
  'solana',
  'wallet-address',
  (data) => {
    console.log('Balance updated:', data);
  }
);

// Unsubscribe when done
unsubscribe();
unsubscribeTrade();
unsubscribeBalance();

Batch Subscriptions

For efficient bulk operations:

// Batch multiple subscriptions
const unsubscribes = client.stream.batchSubscribe(() => {
  const unsub1 = client.stream.subscribeTokenMetadata(
    'solana',
    'token1',
    (data) => console.log('Token 1:', data)
  );
  
  const unsub2 = client.stream.subscribeTokenMetadata(
    'solana',
    'token2',
    (data) => console.log('Token 2:', data)
  );
  
  return [unsub1, unsub2];
});

// Unsubscribe all at once
client.stream.batchUnsubscribe(unsubscribes);

Job Management

For long-running operations, use the job system:

// Start a job (returns job ID)
const job = await client.jobs.createJob({
  // job parameters
});

// Wait for job completion
try {
  const result = await client.waitForJob(job.id, 60000); // 60 second timeout
  console.log('Job completed:', result);
} catch (error) {
  console.error('Job failed:', error);
}

Usage Examples

Get Token List

const tokens = await client.token.listTokens({
  chain: 'solana',
  limit: 20,
  offset: 0
});

console.log(`Found ${tokens.data.length} tokens`);

Get Swap Quote

const quote = await client.dex.getQuote({
  chain: 'solana',
  swapInput: {
    fromToken: 'SOL',
    toToken: 'USDC',
    amount: '1000000000', // 1 SOL (in smallest unit)
    slippage: 0.01 // 1%
  }
});

console.log(`You'll receive ${quote.toAmount} ${quote.toToken}`);

Execute Swap

const swap = await client.dex.swap({
  chain: 'solana',
  swapInput: {
    fromToken: 'SOL',
    toToken: 'USDC',
    amount: '1000000000',
    slippage: 0.01,
    wallet: 'your-wallet-address'
  }
});

console.log('Swap transaction:', swap.txHash);

Get Wallet Balance

const balance = await client.wallet.getWalletBalances({
  chain: 'solana',
  address: 'wallet-address'
});

console.log('Wallet balances:', balance.balances);

Get Wallet PnL

const pnl = await client.wallet.getWalletPnl({
  chain: 'solana',
  address: 'wallet-address'
});

console.log('Wallet PnL:', pnl);

Create Red Packet

const redPacket = await client.redPacket.createRedPacket({
  chain: 'solana',
  createRedPacketInput: {
    token: 'USDC',
    totalAmount: '1000000',
    count: 10,
    // ... other parameters
  }
});

console.log('Red packet created:', redPacket.id);

Upload to IPFS

const file = new File(['content'], 'filename.txt');
const ipfsResult = await client.ipfs.uploadFile({
  file: file
});

console.log('IPFS hash:', ipfsResult.hash);

Get Token Rankings

const rankings = await client.ranking.getTokenRankings({
  chain: 'solana',
  type: 'volume',
  limit: 10
});

console.log('Top tokens:', rankings.data);

TypeScript Support

The SDK is written in TypeScript and provides full type definitions. All API methods, request parameters, and response types are fully typed for better developer experience and IDE autocomplete support.

License

MIT

Support

For issues, questions, or contributions, please visit our GitHub repository.