cipher-ai

TypeScript SDK for the CIPHER trading engine REST API.

Installation

npm install cipher-ai

Quick Start

import { CipherClient } from 'cipher-ai';

const client = new CipherClient({
  baseUrl: 'http://localhost:8000',
  apiKey: 'cipher_sk_your_api_key'
});

// Create a trading signal
const signal = await client.createSignal({
  symbol: 'BTC',
  model_version: 1
});

console.log(signal.signal); // 'BUY', 'SELL', or 'HOLD'
console.log(signal.confidence); // 0.85

API Reference

Constructor

const client = new CipherClient(options?: CipherClientOptions);

Options:

• baseUrl (optional): API base URL. Default: http://localhost:8000
• apiKey (optional): API key for authentication

Trading Endpoints

createSignal

Create a trading signal.

const signal = await client.createSignal({
  symbol: 'BTC',
  model_version: 1
});

// Returns: SignalResponse
// {
//   symbol: 'BTC',
//   signal: 'BUY',
//   confidence: 0.85,
//   price: 45000,
//   timestamp: '2024-01-01T00:00:00Z',
//   model_version: 1,
//   model_episode: 10,
//   reasoning: ['Strong uptrend'],
//   knowledge_context: ['Market analysis']
// }

getStatus

Get system status.

const status = await client.getStatus();

// Returns: StatusResponse
// {
//   model: 'LSTM',
//   status: 'running',
//   latest_model_version: 5,
//   min_model_version: 1,
//   episode: 100,
//   win_rate: 0.75,
//   balance: 10000,
//   total_return: 0.25,
//   last_trained: '2024-01-01T00:00:00Z',
//   knowledge_chunks: 50,
//   uptime_hours: 24
// }

getPerformance

Get performance metrics.

const performance = await client.getPerformance();

// Returns: PerformanceResponse
// {
//   total_return_pct: 25.5,
//   win_rate: 0.75,
//   sharpe_ratio: 1.5,
//   max_drawdown_pct: 5.2,
//   total_trades: 100,
//   avg_trade_duration_hours: 2.5,
//   knowledge_usage_rate: 0.8
// }

getHistory

Get trade history.

const history = await client.getHistory(20);

// Returns: HistoryResponse
// {
//   trades: [
//     {
//       symbol: 'BTC',
//       signal: 'BUY',
//       confidence: 0.85,
//       price: 45000,
//       timestamp: '2024-01-01T00:00:00Z',
//       model_version: 1,
//       model_episode: 10,
//       pnl: 100
//     }
//   ],
//   count: 1
// }

getModels

Get model versions.

const models = await client.getModels();

// Returns: ModelsResponse
// {
//   min_version: 1,
//   latest_version: 5,
//   versions: [
//     {
//       version: 5,
//       episode: 100,
//       win_rate: 0.75,
//       timestamp: '2024-01-01T00:00:00Z',
//       active: true
//     }
//   ]
// }

getModelStatus

Get model status (no authentication required).

const modelStatus = await client.getModelStatus();

// Returns: ModelStatusResponse
// {
//   episode: 100,
//   timestamp: '2024-01-01T00:00:00Z',
//   running: true,
//   cumulative_pnl: 1000,
//   best_pnl: 1500,
//   win_rate: 0.75,
//   best_win_rate: 0.8,
//   total_wins: 75,
//   total_losses: 25,
//   symbol: 'BTC',
//   symbols: ['BTC', 'ETH'],
//   lstm_loss: 0.05
// }

API Key Management

getKeyUsage

Get API key usage statistics.

const usage = await client.getKeyUsage(
  '[email protected]',
  'your_admin_secret',
  30 // days (optional, default: 30)
);

// Returns: KeyUsageResponse
// {
//   usage: [
//     {
//       key_hash: 'abc123...',
//       requests: 150,
//       last_used: '2024-01-01T00:00:00Z'
//     }
//   ],
//   days: 30
// }

Error Handling

All API methods throw a CipherError on non-2xx responses.

import { CipherClient, CipherError } from 'cipher-ai';

try {
  const signal = await client.createSignal({
    symbol: 'BTC',
    model_version: 1
  });
} catch (error) {
  if (error instanceof CipherError) {
    console.error('Status:', error.status);
    console.error('Message:', error.message);
    
    if (error.status === 401) {
      console.error('Invalid API key');
    } else if (error.status === 429) {
      console.error('Rate limit exceeded');
    }
  }
}

Development

Setup

# Clone the repository
git clone https://github.com/getcipherAI/cipher-ai.git
cd cipher-ai

# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

Scripts

• npm run build - Build the package (CJS + ESM)
• npm test - Run tests in watch mode
• npm run test:run - Run tests once
• npm run typecheck - Type-check without emitting files

Requirements

• Node.js >= 18
• TypeScript 5.3+

License

MIT