# Telos Chain API
> Live on-chain data for Telos EVM — a high-throughput EVM Layer 1 — via its public Blockscout explorer (no wallet, no key). The stats endpoint returns chain-wide totals (blocks, transactions, addresses, average block time, gas used); gas gives the current gas-price oracle (slow/average/fast). Blocks lists the latest blocks, and a single block resolves by height or by hash with its transaction count, gas, miner and timestamp. The address endpoint returns any account's TLOS balance, nonce, contract flag and token holdings; transaction resolves a tx by hash with its from/to, value in TLOS, fee, status and block. The token endpoint returns an ERC-20 token's metadata (name, symbol, decimals, total supply, holders) by contract address, and search runs a universal lookup across addresses, tokens, blocks and transactions. Gas, balances, values and fees are denominated in TLOS, the native coin. Real on-chain data straight from the explorer, refreshed every call — no key. 9 endpoints. For multi-chain coverage combine with the other oanor chain APIs (Ethereum, Base, Arbitrum and more).

## 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/telos-api/..."
```

## Pricing
- **Free** (Free) — 1,900 calls/Mo, 2 req/s
- **Basic** ($14/Mo) — 85,000 calls/Mo, 8 req/s
- **Pro** ($44/Mo) — 560,000 calls/Mo, 20 req/s
- **Mega** ($145/Mo) — 2,950,000 calls/Mo, 50 req/s

## Endpoints

### Chain

#### `GET /v1/gas` — Gas-price oracle

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

**Response:**
```json
{
    "data": {
        "fast": 5777.9,
        "slow": 5777.9,
        "unit": "gwei",
        "average": 5777.9,
        "gas_used_today": "171779466"
    },
    "meta": {
        "timestamp": "2026-06-08T09:49:54.325Z",
        "request_id": "e78ffbde-8e03-4d67-8e1e-b9b338eda5fb"
    },
    "status": "ok",
    "message": "Gas retrieved successfully",
    "success": true
}
```

#### `GET /v1/stats` — Chain stats

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

**Response:**
```json
{
    "data": {
        "tvl_usd": null,
        "gas_prices": {
            "fast": 5777.9,
            "slow": 5777.9,
            "average": 5777.9
        },
        "total_blocks": 471793112,
        "coin_price_usd": 0.01139262,
        "gas_used_today": "171779466",
        "market_cap_usd": 4784899.978068622,
        "total_addresses": "221824",
        "total_transactions": "9533159",
        "transactions_today": "3529",
        "network_utilization_percent": 0
    },
    "meta": {
        "timestamp": "2026-06-08T09:49:54.588Z",
        "request_id": "e2364fd9-2b95-45fd-913a-fae26488ad7e"
    },
    "status": "ok",
    "message": "Stats retrieved successfully",
    "success": true
}
```

### Blocks

#### `GET /v1/block` — A block by height or hash

**Parameters:**
- `height` (query, optional, string) — Block height Example: `471764058`
- `hash` (query, optional, string) — Block hash (alternative to height)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/telos-api/v1/block?height=471764058"
```

**Response:**
```json
{
    "data": {
        "block": {
            "hash": "0xd4fc77bb160d64b525cad4e0f726910a0814900223c4637ef4312065cca24e6f",
            "size": 821,
            "miner": "0x0000000000000000000000000000000000000000",
            "height": 471764058,
            "gas_used": 33892,
            "tx_count": 1,
            "gas_limit": 2147483647,
            "timestamp": "2026-06-08T04:44:07.000000Z",
            "burnt_fees": "0",
            "difficulty": "0",
            "base_fee_per_gas": null
        }
    },
    "meta": {
        "timestamp": "2026-06-08T09:49:54.822Z",
        "request_id": "1e061419-4472-4788-8609-2d92a5721489"
    },
    "status": "ok",
    "message": "Block retrieved successfully",
    "success": true
}
```

#### `GET /v1/blocks` — Latest blocks

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

