# KlingEx JavaScript/TypeScript SDK

Official JavaScript/TypeScript SDK for the [KlingEx](https://klingex.io) cryptocurrency exchange API.

## Installation

```bash
npm install klingex
# or
yarn add klingex
# or
pnpm add klingex
```

## Quick Start

```typescript
import { KlingEx } from 'klingex';

// Initialize client with API key
const client = new KlingEx({
  apiKey: 'your-api-key-here'
});

// Get all markets
const markets = await client.markets.list();
console.log(markets);

// Get your balances
const balances = await client.wallet.balances();
console.log(balances);

// Place a limit order (human-readable values by default)
const order = await client.orders.submit({
  symbol: 'BTC-USDT',
  tradingPairId: 1,
  side: 'buy',
  quantity: '0.5',      // 0.5 BTC
  price: '50000.00'     // $50,000 per BTC
});
console.log(`Order placed: ${order.order_id}`);
```

## Configuration

```typescript
const client = new KlingEx({
  // Authentication (choose one)
  apiKey: 'your-api-key',      // API key authentication
  // jwt: 'your-jwt-token',    // Or JWT authentication

  // Optional settings
  baseUrl: 'https://api.klingex.io',  // API base URL
  wsUrl: 'wss://api.klingex.io/ws',   // WebSocket URL
  timeout: 30000,                      // Request timeout (ms)
  humanReadable: true,                 // Use human-readable values (default: true)
});
```

## API Reference

### Markets

```typescript
// Get all trading pairs
const markets = await client.markets.list();
for (const market of markets.slice(0, 5)) {
  console.log(`${market.base_asset_symbol}-${market.quote_asset_symbol}: ${market.last_price}`);
}

// Get 24h tickers (CMC format - uses underscore "BTC_USDT")
const tickers = await client.markets.tickers();
const btcTicker = await client.markets.ticker('BTC_USDT');
console.log(`BTC_USDT: ${btcTicker?.last_price}`);

// Get orderbook (marketId is a number)
const orderbook = await client.markets.orderbook(1);
console.log('Best bid:', orderbook.bids[0]);
console.log('Best ask:', orderbook.asks[0]);

// Get OHLCV (candlestick) data
const candles = await client.markets.ohlcv(1, '1h', { limit: 100 });

// Get recent trades (marketId is a number)
const trades = await client.markets.trades(1);
```

### Orders

```typescript
// Place a limit order
const order = await client.orders.submit({
  symbol: 'BTC-USDT',
  tradingPairId: 1,
  side: 'buy',
  quantity: '1.0',
  price: '50000.00'
});

// Convenience methods
await client.orders.limitBuy('BTC-USDT', 1, '1.0', '50000.00');
await client.orders.limitSell('BTC-USDT', 1, '1.0', '55000.00');
await client.orders.marketBuy('BTC-USDT', 1, '1.0', 0.01);  // 1% slippage
await client.orders.marketSell('BTC-USDT', 1, '1.0', 0.01);

// Get open orders
const orders = await client.orders.list();
const btcOrders = await client.orders.list({ tradingPairId: 1 });

// Cancel an order
await client.orders.cancel({
  orderId: 'order-uuid',
  tradingPairId: 1
});

// Cancel all orders for a trading pair
const result = await client.orders.cancelAll(1);
console.log(`Cancelled ${result.cancelledCount} orders`);

// Get order history
const history = await client.orders.history({ limit: 100 });
```

### Raw Values vs Human-Readable

By default, the SDK uses human-readable values (e.g., `"1.5"` for 1.5 BTC). To use raw base units:

```typescript
// Human-readable (default)
await client.orders.submit({
  symbol: 'BTC-USDT',
  tradingPairId: 1,
  side: 'buy',
  quantity: '1.5',      // 1.5 BTC
  price: '50000.00',    // $50,000
});

// Raw base units
await client.orders.submit({
  symbol: 'BTC-USDT',
  tradingPairId: 1,
  side: 'buy',
  quantity: '150000000',  // 1.5 BTC in satoshis (8 decimals)
  price: '5000000000',    // $50,000 in base units
  rawValues: true
});

// Or configure globally
const client = new KlingEx({
  apiKey: 'your-key',
  humanReadable: false  // Use raw values by default
});
```

### Wallet

```typescript
// Get all balances
const balances = await client.wallet.balances();

// Get specific balance
const btc = await client.wallet.balance('BTC');
console.log(`Available: ${btc?.human_available} BTC`);
```

### Invoices (Payment Processing)

```typescript
// Create invoice
const invoice = await client.invoices.create({
  amount: '100.00',
  asset: 'USDT',
  description: 'Order #12345',
  webhook_url: 'https://yoursite.com/webhook',
  expires_in: 60  // minutes
});

console.log(`Payment address: ${invoice.payment_address}`);
console.log(`Invoice URL: https://klingex.io/pay/${invoice.id}`);

// List invoices
const invoices = await client.invoices.list({ status: 'pending' });

// Check status
const status = await client.invoices.status(invoice.id);

// Cancel
await client.invoices.cancel(invoice.id);

// Get PDF
const pdf = await client.invoices.pdf(invoice.id);
```

### WebSocket (Real-time Data)

```typescript
// Connect to WebSocket
await client.ws.connect();

// Subscribe to orderbook updates
const unsubOrderbook = client.ws.orderbook('BTC-USDT', (data) => {
  console.log('Orderbook update:', data);
});

// Subscribe to trades
const unsubTrades = client.ws.trades('BTC-USDT', (data) => {
  console.log('New trade:', data);
});

// Subscribe to ticker
client.ws.ticker('BTC-USDT', (ticker) => {
  console.log(`Price: ${ticker.last_price}`);
});

// User-specific channels (requires auth)
client.ws.userOrders((order) => {
  console.log('Order update:', order);
});

client.ws.userBalances((balance) => {
  console.log('Balance update:', balance);
});

// Handle errors
client.ws.onError((error) => {
  console.error('WebSocket error:', error);
});

// Unsubscribe
unsubOrderbook();
unsubTrades();

// Disconnect
client.ws.disconnect();
```

## Error Handling

```typescript
import {
  KlingEx,
  KlingExError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  InsufficientFundsError
} from 'klingex';

try {
  await client.orders.submit({ /* ... */ });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof InsufficientFundsError) {
    console.error('Not enough balance');
  } else if (error instanceof ValidationError) {
    console.error('Invalid parameters:', error.details);
  } else if (error instanceof KlingExError) {
    console.error(`API error: ${error.message} (${error.code})`);
  }
}
```

## TypeScript Support

Full TypeScript support with type definitions included:

```typescript
import type {
  Market,
  Order,
  Balance,
  Ticker,
  Orderbook,
  SubmitOrderParams
} from 'klingex';

const params: SubmitOrderParams = {
  symbol: 'BTC-USDT',
  tradingPairId: 1,
  side: 'buy',
  quantity: '1.0',
  price: '50000.00'
};
```

## Browser Support

The SDK works in both Node.js and browsers. For browsers, make sure you have a WebSocket polyfill if needed.

```html
<script type="module">
  import { KlingEx } from 'https://unpkg.com/klingex/dist/index.mjs';

  const client = new KlingEx({ apiKey: 'your-key' });
  const markets = await client.markets.list();
</script>
```

## License

MIT

## Support

- Documentation: https://klingex.io/support/api-docs
- Issues: https://github.com/Klingon-tech/klingex-js/issues
- Email: support@klingex.io