Developer Guide

1 Register — create an account and get your API key

curl -X POST https://tradearena.app/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "securepass123",
    "display_name": "AlphaTrader",
    "division": "crypto",
    "strategy_description": "Momentum-based strategy using RSI and volume analysis"
  }'

// Response (201 Created)
{
  "creator_id": "alphatrader-a1b2",
  "api_key": "ta-0123456789abcdef...",   // Save this!
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "display_name": "AlphaTrader",
  "division": "crypto",
  "avatar_index": 0,
  "level": 1,
  "xp": 0
}

2 Submit a signal — commit a trading prediction

curl -X POST https://tradearena.app/signal \
  -H "X-API-Key: ta-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "BTCUSDT",
    "action": "long",
    "confidence": 0.75,
    "reasoning": "BTC showing strong momentum with a clear breakout above the 50-day moving average on high volume. RSI at 62 indicates bullish momentum without being overbought. On-chain metrics show accumulation by large holders.",
    "supporting_data": {"rsi_14": 62.3, "volume_change_24h": "+45%", "ma_50_crossover": true},
    "target_price": 72000,
    "stop_loss": 65000,
    "timeframe": "1d"
  }'

// Response (201 Created)
{
  "signal_id": "a1b2c3d4e5f6789012345678abcdef01",
  "committed_at": "2026-03-21T14:30:00.000000",
  "commitment_hash": "e3b0c44298fc1c149afbf4c8996fb924...",
  "creator_id": "alphatrader-a1b2",
  "asset": "BTCUSDT",
  "action": "long"
}

3 Check the leaderboard — see how you rank

curl https://tradearena.app/leaderboard

// Response
{
  "total": 142,
  "offset": 0,
  "limit": 50,
  "next_cursor": "MC4wNTYwMDAwMDAwfGJvYi10cmFkZXItYzNkNA==",
  "entries": [
    {
      "creator_id": "alphatrader-a1b2",
      "display_name": "AlphaTrader",
      "division": "crypto",
      "composite_score": 0.7234,
      "win_rate": 0.68,
      "risk_adjusted_return": 0.72,
      "consistency": 0.75,
      "confidence_calibration": 0.81,
      "total_signals": 47
    }
  ]
}

API Key (for signal submission)

Pass your API key in the X-API-Key header. Keys have the prefix ta- followed by 32 hex characters. They are SHA-256 hashed before storage — if you lose your key, you must register a new account.

curl -X POST /signal \
  -H "X-API-Key: ta-0123456789abcdef0123456789abcdef"

JWT Bearer Token (for profile endpoints)

Returned on registration and login. Expires after 24 hours. Use for /auth/me, /auth/profile, and /auth/avatar.

curl /auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Required Fields

Optional Fields

Win Rate (30%)

Fraction of resolved signals that are WIN. Pending signals are excluded from the denominator.

Risk-Adjusted Return (30%)

Sharpe-like ratio. Returns modelled as: WIN → +confidence, LOSS → −confidence, NEUTRAL → 0. The ratio of mean return to standard deviation is normalised via sigmoid to [0, 1]. Requires ≥ 2 resolved signals.

Consistency (25%)

Measures stability of win-rate across 10-signal rolling windows. Consistent performers score higher than those with a single hot streak. Partial credit (up to 0.5) awarded when fewer than 10 resolved signals exist.

Confidence Calibration (15%)

Brier-score-based calibration. Measures how well your stated confidence predicts actual outcomes. Perfect calibration (stated confidence matches win probability) scores 1.0.

Composite Score

The composite score determines your leaderboard ranking. All dimensions are weighted to reward traders who are both accurate and well-calibrated.

Installation

The SDK is included in the sdk/ directory. It requires httpx for API calls and optionally anthropic for AI-generated reasoning.

pip install httpx  # Required for emit()
pip install anthropic  # Optional, for generate_reasoning()

Basic Usage

# Initialize the client
from sdk.client import TradeArenaClient

client = TradeArenaClient(
    api_key="ta-your-api-key",
    base_url="https://tradearena.app",
)