**Response:**
```json
{
    "data": {
        "count": 50,
        "blocks": [
            {
                "hash": "0xb2f4180dbdde5477d77883cbc92acae4e97d38520def80ef8a7f8ec988952f97",
                "size": 545,
                "miner": "0x0000000000000000000000000000000000000000",
                "height": 471800752,
                "gas_used": 0,
                "tx_count": 0,
                "gas_limit": 2147483647,
                "timestamp": "2026-06-08T09:49:54.000000Z",
                "burnt_fees": "0",
                "difficulty": "0",
                "base_fee_per_gas": null
            },
            {
                "hash": "0xa3c63b79a329c084268b72132ed04034bb08f7253334a7094abfc3a33d0d3275",
                "size": 545,
                "miner": "0x0000000000000000000000000000000000000000",
                "height": 471800751,
                "gas_used": 0,
                "tx_count": 0,
                "gas_limit": 2147483647,
                "timestamp": "2026-06-08T09:49:53.000000Z",
                "burnt_fees": "0",
                "difficulty": "0",
                "base_fee_per_gas": null
            },
            {
                "hash": "0xd752c99201e6c8ff631fd2e3af843c94d33098559dc7dc861947636c94f8f3ec",
                "size": 545,
                "miner": "0x0000000000000000000000000000000000000000",
                "height": 471800750,
                "gas_used": 0,
                "tx_count": 0,
                "gas_limit": 2147483647,
                "timestamp"
…(truncated, see openapi.json for full schema)
```

### Accounts

#### `GET /v1/address` — Account balance & holdings

**Parameters:**
- `address` (query, required, string) — Account address (0x + 40 hex) Example: `0x681636784F1E2e119a86B0ddD089f4D6f49FeB41`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/telos-api/v1/address?address=0x681636784F1E2e119a86B0ddD089f4D6f49FeB41"
```

**Response:**
```json
{
    "data": {
        "address": {
            "ens": null,
            "hash": "0x681636784F1E2e119a86B0ddD089f4D6f49FeB41",
            "name": null,
            "token": null,
            "creator": null,
            "balance_wei": "9092361549074397305869",
            "is_contract": false,
            "is_verified": false,
            "balance_tlos": 9092.361549074398
        }
    },
    "meta": {
        "timestamp": "2026-06-08T09:49:55.555Z",
        "request_id": "8c58bfd2-706f-4374-bae8-5f9726d0e2ff"
    },
    "status": "ok",
    "message": "Address retrieved successfully",
    "success": true
}
```

### Transactions

#### `GET /v1/transaction` — A transaction by hash

**Parameters:**
- `hash` (query, required, string) — Transaction hash (0x + 64 hex) Example: `0xee27195cd9636a15c485ae05c5c17bfe513a8f6b8678d37841c118c576d5abe1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/telos-api/v1/transaction?hash=0xee27195cd9636a15c485ae05c5c17bfe513a8f6b8678d37841c118c576d5abe1"
```

**Response:**
```json
{
    "data": {
        "transaction": {
            "to": "0xf774801c9f1b11e70966CE65EC7f95d7730F380d",
            "from": "0x681636784F1E2e119a86B0ddD089f4D6f49FeB41",
            "hash": "0xee27195cd9636a15c485ae05c5c17bfe513a8f6b8678d37841c118c576d5abe1",
            "type": 0,
            "block": 471764058,
            "nonce": 311789,
            "method": "setValue",
            "status": "ok",
            "fee_wei": "195824301595837504",
            "fee_tlos": 0.1958243015958375,
            "gas_used": 33892,
            "gas_price": "5777891584912",
            "timestamp": "2026-06-08T04:44:07.000000Z",
            "value_wei": "0",
            "value_tlos": 0,
            "confirmations": 36697
        }
    },
    "meta": {
        "timestamp": "2026-06-08T09:49:55.817Z",
        "request_id": "abae5a08-3887-4cd9-a96a-68bc7ca6a1bd"
    },
    "status": "ok",
    "message": "Transaction retrieved successfully",
    "success": true
}
```

### Tokens

#### `GET /v1/token` — ERC-20 token metadata

**Parameters:**
- `address` (query, required, string) — Token contract address Example: `0x7627b27594bc71e6Ab0fCE755aE8931EB1E12DAC`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/telos-api/v1/token?address=0x7627b27594bc71e6Ab0fCE755aE8931EB1E12DAC"
```

