> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vela.monolithsystematic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> Complete reference for the Vela engine HTTP API

## Base URL

[https://vela-engine.fly.dev](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:

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

## Endpoints

### GET /markets

Returns all active markets with current best bid/ask.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:{market_id}:{side}:{price}:{quantity}:{nonce}

Sign via MetaMask `personal_sign`.

### POST /orders/cancel

Cancel an existing order. Requires wallet signature.

**Request:**

```json theme={null}
{
  "order_id": "abc123",
  "client_order_id": "",
  "user": "0x...",
  "nonce": 1713000000001,
  "signature": "0x..."
}
```

**Signature message format:**
vela:cancel:{order_id}:{client_order_id}:{nonce}

### POST /deposit

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

```json theme={null}
{
  "user": "0x...",
  "asset": "USDC",
  "amount": "1000.00"
}
```

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

### POST /withdrawals

Submit a withdrawal request.

```json theme={null}
{
  "address": "0x...",
  "asset": "ETH",
  "amount": 10000000000000000,
  "nonce": 1713000000002,
  "signature": "0x..."
}
```

### POST /withdrawal-signature

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

```json theme={null}
{
  "user": "0x...",
  "asset": "ETH",
  "amount": "0.01",
  "nonce": 1713000000003
}
```

**Response:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "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 |

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

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

### GET /fees

Returns current global fee configuration.

```json theme={null}
{
  "ok": true,
  "data": {
    "maker_fee_bps": -1,
    "taker_fee_bps": 5
  }
}
```

### GET /markets/:id/fees

Returns fee configuration for a specific market.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "user": "0x...",
  "payload": "0x...",
  "nonce": 1713000000000,
  "signature": "0x..."
}
```

### GET /ws

WebSocket upgrade endpoint. Connect via `wss://vela-engine.fly.dev/ws`. See [WebSocket Feeds](/transparency/websocket) for the full protocol reference.

### GET /admin/state

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

```bash theme={null}
curl -H "X-Admin-Token: vela-admin-2026" \
  https://vela-engine.fly.dev/admin/state
```