@kolplayorg/sdk

The official TypeScript SDK for the KOLPLAY Developer API. Build high-performance trading tools, social mindmaps, and AI-powered autonomous agents on the Solana blockchain.

🚀 Features

• Isomorphic Support: Seamlessly transitions between Node.js, modern browsers, and Edge runtimes.
• Full Type Safety: Comprehensive TypeScript interfaces for all metrics, trades, and social data.
• Flexible Auth: Support for both developer API Keys and user-facing JWT Bearer Tokens.
• Real-time Streaming: Built-in Socket.IO management for live KOL trade feeds and mindmap shifts.
• Enterprise Ready: Automatic retries, error handling, and optimized bundle sizes.

📦 Installation

npm install @kolplayorg/sdk
# or
yarn add @kolplayorg/sdk

🛠 Quick Start

1. Initialize the Client

You can initialize with a plain API Key or a configuration object (useful for JWT/Agents).

import { KolplayClient } from '@kolplayorg/sdk';

// Option A: Standard API Key
const client = new KolplayClient('sk_live_your_key_here');

// Option B: JWT (for AI Agents or Frontend sessions)
const agentClient = new KolplayClient({ 
  jwt: 'your_user_jwt_token',
  baseUrl: 'https://vps.kolplay.xyz/api/v1' 
});

2. Fetch On-Chain Insights

// Get real-time metrics for a Solana token
const metrics = await client.getTokenMetrics('So11111111111111111111111111111111111111112');
console.log(`Price: ${metrics.price} SOL | Liquidity: $${metrics.liquidity}`);

// Get social mindmap (KOL involvement)
const mindmap = await client.getTokenMindmap('So111...');
console.log(`Social Centrality: ${mindmap.networkMetrics.centrality}`);

3. Execute Trades

// Execute a high-speed swap (supports simulation)
const trade = await client.executeSwap({
  mint: 'So111...',
  amount: 0.1,
  tradeType: 'buy',
  slippage: 15, // 15%
  isSimulation: true
});

console.log(`Trade Status: ${trade.status} | ID: ${trade.tradeId}`);

4. Real-time Subscriptions

const socket = client.connectWebSocket();

// Listen for global KOL trade updates
client.subscribeToKOLTrades((update) => {
  console.log(`KOL ${update.trade.kolId} just bought ${update.trade.mint}`);
});

📚 API Reference

| Module | Method | Description | | :--- | :--- | :--- | | Tokens | getTokenMetrics(mint) | Real-time price, liquidity, and supply data. | | | getTokenMindmap(mint) | Social influence network and KOL connections. | | | predictTokens(mints[]) | AI-powered win probability for token addresses. | | KOLs | getFeaturedKols() | List of high-performing traders currently featured. | | | getLeaderboard(limit) | Top traders ranked by PnL and Win Rate. | | Trades | executeSwap(params) | Execute buy/sell orders via KOLPLAY engine. | | | getTradeHistory(limit) | Global feed of recent high-value trades. | | User | getUserStats() | Personal PnL, Win Rate, and Volume analytics. | | | getUserTrades(filter)| Filterable history of your own trades. |

🧪 Testing

The SDK is fully tested with Vitest.

npm test

🔗 Links

• Developer Portal: https://kolplay.xyz/developers
• Documentation: https://kolplay.xyz/developers/docs
• GitHub: https://github.com/kolplayorg/sdk

📄 License

MIT © KOLPLAY Team