import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Data API

The Data API uses the HTTP protocol for on-demand market data queries. Use it for historical data retrieval, snapshot lookups, and backtesting. For the full list of available endpoints, see [Market Data API Overview](overview.md).

For real-time streaming data via MQTT, see [Data Streaming API](data-streaming-api.md).

## Base URLs

| Environment | URL |
|-------------|-----|
| Production | `https://api.webull.hk` |
| Sandbox | `https://api.sandbox.webull.hk` |

## Request Format

All Data API requests are standard HTTP GET or POST calls. Every request must include the authentication headers described in [Authentication Overview](../authentication/overview.md).

Example request:

```
GET /openapi/market-data/stock/snapshot?symbols=AAPL&category=US_STOCK&extend_hour_required=false&overnight_required=false
x-app-key: <your_app_key>
x-app-secret: <your_app_secret>
x-timestamp: 2025-03-19T10:00:00Z
x-signature-algorithm: HMAC-SHA1
x-signature-version: 1.0
x-signature-nonce: <unique_nonce>
x-version: v2
x-access-token: <your_access_token>
x-signature: <computed_signature>
```

## Response Format

All responses are returned as JSON. A successful response returns HTTP 200 with the data payload directly:

```json
[
  {
    "symbol": "AAPL",
    "instrument_id": "913256135",
    "price": "185.50",
    "open": "184.00",
    "high": "186.20",
    "low": "183.80",
    "volume": "52340000",
    "change": "1.50",
    "change_ratio": "0.0082",
    "pre_close": "184.00",
    "last_trade_time": 1710849600000
  }
]
```

Timestamps in responses are Unix timestamps in milliseconds. Prices and numeric values are returned as strings to preserve precision.

## Asset Categories

When calling Data API endpoints, you need to specify the asset category:

| Category Value | Description |
|----------------|-------------|
| `US_STOCK` | US Stocks |
| `HK_STOCK` | Hong Kong Stocks |
| `CN_STOCK` | China A-Shares (Stock Connect) |

## Rate Limits

| Limit | Value |
|-------|-------|
| Market Data API | 600 requests per minute |

If you exceed the rate limit, the server will return an error.