👨‍💻API Integration for Devs.

SignalMagic offers a robust API for developers who want to integrate our signals into their own trading systems:

### REST API Documentation

```
BASE URL: https://api.signalmagic.ai/v1
```

<details>
<summary><strong>Authentication</strong></summary>

```
Authorization: Bearer YOUR_API_KEY
```

Generate your API key from: **Dashboard > Settings > API Access**
</details>

<details>
<summary><strong>Endpoints</strong></summary>

**Get Latest Signals**
```
GET /signals/latest
```
Parameters:
- `asset`: Filter by specific asset (optional)
- `confidence`: Minimum confidence score (optional)
- `limit`: Number of signals to return (default: 10)

**Get Signal by ID**
```
GET /signals/{signal_id}
```

**Get Account Positions**
```
GET /positions
```
Parameters:
- `status`: open, closed, all (default: open)
- `asset`: Filter by specific asset (optional)

**Place Order**
```
POST /orders
```
Body:
```json
{
  "signal_id": "sig_123456",
  "exchange": "binance",
  "position_size": "10%", // or specific amount
  "entry_type": "market", // or "limit"
  "stop_loss_type": "fixed", // or "trailing"
  "take_profit_levels": [
    { "price": 45000, "percentage": 25 },
    { "price": 47000, "percentage": 50 },
    { "price": 50000, "percentage": 25 }
  ]
}
```
</details>

### WebSocket API

Connect to our WebSocket API for real-time signal updates:

```
wss://api.signalmagic.ai/v1/ws
```

#### Events:

- `signal`: New trading signal generated
- `signal_update`: Updates to existing signal
- `position_update`: Changes in your open positions
- `market_alert`: Critical market condition alerts

### Code Examples

<details>
<summary><strong>Python Integration Example</strong></summary>

```python
import requests
import json
import hmac
import hashlib
import time

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL = "https://api.signalmagic.ai/v1"

def get_signature(query_string):
    return hmac.new(
        API_SECRET.encode('utf-8'),
        query_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

def get_latest_signals(asset=None, confidence=None, limit=10):
    endpoint = "/signals/latest"
    timestamp = int(time.time() * 1000)
    params = f"timestamp={timestamp}&limit={limit}"
    
    if asset:
        params += f"&asset={asset}"
    if confidence:
        params += f"&confidence={confidence}"
        
    signature = get_signature(params)
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "X-SM-SIGNATURE": signature
    }
    
    response = requests.get(
        f"{BASE_URL}{endpoint}?{params}",
        headers=headers
    )
    
    return response.json()

def place_order(signal_id, exchange, position_size, entry_type="market", 
                stop_loss_type="fixed", take_profit_levels=None):
    endpoint = "/orders"
    timestamp = int(time.time() * 1000)
    
    payload = {
        "signal_id": signal_id,
        "exchange": exchange,
        "position_size": position_size,
        "entry_type": entry_type,
        "stop_loss_type": stop_loss_type,
        "timestamp": timestamp
    }
    
    if take_profit_levels:
        payload["take_profit_levels"] = take_profit_levels
        
    payload_str = json.dumps(payload)
    signature = get_signature(payload_str)
    
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "X-SM-SIGNATURE": signature,
        "Content-Type": "application/json"
    }
    
    response = requests.post(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        data=payload_str
    )
    
    return response.json()

# Example usage
if __name__ == "__main__":
    # Get latest Bitcoin signals with at least 80% confidence
    btc_signals = get_latest_signals(asset="BTC-USDT", confidence=80)
    
    # Place an order based on the first signal
    if btc_signals["signals"]:
        signal = btc_signals["signals"][0]
        order = place_order(
            signal_id=signal["id"],
            exchange="binance",
            position_size="5%",
            take_profit_levels=[
                {"price": signal["take_profit_1"], "percentage": 50},
                {"price": signal["take_profit_2"], "percentage": 50}
            ]
        )
        print(f"Order placed: {order}")
```
</details>

<details>
<summary><strong>Node.js Integration Example</strong></summary>