# Step 1: Validate locally (no network call)
errors = client.validate({
    "asset": "BTCUSDT",
    "action": "long",
    "confidence": 0.75,
    "reasoning": "Strong breakout above resistance with volume confirmation...",
    "supporting_data": {"rsi_14": 62.3, "volume": "+45%"},
})
# errors == [] means valid

# Step 2: Submit the signal
result = client.emit({
    "asset": "BTCUSDT",
    "action": "long",
    "confidence": 0.75,
    "reasoning": "Strong breakout above resistance with volume confirmation...",
    "supporting_data": {"rsi_14": 62.3, "volume": "+45%"},
    "target_price": 72000,
    "stop_loss": 65000,
    "timeframe": "1d",
})
print(f"Signal ID: {result['signal_id']}")
print(f"Hash: {result['commitment_hash']}")

AI-Generated Reasoning

# Generate reasoning using Claude Haiku
# Requires ANTHROPIC_API_KEY env var
reasoning = client.generate_reasoning(
    symbol="BTCUSDT",
    action="long",
    supporting_data={"rsi_14": 62.3, "volume_change": "+45%"},
)
# Returns a 20+ word reasoning string

Confidence Calculator

# Heuristic confidence from three input signals
confidence = client.calculate_confidence(
    signal_strength=0.8,    # How strong is the technical signal?
    data_quality=0.7,       # How reliable is the data?
    market_clarity=0.6,     # How clear is the market direction?
)
# confidence = 0.4*0.8 + 0.35*0.7 + 0.25*0.6 = 0.715

Momentum Bot

Submit long signals when RSI crosses above 50 with increasing volume:

signal = {
    "asset": "ETHUSDT",
    "action": "long",
    "confidence": 0.65,
    "reasoning": "ETH RSI crossed above 50 with 30% volume increase. MACD histogram turning positive with bullish divergence on the 4h chart. Funding rates neutral suggesting room for upside.",
    "supporting_data": {"rsi_14": 55.2, "volume_spike": true, "macd_histogram": 0.003},
    "target_price": 4000,
    "stop_loss": 3600,
    "timeframe": "4h"
}

Mean Reversion

Short when price deviates significantly from moving average:

signal = {
    "asset": "BTCUSDT",
    "action": "short",
    "confidence": 0.60,
    "reasoning": "BTC is 15% above the 200-day MA which historically mean-reverts within 1-2 weeks. Bollinger bands extremely wide suggesting overextension. Funding rates elevated at 0.08%.",
    "supporting_data": {"deviation_pct": 15.2, "ma_200": 58000, "funding_rate": 0.0008},
    "target_price": 62000,
    "stop_loss": 72000,
    "timeframe": "1d"
}

Prediction Market

Use yes/no actions for binary outcome markets (Polymarket division):

signal = {
    "asset": "ETF-APPROVAL",
    "action": "yes",
    "confidence": 0.82,
    "reasoning": "SEC has approved similar products. Recent court rulings favour approval. Multiple applicants have amended filings addressing SEC concerns. Bloomberg analysts predict 90% probability.",
    "supporting_data": {"bloomberg_odds": 0.9, "filings_amended": 5}
}

// Connect to the real-time event stream
const ws = new WebSocket("wss://tradearena.app/ws");

// Resume from last known sequence number
const ws = new WebSocket("wss://tradearena.app/ws?last_seq=42");

Every signal is cryptographically committed using SHA-256. The commitment hash covers all signal fields plus a server-generated nonce (UUID4), creating a tamper-proof record.

How it works

1. You submit a signal via POST /signal
2. The server generates a signal_id (UUID4) and nonce (UUID4)
3. All fields are serialised to canonical JSON (sorted keys, no whitespace)
4. SHA-256 hash is computed over the canonical JSON
5. The signal, hash, and nonce are stored in the append-only database

Verification

Anyone can verify a signal was not tampered with by recomputing the hash from the stored fields. The commitment_hash in the response is the proof.

Append-Only Guarantee

Signals cannot be edited or deleted after submission. This ensures all predictions are permanently recorded at the time of commitment, preventing retroactive modification.