API Overview

Ballast provides REST and WebSocket APIs for programmatic trading, market data access, and account management.

Base URLs

Environment	REST API	WebSocket
Production	https://api.ballastmarkets.com/v1	wss://stream.ballastmarkets.com
Sandbox	https://api-sandbox.ballastmarkets.com/v1	wss://stream-sandbox.ballastmarkets.com

Authentication

All API requests require authentication via API keys generated in your account dashboard.

API Key Format

API Key: bmkt_live_abc123...
API Secret: bmkt_secret_xyz789...

Authentication Header

Authorization: Bearer <API_KEY>
X-BM-Signature: <HMAC-SHA256 signature>
X-BM-Timestamp: <Unix timestamp in milliseconds>

Signature Generation (Python)

import hmac
import hashlib
import time

def sign_request(secret, method, path, body=""):
    timestamp = str(int(time.time() * 1000))
    message = f"{timestamp}{method}{path}{body}"
    signature = hmac.new(
        secret.encode(), 
        message.encode(), 
        hashlib.sha256
    ).hexdigest()
    return signature, timestamp

---

Rate Limits

Endpoint Type	Limit	Window
Public (market data)	100 req/min	Per IP
Private (trading)	300 req/min	Per API key
WebSocket connections	5 simultaneous	Per API key

Rate Limit Headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1678901234

---

Core Endpoints

Market Data (Public)

Get All Markets

GET /markets

Response:

{
  "markets": [
    {
      "id": "suez-apr2025",
      "name": "Suez Canal Availability - April 2025",
      "type": "binary",
      "settlement_date": "2025-04-30T23:59:00Z",
      "last_price": 0.87,
      "bid": 0.865,
      "ask": 0.875,
      "volume_24h": 125000
    }
  ]
}

Get Market Details

GET /markets/{market_id}

Get Order Book

GET /markets/{market_id}/orderbook?depth=20

Response:

{
  "market_id": "suez-apr2025",
  "timestamp": "2025-03-15T10:30:00Z",
  "bids": [
    {"price": 0.865, "size": 5000},
    {"price": 0.860, "size": 12000}
  ],
  "asks": [
    {"price": 0.875, "size": 3000},
    {"price": 0.880, "size": 8000}
  ]
}

---

Trading (Private)

Place Order

POST /orders
Content-Type: application/json

{
  "market_id": "suez-apr2025",
  "side": "buy",
  "type": "limit",
  "price": 0.870,
  "size": 1000,
  "time_in_force": "GTC"
}

Response:

{
  "order_id": "ord_abc123",
  "status": "open",
  "filled_size": 0,
  "remaining_size": 1000,
  "created_at": "2025-03-15T10:31:05Z"
}

Cancel Order

DELETE /orders/{order_id}

Get Open Orders

GET /orders?status=open

Get Order History

GET /orders?start_date=2025-03-01&end_date=2025-03-15

---

Account Management (Private)

Get Account Balance

GET /account/balance

Response:

{
  "total_balance": 50000.00,
  "available": 42000.00,
  "reserved": 8000.00,
  "currency": "USDC"
}

Get Positions

GET /positions

Response:

{
  "positions": [
    {
      "market_id": "suez-apr2025",
      "size": 5000,
      "average_price": 0.85,
      "current_price": 0.87,
      "unrealized_pnl": 100.00,
      "margin_used": 500.00
    }
  ]
}

---

Error Handling

Standard Error Response

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient collateral for this order",
    "details": {
      "required": 1000.00,
      "available": 850.00
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
INVALID_SIGNATURE	401	Authentication signature invalid
RATE_LIMIT_EXCEEDED	429	Too many requests
MARKET_NOT_FOUND	404	Market ID does not exist
INSUFFICIENT_BALANCE	400	Not enough collateral
ORDER_SIZE_TOO_SMALL	400	Below minimum order size
POSITION_LIMIT_EXCEEDED	400	Exceeds max position for market

---

SDK Support

Official SDKs

• Python: pip install ballast-markets
• TypeScript: npm install @ballast/sdk
• Go: Coming Q3 2025

Example (Python SDK)

from ballast import BallastClient

client = BallastClient(
    api_key="bmkt_live_abc123",
    api_secret="bmkt_secret_xyz789"
)

# Get markets
markets = client.get_markets()

# Place order
order = client.place_order(
    market_id="suez-apr2025",
    side="buy",
    order_type="limit",
    price=0.87,
    size=1000
)

print(f"Order placed: {order.id}")

---

Next Steps

• Authentication Guide
• WebSocket Streaming
• SDK Documentation

Questions? Join our Discord or email api@ballastmarkets.com