API REFERENCE

Kerosyne API v1.0

RESTful API for programmatic access to Kerosyne trading platform.

Base URL:https://api.kerosyne.trade/v1

Authentication

All API requests require authentication using API keys. Generate keys from your dashboard under Settings → API Keys.

API Key Authentication

Include your API key in the X-API-Key header.

curl -X GET https://api.kerosyne.trade/v1/positions \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json"

Security Best Practices

• Never expose API keys in client-side code
• Rotate keys regularly
• Use environment variables for key storage
• Revoke unused keys immediately

Rate Limits

Tier	Requests/min	Burst
Starter	60	10
Pro	120	20
Pro+	300	50

Rate limit headers are included in all responses:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Endpoints

GET/positions

List all active positions across exchanges.

Query Parameters

Parameter	Type	Description
exchange	string	Filter by exchange ID
status	string	open \| closed \| all
limit	integer	Max results (default: 50)

Response

{
  "positions": [
    {
      "id": "pos_abc123",
      "exchange": "binance",
      "symbol": "BTC/USDT",
      "side": "long",
      "entry_price": 45000.00,
      "current_price": 46200.00,
      "quantity": 0.5,
      "unrealized_pnl": 600.00,
      "stop_loss": 44000.00,
      "take_profit": 48000.00,
      "status": "open",
      "created_at": "2026-02-06T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

POST/positions

Create a new position. Subject to Cerberus validation.

Request Body

{
  "exchange": "binance",
  "symbol": "BTC/USDT",
  "side": "long",
  "entry_price": 45000.00,
  "quantity": 0.5,
  "stop_loss": 44000.00,
  "take_profit": 48000.00,
  "strategy_id": "strat_xyz789"  // optional
}

Response (201 Created)

{
  "position": {
    "id": "pos_abc123",
    "status": "pending_validation",
    "validation": {
      "cerberus_status": "validating",
      "checks": [
        "position_size",
        "exposure_limit",
        "daily_loss_limit"
      ]
    }
  }
}

GET/strategies

List all strategies.

Response

{
  "strategies": [
    {
      "id": "strat_xyz789",
      "name": "BTC Grid Strategy",
      "type": "grid",
      "status": "active",
      "exchange": "binance",
      "symbol": "BTC/USDT",
      "config": {
        "grid_levels": 10,
        "price_range": [44000, 48000],
        "quantity_per_level": 0.01
      },
      "performance": {
        "total_pnl": 1250.00,
        "win_rate": 0.68,
        "trades": 45
      },
      "created_at": "2026-01-15T08:00:00Z"
    }
  ]
}

POST/strategies

Create and deploy a new strategy.

Request Body

{
  "name": "BTC Grid Strategy",
  "type": "grid",
  "exchange": "binance",
  "symbol": "BTC/USDT",
  "config": {
    "grid_levels": 10,
    "price_range": [44000, 48000],
    "quantity_per_level": 0.01
  },
  "risk_limits": {
    "max_position_size": 5000.00,
    "max_daily_loss": 500.00,
    "stop_loss_pct": 0.02
  }
}

GET/risk/envelope

Get current risk envelope and utilization.

Response

{
  "envelope": {
    "max_position_size": 10000.00,
    "max_exposure": 0.30,
    "max_daily_loss": 1000.00,
    "max_concurrent_positions": 10
  },
  "current": {
    "total_exposure": 0.18,
    "daily_loss": -120.00,
    "active_positions": 5,
    "available_capital": 28000.00
  },
  "status": "ok"
}

POST/emergency/kill

Trigger Charon emergency exit. Closes all positions and halts all strategies.

Request Body

{
  "reason": "Market volatility",
  "confirm": true
}

Response (202 Accepted)

{
  "status": "executing",
  "positions_closing": 5,
  "strategies_halting": 2,
  "estimated_completion": "2026-02-06T10:35:00Z"
}

Webhooks

Configure webhooks to receive real-time notifications for position updates, strategy events, and risk alerts.

Webhook Events

position.openedPosition successfully opened

position.closedPosition closed (stop/target hit)

strategy.startedStrategy activated

strategy.stoppedStrategy halted

risk.limit_reachedRisk limit threshold reached

emergency.kill_triggeredCharon emergency exit activated

Webhook Payload Example

{
  "event": "position.opened",
  "timestamp": "2026-02-06T10:30:00Z",
  "data": {
    "position_id": "pos_abc123",
    "exchange": "binance",
    "symbol": "BTC/USDT",
    "side": "long",
    "entry_price": 45000.00,
    "quantity": 0.5
  }
}

Error Codes

Code	Message	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions
422	Validation Failed	Cerberus rejected request
429	Rate Limit Exceeded	Too many requests
500	Internal Server Error	Server-side error

Error Response Format

{
  "error": {
    "code": 422,
    "message": "Position validation failed",
    "details": {
      "reason": "Exceeds max position size",
      "limit": 10000.00,
      "requested": 15000.00
    }
  }
}

Code Examples

cURL

# List positions
curl -X GET https://api.kerosyne.trade/v1/positions \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json"

# Create position
curl -X POST https://api.kerosyne.trade/v1/positions \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"exchange":"binance","symbol":"BTC/USDT","side":"long","entry_price":45000,"quantity":0.5}'

JavaScript (Node.js)

const axios = require('axios');

const client = axios.create({baseURL: 'https://api.kerosyne.trade/v1',
headers: { 'X-API-Key': process.env.KEROSYNE_API_KEY }});

async function getPositions() {const response = await client.get('/positions');
return response.data.positions;
}
async function createPosition(data) {const response = await client.post('/positions', data);
return response.data.position;
}

Python

import requests
import os

class KerosyneClient:
def __init__(self, api_key):
self.base_url = "https://api.kerosyne.trade/v1"
self.headers = {
"X-API-Key": api_key,
"Content-Type": "application/json"
}

def get_positions(self, exchange=None):
params = {"exchange": exchange} if exchange else {}response = requests.get(
f"{self.base_url}/positions",
headers=self.headers,
params=params
)
return response.json()["positions"]

def create_position(self, data):
response = requests.post(
f"{self.base_url}/positions",
headers=self.headers,
json=data
)
return response.json()["position"]

# Usage
client = KerosyneClient(os.getenv("KEROSYNE_API_KEY"))
positions = client.get_positions()