POST /v1/validate

The core endpoint. Analyzes a proposed trade against real-time market data and returns a structured risk assessment.

Request

POST https://api.canon.trade/v1/validate

Headers

Header	Required	Value
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	Yes	application/json

Body

{
  "asset": "BTC",
  "action": "long",
  "size": 50000,
  "leverage": 10,
  "wallet": "0x7a3b1234567890abcdef1234567890abcdef1234",
  "mode": "cross"
}

Field	Type	Required	Description
asset	string	Yes	Asset ticker (e.g. "BTC", "ETH", "HYPE")
action	string	Yes	Trade direction: "long", "short", or "close"
size	number	Yes	Position size in USD. Must be positive, max $100,000,000
leverage	number	No	Leverage multiplier. Cannot exceed the asset's maximum leverage
wallet	string	Yes	Ethereum wallet address (42 characters, 0x prefix)
mode	string	No	Margin mode: "cross" (default) or "isolated"

Validation Rules

• wallet must be a valid 42-character hex address starting with 0x
• size must be positive and not exceed $100M
• leverage cannot exceed the asset's maximum allowed leverage
• asset must be a currently listed (not delisted) asset on Hyperliquid
• Some assets are isolated-margin only and will reject "cross" mode

Response

{
  "risk_score": 42,
  "recommendation": "proceed_with_caution",
  "flags": ["funding_anomaly"],
  "slippage": {
    "estimated_bps": 5.2,
    "fill_price": 67432.10,
    "depth_at_50bps": 2150000,
    "depth_at_100bps": 4800000,
    "book_imbalance": 0.62
  },
  "liquidation": {
    "price": 61200.50,
    "distance_pct": 9.2,
    "margin_usage_pct": 68.4,
    "effective_leverage": 10.8
  },
  "funding": {
    "rate_8h": 0.0089,
    "annualized_pct": 9.7,
    "cex_divergence": 0.0034,
    "direction": "longs_pay"
  },
  "impact": {
    "expected_bps": 8.1,
    "participation_pct": 2.3
  },
  "var": {
    "var_95_pct": 4.2,
    "var_99_pct": 6.8,
    "var_95_usd": 2100,
    "var_99_usd": 3400,
    "expected_shortfall_pct": 5.1
  },
  "oi": {
    "current": 485000000,
    "at_cap": false,
    "utilization_pct": 72.3
  },
  "portfolio": {
    "portfolio_var_pct": 5.1,
    "position_count": 3
  },
  "stress": {
    "worst_scenario": "luna_collapse",
    "worst_pnl_usd": -18500
  },
  "fees": {
    "estimated_open_fee": 12.50,
    "estimated_close_fee": 12.50
  },
  "meta": {
    "asset": "BTC",
    "mark_price": 67500.00,
    "max_leverage": 50,
    "latency_ms": 52,
    "request_id": "req_d4f8a2b1"
  }
}

Response Fields

Field	Type	Description
risk_score	number	Composite risk score from 0 (lowest risk) to 100 (highest risk)
recommendation	string	"proceed", "proceed_with_caution", or "abort"
flags	string[]	Array of risk flags identifying specific concerns. See Risk Flags
slippage	object	Order book slippage analysis
liquidation	object	Liquidation proximity metrics
funding	object	Funding rate analysis
impact	object	Market impact estimation
var	object	Value-at-Risk calculations
oi	object	Open interest utilization
portfolio	object	Portfolio-level risk (when wallet has existing positions)
stress	object	Stress test results against historical scenarios
fees	object	Estimated trading fees
meta	object	Request metadata including current mark price and latency

Slippage Object

Field	Type	Description
estimated_bps	number	Expected slippage in basis points
fill_price	number	Estimated average fill price
depth_at_50bps	number	USD liquidity available within 50bps of mid
depth_at_100bps	number	USD liquidity available within 100bps of mid
book_imbalance	number	Order book imbalance ratio (0-1). Values near 0.5 indicate balance

Liquidation Object

Field	Type	Description
price	number	Estimated liquidation price
distance_pct	number	Distance from mark price to liquidation as percentage
margin_usage_pct	number	Percentage of available margin consumed
effective_leverage	number	Effective leverage accounting for existing positions

Funding Object

Field	Type	Description
rate_8h	number	Current 8-hour funding rate
annualized_pct	number	Projected annualized funding cost as percentage
cex_divergence	number	Divergence between Hyperliquid and CEX funding rates
direction	string	"longs_pay" or "shorts_pay"

Impact Object

Field	Type	Description
expected_bps	number	Estimated market impact in basis points
participation_pct	number	Trade size as percentage of recent volume

VaR Object

Field	Type	Description
var_95_pct	number	24-hour Value-at-Risk at 95% confidence (percentage)
var_99_pct	number	24-hour Value-at-Risk at 99% confidence (percentage)
var_95_usd	number	95% VaR in USD
var_99_usd	number	99% VaR in USD
expected_shortfall_pct	number	Expected Shortfall (CVaR) as percentage

OI Object

Field	Type	Description
current	number	Current open interest in USD
at_cap	boolean	Whether the asset is at Hyperliquid's OI cap
utilization_pct	number	OI as percentage of estimated cap

Meta Object

Field	Type	Description
asset	string	Asset ticker
mark_price	number	Current mark price
max_leverage	number	Maximum allowed leverage for this asset
latency_ms	number	Server-side processing time in milliseconds
request_id	string	Unique identifier for this request