HTTP API

Complete reference for the Vela engine HTTP API

Base URL

https://vela-engine.fly.dev

Rate Limits

Endpoint	Limit
POST /orders	20 per minute per wallet
POST /orders/cancel	20 per minute per wallet
POST /deposit	5 per minute per wallet
POST /withdrawals	5 per minute per wallet
GET endpoints	100 per minute per IP

Rate limit exceeded returns HTTP 429 with:

{ "ok": false, "data": null, "error": "Rate limit exceeded. Please slow down." }

Endpoints

GET /markets

Returns all active markets with current best bid/ask.

{
  "ok": true,
  "data": [
    {
      "id": "ETH-USDC",
      "base": "ETH",
      "quote": "USDC",
      "best_bid": "1580.50",
      "best_ask": "1581.50",
      "spread": "1.00"
    }
  ]
}

GET /orderbook/:market_id

Returns the full order book for a market.

{
  "ok": true,
  "data": {
    "market_id": "ETH-USDC",
    "bids": [["1580500000", "500000"], ...],
    "asks": [["1581500000", "300000"], ...]
  }
}

Prices and quantities are in fixed-point format (multiply by 1,000,000 for display).

POST /orders

Place a new limit order. Requires wallet signature.

Request:

{
  "user": "0x...",
  "market_id": "ETH-USDC",
  "side": "bid",
  "price": 1580500000,
  "quantity": 500000,
  "order_type": "limit",
  "time_in_force": "gtc",
  "nonce": 1713000000000,
  "signature": "0x..."
}

Signature message format: vela:order:::::

Sign via MetaMask personal_sign.

POST /orders/cancel

Cancel an existing order. Requires wallet signature.

Request:

{
  "order_id": "abc123",
  "client_order_id": "",
  "user": "0x...",
  "nonce": 1713000000001,
  "signature": "0x..."
}

Signature message format: vela:cancel:::

POST /deposit

Credit the engine balance. Trust-based for non-ETH assets.

{
  "user": "0x...",
  "asset": "USDC",
  "amount": "1000.00"
}

For ETH on-chain deposits, use the VelaSettlement contract directly.

POST /withdrawals

Submit a withdrawal request.

{
  "address": "0x...",
  "asset": "ETH",
  "amount": 10000000000000000,
  "nonce": 1713000000002,
  "signature": "0x..."
}

POST /withdrawal-signature

Request an operator signature for an on-chain ETH withdrawal.

{
  "user": "0x...",
  "asset": "ETH",
  "amount": "0.01",
  "nonce": 1713000000003
}

Response:

{
  "ok": true,
  "data": {
    "signature": "0x...",
    "user": "0x...",
    "asset": "0x0000000000000000000000000000000000000000",
    "amount_wei": "10000000000000000",
    "nonce": 1713000000003
  }
}

GET /account/:address/balances

Returns all balances for a wallet address.

{
  "ok": true,
  "data": {
    "ETH": { "available": 1000000, "locked": 0 },
    "USDC": { "available": 500000000, "locked": 100000000 }
  }
}

GET /ohlcv/:market_id

Returns OHLCV candlestick data for a market, derived from real trade history.

Query parameters:

Param	Description	Default
interval	Candle interval: 1m, 5m, 15m, 1h, 4h, 1d	1h
limit	Number of candles to return (max 500)	100
since	ISO8601 start time	24h ago

{
  "ok": true,
  "data": [
    {
      "t": "2026-04-15T12:00:00Z",
      "o": "3200000000",
      "h": "3215000000",
      "l": "3195000000",
      "c": "3208000000",
      "v": "42500000",
      "source": "LIVE"
    }
  ]
}

source is "LIVE" when built from real trades, "SIMULATED" when built from order book midpoints.

GET /account/:address/orders/by-client-id/:client_order_id

Look up a specific order by client order ID.

{
  "ok": true,
  "data": {
    "order_id": 12345,
    "client_order_id": "my-order-001",
    "status": "open",
    "market_id": "ETH-USDC",
    "side": "bid",
    "price": 1580500000,
    "quantity": 500000,
    "filled_quantity": 0
  }
}

GET /referral/:address

Returns referral stats for a wallet address.

{
  "ok": true,
  "data": {
    "address": "0x...",
    "referral_code": "0x...",
    "referred_users": 3,
    "total_earnings_usdc": "142000",
    "active_until": "2026-07-15T00:00:00Z"
  }
}

POST /referral/register

Register a referral relationship.

{
  "referred": "0xNewUserAddress",
  "referrer": "0xReferrerAddress",
  "signature": "0x..."
}

The signature message is vela:referral:{referred}:{referrer}:{nonce}, signed by the referred user.

GET /leaderboard

Returns the trading leaderboard.

{
  "ok": true,
  "data": [
    {
      "rank": 1,
      "address": "0x...",
      "volume_usdc": "4820000000",
      "pnl_usdc": "198000",
      "trades": 842
    }
  ]
}

GET /fees

Returns current global fee configuration.

{
  "ok": true,
  "data": {
    "maker_fee_bps": -1,
    "taker_fee_bps": 5
  }
}

GET /markets/:id/fees

Returns fee configuration for a specific market.

{
  "ok": true,
  "data": {
    "market_id": "ETH-USDC",
    "maker_fee_bps": -1,
    "taker_fee_bps": 5
  }
}

GET /orders/:id/da-proof

Returns a data availability proof for a filled order. Used by external parties to verify that a fill was included in the DA layer.

{
  "ok": true,
  "data": {
    "order_id": 12345,
    "batch_id": "batch_abc123",
    "merkle_root": "0x...",
    "merkle_proof": ["0x...", "0x..."],
    "fill_hash": "0x..."
  }
}

POST /force-include

Submit a signed transaction directly to the delayed inbox. The engine must include it within 24 hours or face an on-chain challenge.

{
  "user": "0x...",
  "payload": "0x...",
  "nonce": 1713000000000,
  "signature": "0x..."
}

GET /ws

WebSocket upgrade endpoint. Connect via wss://vela-engine.fly.dev/ws. See WebSocket Feeds for the full protocol reference.

GET /admin/state

Admin-only endpoint. Requires X-Admin-Token header.

curl -H "X-Admin-Token: vela-admin-2026" \
  https://vela-engine.fly.dev/admin/state