Quickstart

Get risk intelligence for your first trade in under 5 minutes.

1. Get an API Key

Request early access by emailing [email protected] with the subject line "Canon API Early Access". Include a brief description of your agent or use case.

You'll receive a Bearer token to authenticate requests.

2. Make Your First Request

curl -X POST https://api.canon.trade/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "ETH",
    "action": "long",
    "size": 50000,
    "leverage": 10,
    "wallet": "0x7a3b1234567890abcdef1234567890abcdef1234"
  }'

3. Read the Response

{
  "risk_score": 28,
  "recommendation": "proceed",
  "flags": [],
  "slippage": {
    "estimated_bps": 3.8,
    "fill_price": 3412.50
  },
  "liquidation": {
    "price": 2901.25,
    "distance_pct": 17.2,
    "margin_usage_pct": 42.1
  },
  "funding": {
    "rate_8h": 0.0012,
    "annualized_pct": 2.1,
    "direction": "longs_pay"
  },
  "meta": {
    "asset": "ETH",
    "mark_price": 3415.20,
    "latency_ms": 47,
    "request_id": "req_abc123"
  }
}

4. Act on It

Use the recommendation field to gate your agent's execution:

import requests

resp = requests.post(
    "https://api.canon.trade/v1/validate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "asset": "ETH",
        "action": "long",
        "size": 50_000,
        "leverage": 10,
        "wallet": "0x7a3b..."
    }
)
result = resp.json()

if result["recommendation"] == "proceed":
    # Execute the trade
    hl.market_open("ETH", True, result["safe_size"])
elif result["recommendation"] == "proceed_with_caution":
    # Reduce size or alert operator
    hl.market_open("ETH", True, result["safe_size"] * 0.5)
else:
    # Abort - too risky
    agent.log(f"Trade aborted: {result['flags']}")

What's Next

• Validate endpoint details - Full request/response reference
• Batch validation - Validate multiple trades in sequence
• Understanding risk scores - How scores map to recommendations
• Risk flags - What each flag means and how to respond