**Response:**
```json
{
    "data": {
        "token": {
            "icon": null,
            "name": "Bitcoin",
            "type": "ERC-20",
            "symbol": "BTC.b",
            "holders": null,
            "decimals": 8,
            "total_supply": "4144918",
            "exchange_rate_usd": 63334,
            "circulating_market_cap": "7354930115.191614"
        }
    },
    "meta": {
        "timestamp": "2026-06-08T09:49:56.050Z",
        "request_id": "15540dbf-61d8-4466-9481-4b103d36cd1c"
    },
    "status": "ok",
    "message": "Token retrieved successfully",
    "success": true
}
```

### Search

#### `GET /v1/search` — Universal search

**Parameters:**
- `q` (query, required, string) — Address, token, block or tx Example: `BTC.b`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/telos-api/v1/search?q=BTC.b"
```

**Response:**
```json
{
    "data": {
        "count": 46,
        "query": "BTC.b",
        "results": [
            {
                "name": "Bitcoin",
                "type": "token",
                "symbol": "BTC.b",
                "address": "0x7627b27594bc71e6Ab0fCE755aE8931EB1E12DAC"
            },
            {
                "name": "Wrapped BTC",
                "type": "token",
                "symbol": "WBTC",
                "address": "0x0555E30da8f98308EdB960aa94C0Db47230d2B9c"
            },
            {
                "name": "Wrapped BTC",
                "type": "token",
                "symbol": "WBTC",
                "address": "0xf390830DF829cf22c53c8840554B98eafC5dCBc2"
            },
            {
                "name": "believe btc base",
                "type": "token",
                "symbol": "bbb",
                "address": "0x43D4066B4Cea9ee28A10cF346124095D0072c7fc"
            },
            {
                "name": "gift btc",
                "type": "token",
                "symbol": "gift",
                "address": "0x951385ebc86460eBf0B147307a2BFf591EE43AE5"
            },
            {
                "name": "BitcoinBR",
                "type": "token",
                "symbol": "BTCBR",
                "address": "0x26fD8574a21D3160c6CC6098f8e8761aa2630117"
            },
            {
                "name": "BTC@telos",
                "type": "token",
                "symbol": "BTC",
                "address": "0x9E8AAfd785F8cC9AEbB4B6Fbf817ee
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Spec

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

**Response:**
```json
{
    "data": {
        "service": "telos-api",
        "endpoints": {
            "GET /v1/gas": "Gas oracle (slow/average/fast in gwei).",
            "GET /v1/meta": "This document.",
            "GET /v1/block": "Block detail by height= or hash=.",
            "GET /v1/stats": "Network stats (blocks, txns, coin price, market cap, gas).",
            "GET /v1/token": "ERC-20 token detail by contract (address=).",
            "GET /v1/blocks": "The most recent blocks.",
            "GET /v1/search": "Search addresses, tokens, blocks & txns (q=).",
            "GET /v1/address": "Address balance, ENS & contract info (address=).",
            "GET /v1/transaction": "Transaction detail (hash=)."
        },
        "description": "Live Telos EVM on-chain data via Blockscout: network stats, a gas oracle (gwei), recent blocks and block detail, address balances with ENS, transaction detail, ERC-20 token detail and a universal search across addresses, tokens, blocks and transactions. Telos is an EVM Layer 1; gas, balances and fees are in TLOS. Real on-chain data, no key."
    },
    "meta": {
        "timestamp": "2026-06-08T09:49:56.478Z",
        "request_id": "36adb16b-0c49-4b54-a5d5-a27fd827d63a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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