# Block Time API
> Convert a timestamp or date into the block number that was live at that moment on any of 100+ blockchains, keyless. On-chain analysts, indexers and dashboards constantly need "what block was chain X at time T" to query historical state, and "which blocks cover this time window" to scan a period. This API answers both — for a single moment and for a date range (returning the start and end block plus the block count and average block time). Live, nothing stored. The timestamp-to-block layer for EVM and non-EVM chains alike. Backed by the open DeFiLlama coins API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/blocktime-api/..."
```

## Pricing
- **Free** (Free) — 6,000 calls/Mo, 3 req/s
- **Starter** ($9/Mo) — 140,000 calls/Mo, 8 req/s
- **Pro** ($30/Mo) — 900,000 calls/Mo, 20 req/s
- **Business** ($86/Mo) — 5,500,000 calls/Mo, 50 req/s

## Endpoints

### Blocks

#### `GET /v1/at` — Block height at a timestamp or date on a chain

**Parameters:**
- `chain` (query, required, string) — Chain (ethereum, polygon, arbitrum, base, optimism, bsc, avax...) Example: `ethereum`
- `timestamp` (query, required, string) — Unix timestamp (seconds); or use date=YYYY-MM-DD Example: `1704067200`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/blocktime-api/v1/at?chain=ethereum&timestamp=1704067200"
```

**Response:**
```json
{
    "data": {
        "note": "The block that was live at (or closest at/after) the requested time. drift_seconds is how far the block's timestamp is from the request.",
        "chain": "ethereum",
        "source": "DeFiLlama",
        "block_height": 18908895,
        "drift_seconds": 11,
        "block_timestamp": 1704067211,
        "requested_timestamp": 1704067200
    },
    "meta": {
        "timestamp": "2026-06-14T08:04:14.260Z",
        "request_id": "762c6837-b7e5-4f32-834c-adb9eade76d8"
    },
    "status": "ok",
    "message": "Block at timestamp retrieved successfully",
    "success": true
}
```

#### `GET /v1/range` — Start/end block, block count and avg block time for a window

**Parameters:**
- `chain` (query, required, string) — Chain Example: `ethereum`
- `start` (query, required, string) — Window start: unix timestamp or date (YYYY-MM-DD) Example: `2024-01-01`
- `end` (query, required, string) — Window end: unix timestamp or date Example: `2024-02-01`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/blocktime-api/v1/range?chain=ethereum&start=2024-01-01&end=2024-02-01"
```

**Response:**
```json
{
    "data": {
        "note": "The first and last block covering the time window, the number of blocks in it, and the average block time across the window.",
        "chain": "ethereum",
        "source": "DeFiLlama",
        "end_block": 19129889,
        "block_count": 220994,
        "start_block": 18908895,
        "end_timestamp": 1706745600,
        "start_timestamp": 1704067200,
        "duration_seconds": 2678400,
        "avg_block_time_seconds": 12.12
    },
    "meta": {
        "timestamp": "2026-06-14T08:04:14.428Z",
        "request_id": "6b10183e-b947-46c9-a849-701b8387813b"
    },
    "status": "ok",
    "message": "Block range retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Service metadata & live sample

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/blocktime-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "at takes chain (e.g. ethereum, polygon, arbitrum, base, optimism, bsc) and timestamp (unix seconds) or date (YYYY-MM-DD). range takes chain, start and end (each a timestamp or date).",
        "sample": {
            "chain": "ethereum",
            "block_height": 18908895
        },
        "source": "DeFiLlama open coins API (coins.llama.fi/block), live",
        "service": "blocktime-api",
        "endpoints": {
            "GET /v1/at": "Block height at a timestamp/date on a chain (chain=ethereum, timestamp=1704067200).",
            "GET /v1/meta": "This document.",
            "GET /v1/range": "Start/end block, block count and avg block time for a window (chain, start, end)."
        },
        "description": "Convert a timestamp or date into the block number that was live at that moment on any of 100+ blockchains, keyless. Answers the two questions on-chain analysts ask constantly: what block was chain X at time T (to query historical state), and which blocks cover a time window (to scan a period — returning start and end block, block count and average block time). Live, nothing stored beyond a short cache. The timestamp-to-block layer for EVM and non-EVM chains alike. Backed by the open DeFiLlama coins API.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-14T08:04:14.500Z",
        "request_id": "55d8d174-d0e1-466d-a6c6-e45d4e847046"
    },
    "status": "ok",
    "message": "Meta",
    "success":
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/blocktime-api
OpenAPI spec: https://www.oanor.com/api/blocktime-api/openapi.json