```javascript
const axios = require('axios');
const crypto = require('crypto');
const WebSocket = require('ws');

const API_KEY = 'your_api_key';
const API_SECRET = 'your_api_secret';
const BASE_URL = 'https://api.signalmagic.ai/v1';

// Generate signature for API authentication
function generateSignature(queryString) {
  return crypto
    .createHmac('sha256', API_SECRET)
    .update(queryString)
    .digest('hex');
}

// Get latest trading signals
async function getLatestSignals(asset = null, confidence = null, limit = 10) {
  const headers = authenticate();
  const url = 'https://api.signalmagic.ai/v1/signals';
  
  const params = new URLSearchParams({
    limit: 10,
    confidence: 80,
    pairs: 'BTC-USDT,ETH-USDT,SOL-USDT'
  });
  
  try {
    const response = await fetch(`${url}?${params}`, { headers });
    if (response.ok) {
      return await response.json();
    } else {
      throw new Error(`API request failed: ${await response.text()}`);
    }
  } catch (error) {
    console.error('Error fetching signals:', error);
    throw error;
  }
}

// Place trading order based on signal
async function placeOrder(signalId, exchange, positionSize, entryType = 'market', 
                          stopLossType = 'fixed', takeProfitLevels = null) {
  const endpoint = '/orders';
  const timestamp = Date.now();
  
  const payload = {
    signal_id: signalId,
    exchange: exchange,
    position_size: positionSize,
    entry_type: entryType,
    stop_loss_type: stopLossType,
    timestamp: timestamp
  };
  
  if (takeProfitLevels) {
    payload.take_profit_levels = takeProfitLevels;
  }
  
  const payloadStr = JSON.stringify(payload);
  const signature = generateSignature(payloadStr);
  
  try {
    const response = await axios.post(`${BASE_URL}${endpoint}`, payload, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'X-SM-SIGNATURE': signature,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error placing order:', error.response?.data || error.message);
    throw error;
  }
}

// Connect to WebSocket for real-time updates
function connectToSignalStream(onSignal, onPositionUpdate) {
  const timestamp = Date.now();
  const signature = generateSignature(`timestamp=${timestamp}`);
  
  const ws = new WebSocket(`wss://api.signalmagic.ai/v1/ws?timestamp=${timestamp}&signature=${signature}`);
  
  ws.on('open', () => {
    console.log('Connected to SignalMagic WebSocket');
    ws.send(JSON.stringify({
      action: 'authenticate',
      api_key: API_KEY
    }));
  });
  
  ws.on('message', (data) => {
    const message = JSON.parse(data);
    
    switch (message.event) {
      case 'signal':
        onSignal(message.data);
        break;
      case 'position_update':
        onPositionUpdate(message.data);
        break;
      case 'auth_success':
        console.log('Authentication successful');
        break;
      case 'error':
        console.error('WebSocket error:', message.message);
        break;
    }
  });
  
  ws.on('error', (error) => {
    console.error('WebSocket connection error:', error);
  });
  
  ws.on('close', () => {
    console.log('WebSocket connection closed, reconnecting...');
    setTimeout(() => connectToSignalStream(onSignal, onPositionUpdate), 5000);
  });
  
  return ws;
}

// Example usage
async function main() {
  try {
    // Get latest Ethereum signals with at least 85% confidence
    const ethSignals = await getLatestSignals('ETH-USDT', 85);
    console.log('Latest ETH signals:', ethSignals);
    
    // Place an order based on the first signal
    if (ethSignals.signals && ethSignals.signals.length > 0) {
      const signal = ethSignals.signals[0];
      const order = await placeOrder(
        signal.id,
        'kraken',
        '3%',
        'limit',
        'trailing',
        [
          { price: signal.take_profit_1, percentage: 30 },
          { price: signal.take_profit_2, percentage: 40 },
          { price: signal.take_profit_3, percentage: 30 }
        ]
      );
      console.log('Order placed:', order);
    }
    
    // Connect to real-time signal stream
    connectToSignalStream(
      (signal) => console.log('New signal received:', signal),
      (position) => console.log('Position update:', position)
    );
  } catch (error) {
    console.error('Error:', error);
  }
}

main();
```
</details>