@chainstream-io/sdk 0.1.13 → 0.1.14

package/README.md

@@ -1,46 +1,353 @@
-## @chainstream-io/sdk@0.1.13
+# ChainStream JavaScript/TypeScript SDK
 
-This generator creates TypeScript/JavaScript client that utilizes [Fetch API](https://fetch.spec.whatwg.org/). The generated Node module can be used in the following environments:
+[![npm version](https://img.shields.io/npm/v/@chainstream-io/sdk.svg)](https://www.npmjs.com/package/@chainstream-io/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Environment
-* Node.js
-* Webpack
-* Browserify
+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.
 
-Language level
-* ES5 - you must have a Promises/A+ library installed
-* ES6
+## Features
 
-Module system
-* CommonJS
-* ES6 module system
+- 🔄 **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
 
-It can be used in both TypeScript and JavaScript. In TypeScript, the definition will be automatically resolved via `package.json`. ([Reference](https://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html))
+## Installation
 
-### Building
+```bash
+npm install @chainstream-io/sdk
+```
+
+or
 
-To build and compile the typescript sources to javascript use:
+```bash
+yarn add @chainstream-io/sdk
 ```
-npm install
-npm run build
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+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);
 ```
 
-### Publishing
+### Using Token Provider
 
-First build the package then run `npm publish`
+For dynamic token management:
 
-### Consuming
+```typescript
+import { DexClient, TokenProvider } from '@chainstream-io/sdk';
 
-navigate to the folder of your consuming project and run one of the following commands.
+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());
+```
 
-_published:_
+### Custom Configuration
 
+```typescript
+const client = new DexClient('your-access-token', {
+  serverUrl: 'https://api-dex.chainstream.io',
+  streamUrl: 'wss://realtime-dex.chainstream.io/connection/websocket',
+  debug: true
+});
 ```
-npm install @chainstream-io/sdk@0.1.10 --save
+
+## 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:
+
+```typescript
+// 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();
 ```
 
-_unPublished (not recommended):_
+### Batch Subscriptions
+
+For efficient bulk operations:
 
+```typescript
+// 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);
 ```
-npm install PATH_TO_GENERATED_PACKAGE --save
+
+## Job Management
+
+For long-running operations, use the job system:
+
+```typescript
+// 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
+
+```typescript
+const tokens = await client.token.listTokens({
+  chain: 'solana',
+  limit: 20,
+  offset: 0
+});
+
+console.log(`Found ${tokens.data.length} tokens`);
+```
+
+### Get Swap Quote
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+const balance = await client.wallet.getWalletBalances({
+  chain: 'solana',
+  address: 'wallet-address'
+});
+
+console.log('Wallet balances:', balance.balances);
+```
+
+### Get Wallet PnL
+
+```typescript
+const pnl = await client.wallet.getWalletPnl({
+  chain: 'solana',
+  address: 'wallet-address'
+});
+
+console.log('Wallet PnL:', pnl);
+```
+
+### Create Red Packet
+
+```typescript
+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
+
+```typescript
+const file = new File(['content'], 'filename.txt');
+const ipfsResult = await client.ipfs.uploadFile({
+  file: file
+});
+
+console.log('IPFS hash:', ipfsResult.hash);
+```
+
+### Get Token Rankings
+
+```typescript
+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](https://github.com/chainstream-io/openapi-sdk-generator).