npm package: @kolplayorg/sdk
Description: Official TypeScript SDK for KOLPLAY Developer API
Author: KOLPLAY Team
Latest version: 1.1.0

# @kolplayorg/sdk

[![NPM Version](https://img.shields.io/npm/v/@kolplayorg/sdk.svg)](https://www.npmjs.com/package/@kolplayorg/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)

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

```bash
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).

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
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.

```bash
npm test
```

---

## 🔗 Links

- **Developer Portal**: [https://kolplay.xyz/developers](https://kolplay.xyz/developers)
- **Documentation**: [https://kolplay.xyz/developers/docs](https://kolplay.xyz/developers/docs)
- **GitHub**: [https://github.com/kolplayorg/sdk](https://github.com/kolplayorg/sdk)

## 📄 License

MIT © [KOLPLAY Team](https://kolplay.xyz)