skayn-trading-sdk/README.md

Professional Bitcoin trading strategy backtesting framework with institutional-grade architecture

# Skayn Trading SDK

Professional-grade Bitcoin trading strategy framework with institutional architecture. Battle-tested backtesting engine, production logging, and TypeScript support.

## Features

- ⚡ **Simple** - Working backtest in 30 seconds: `npm install` → `npx skayn example`
- 🏛️ **Professional** - Clean plugin architecture with proper interfaces
- ₿ **Bitcoin-First** - Optimized for Bitcoin momentum and swing strategies  
- 📊 **Battle-Tested** - Validated P&L calculations, realistic position management
- 🌐 **Real Market Data** - Direct Binance API integration for accurate backtests
- 🔓 **Production-Ready** - TypeScript, comprehensive logging, CLI tools

## Installation

```bash
npm install skayn-trading-sdk
```

## Quick Start (30 seconds)

```bash
npm install skayn-trading-sdk
npx skayn example     # Run demo backtest with real market data
npx skayn momentum    # Run momentum strategy demo
npx skayn --help      # Show all available commands
```

🇺🇸 **US Developers:** Enable VPN before running examples (Binance geoblocks US traffic)  
📊 **Data Source:** Uses real Bitcoin OHLCV data from Binance for professional-grade backtests  
⚠️ **Disclaimer:** Past performance does not guarantee future results - for educational purposes only  
⚡ **Setup Time:** 30 seconds

### If You Get API Errors
- **US users:** Enable VPN and retry for best experience  
- **Custom data:** Plug in your own high-quality OHLCV files using data provider plugins

```javascript
const { SDK } = require('skayn-trading-sdk');

// Create a simple moving average strategy
const myStrategy = SDK.strategy(async (data, portfolio) => {
  const prices = data.map(bar => bar.close);
  const sma20 = average(prices.slice(-20));
  const sma50 = average(prices.slice(-50));
  
  if (sma20 > sma50) {
    return { action: 'BUY', confidence: 0.8 };
  }
  return { action: 'SELL', confidence: 0.7 };
});

// Run a backtest
const results = await SDK.create()
  .strategy(myStrategy)
  .dataProvider(myDataProvider)
  .backtest({
    startDate: '2024-01-01',
    endDate: '2024-12-31',
    initialBalance: 10000
  });

console.log('Backtest Results:', results);
```

## Core Concepts

### Strategies
Implement your trading logic by extending the Strategy interface:

```javascript
const { Strategy } = require('skayn-trading-sdk');

class MyStrategy extends Strategy {
  async analyze(data, portfolio) {
    // Your trading logic here
    return {
      action: 'BUY',     // 'BUY', 'SELL', or 'HOLD'
      confidence: 0.85,   // 0-1 confidence score
      quantity: 0.001,    // BTC amount
      reasons: ['SMA crossover', 'RSI oversold']
    };
  }
}
```

### Data Providers
Connect any data source by implementing the DataProvider interface:

```javascript
const { DataProvider } = require('skayn-trading-sdk');

class MyDataProvider extends DataProvider {
  async getData(startDate, endDate, interval, symbol) {
    // Fetch and return OHLCV data
    return [{
      timestamp: 1234567890,
      open: 45000,
      high: 46000,
      low: 44500,
      close: 45500,
      volume: 100
    }];
  }
}
```

### Exchange Providers
Execute trades on any exchange by implementing the ExchangeProvider interface:

```javascript
const { ExchangeProvider } = require('skayn-trading-sdk');

class MyExchange extends ExchangeProvider {
  async executeSignal(signal, params) {
    // Execute the trade
    return {
      success: true,
      orderId: '12345',
      executedPrice: 45500
    };
  }
}
```

## Available Providers

Install additional providers as needed:

- `skayn-lnmarkets-provider` - Trade on LN Markets via Lightning
- `skayn-hyperliquid-provider` - Trade on Hyperliquid DEX
- `skayn-cryptoquant-provider` - On-chain data from CryptoQuant
- More coming soon...

## Advanced Usage

### Custom Backtest Engine

```javascript
const { BacktestEngine } = require('skayn-trading-sdk');

class MyBacktestEngine extends BacktestEngine {
  async runBacktest(config) {
    // Custom backtesting logic
  }
}

SDK.create()
  .backtestEngine(new MyBacktestEngine())
  .run();
```

### Live Trading

```javascript
const LNMarketsProvider = require('skayn-lnmarkets-provider');

SDK.create()
  .strategy(myStrategy)
  .exchange(new LNMarketsProvider({
    key: process.env.LN_MARKETS_KEY,
    secret: process.env.LN_MARKETS_SECRET
  }))
  .live({
    checkInterval: 60000,  // Check every minute
    maxPositionSize: 0.01  // Max 0.01 BTC
  });
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Support

- 🐛 [Issue Tracker](https://github.com/skayn-ai/skayn-trading-sdk/issues)

Built for the Bitcoin trading community