API reference

Velox's API is a collection of Vercel serverless functions under /api/*. Most are read-only data endpoints; four are cron-triggered pipeline steps.

Base URL

https://app.velox.trade/api

All endpoints return JSON. Errors are { "success": false, "error": "…" } with an appropriate HTTP status.

Authentication

Current Endpoints are open to the public internet. Bearer-token auth via CRON_SECRET is on the roadmap but not yet enforced. If you self-host, put your deployment behind a reverse-proxy ACL until this ships.

Cron-triggered endpoints

These endpoints run on a Vercel cron schedule but are also HTTP-callable for manual testing.

GET /api/scan

Kicks off a full scan cycle: fetches 80 pairs of market data, fans out to three AI models, applies consensus, sizes positions, and writes trades to Redis.

Runtime gating. When invoked by the Vercel scheduler (x-vercel-cron: 1 header), the handler checks CRONS_ENABLED. If not set to "true" the call is a no-op that returns:

{
  "skipped": true,
  "cron": "scan",
  "reason": "CRONS_ENABLED env var is not \"true\""
}

Manual HTTP calls always run, regardless of CRONS_ENABLED. This lets operators smoke-test in production without flipping the flag.

Response (successful scan):

{
  "success": true,
  "cycle": 128,
  "scannedPairs": 80,
  "signals": 3,
  "goldSignals": 1,
  "silverSignals": 2,
  "tradesOpened": 3,
  "elapsedMs": 18402
}

GET /api/monitor-positions

Walks all open trades; applies partial take-profit tiers (33% / 50% / 100% at configured R-multiples), trailing stop-loss, and breakeven-stop-triggered events. Captures trade lessons to feed back into future scan prompts.

GET /api/evaluate-positions

Calls Claude once per run with all currently-open trades in context; asks for a per-trade verdict of HOLD, TIGHTEN (move SL tighter), or EXIT (close early). Acts on the response.

GET /api/optimize

Dual-mode endpoint:

Call	Behavior
`GET /api/optimize`	Read-only — returns current optimizer config from Redis
`GET /api/optimize?run=1`	Full run — reads closed trades, adjusts weights, writes new config
`GET /api/optimize` with `x-vercel-cron: 1`	Full run (scheduler-triggered)

The dual-mode exists because the frontend polls /api/optimize to display current weights in the UI without triggering a re-optimization. To force a run manually, always pass ?run=1.

Data endpoints

GET /api/market

Returns normalized OHLCV + funding + OI for a given symbol. Used internally by the scanner and exposed for external tools.

Query params:

symbol — e.g. BTCUSDT
timeframe — one of 1h, 4h, 1d

Response:

{
  "symbol": "BTCUSDT",
  "timeframe": "4h",
  "candles": [
    { "t": 1712620800, "o": 68500, "h": 68812, "l": 68230, "c": 68741, "v": 1234.5 }
  ],
  "funding": 0.00012,
  "openInterest": 12837402
}

GET /api/portfolio

Returns the current dual-portfolio state.

{
  "aggressive": {
    "balance": 10837.24,
    "equity": 11402.91,
    "openTrades": 4,
    "closedTrades": 128,
    "winRate": 0.604
  },
  "conservative": { "...": "..." }
}

GET /api/trading-config

Returns the live trading-config.js as JSON. Both the browser and server import from the same module; this endpoint makes it available to third-party integrations.

GET /api/ai-stats

Per-model performance stats: win rate, average R, shadow P&L, and current optimizer weight.

Health

GET /api/health

Returns { "ok": true, "redisReachable": true, "providers": { "claude": "ok", "gemini": "ok", "grok": "ok" } } — useful for uptime monitoring.

Rate limits

Currently none. Self-hosted deployments should add a reverse-proxy rate limiter before exposing endpoints publicly.

Versioning

The API is currently v0 — unstable, expect breaking changes between minor releases. See the changelog for version-by-version migration notes.