# TaoMarketCap API

> Public REST API for blockchain analytics on the Bittensor (TAO) network. Provides data on subnets, validators, transactions, blocks, analytics, and market information.

## Bittensor Domain Context

**Bittensor** is a decentralized AI network where ML models compete for TAO token rewards across specialized subnets.

Key concepts for this API:

- **Subnet** (`netuid`): Sub-network for a specific AI task, identified by numeric ID (e.g. 1, 18, 51)
- **Miner**: Runs ML models, earns TAO based on performance
- **Validator**: Evaluates miners, assigns weights (scores)
- **Neuron**: Any participant (miner or validator) in a subnet, identified by UID. Data: `/public/v1/subnets/neurons/{netuid}/`
- **Weights**: Scores (u16, 0-65535) validators assign to miners. Data: `/public/v1/subnets/weights/{netuid}/`
- **Hotkey**: Public key identifying a neuron
- **Coldkey**: Wallet address owning hotkeys
- **Stake**: TAO locked with a validator for voting power
- **Emission**: TAO rewards distributed each block (~12 sec)

For full Bittensor concepts, glossary, and blockchain reference: [docs.taomarketcap.com/llms.txt](https://docs.taomarketcap.com/llms.txt)

## Authentication

All `/public/v1/` endpoints are accessible **without authentication** with anonymous rate limits per IP address:

- 10 requests / minute
- 600 requests / hour
- 100,000 requests / month (calendar month, UTC)
- 2 concurrent SSE connections

```bash
curl https://api.taomarketcap.com/public/v1/subnets/
```

This API is designed for **server-side use and LLM agents**. Browser-based cross-origin requests are not supported (CORS is restricted to a whitelist).

For higher limits per user (vs. per-IP anonymous), subscribe to a paid plan and create an API key (server-side use):

**Note:** API keys require an active paid subscription. The Free plan is grandfathered — existing Free keys continue to work, but new ones are no longer issued. Subscribe at `https://api.taomarketcap.com/developer/plans`.

**Step 1 — Register an account:**

```bash
curl -X POST https://api.taomarketcap.com/auth/users/ \
  -H "Content-Type: application/json" \
  -d '{"username": "my_agent", "email": "agent@example.com", "password": "<YOUR_PASSWORD>", "re_password": "<YOUR_PASSWORD>"}'
```

Required fields: `username`, `email`, `password` (min 12 chars), `re_password` (must match `password`). Returns `201 Created` with `{"id": 1, "username": "...", "email": "..."}`. Limit: 3 registrations per IP per day.

**Step 2 — Get JWT token:**

```bash
curl -X POST https://api.taomarketcap.com/auth/jwt/create/ \
  -H "Content-Type: application/json" \
  -d '{"username": "my_agent", "password": "<YOUR_PASSWORD>"}'
```

Returns `{"access": "eyJ...", "refresh": "eyJ..."}`.

**Step 3 — Create API key:**

```bash
curl -X POST https://api.taomarketcap.com/developer/keys/api/ \
  -H "Content-Type: application/json" \
  -H "Authorization: JWT <access_token>" \
  -d '{"name": "my-key"}'
```

Returns `{"token": "<prefix>.<secret>", "key": {...}}`. Save the `token` immediately — it is shown only once.

**Step 4 — Make requests:**

```bash
curl https://api.taomarketcap.com/public/v1/subnets/ \
  -H "Authorization: <prefix>.<secret>"
```

## Rate Limits

Rate limits vary by plan (burst, hourly, monthly windows). Every API response includes these headers:

- `X-RateLimit-Limit` — max requests in current window
- `X-RateLimit-Remaining` — requests left
- `X-RateLimit-Reset` — UTC epoch when the window resets

Make any authenticated request and read the response headers to discover your current limits.

On `429 Too Many Requests`, wait for the `Retry-After` header value (in seconds) before retrying.

## Pagination

List endpoints return paginated results:

```json
{"count": 129, "next": "...?limit=25&offset=25",
"previous": null, "results": [...]}
```

Query parameters: `limit` (default 25), `offset` (default 0).

## Error Responses

| Code | Meaning |
|------|---------|
| 400  | Bad request (invalid parameters) |
| 401  | Missing or invalid API key |
| 403  | Forbidden (IP not in allowlist) |
| 429  | Rate limit exceeded |

Error body: `{"detail": "Error description"}`.

## API Endpoints

All endpoints are under `/public/v1/` and accept **GET only**.

- `/public/v1/subnets/` — Subnet list and statistics
- `/public/v1/subnets/{netuid}/` — Single subnet detail
- `/public/v1/subnets/neurons/{netuid}/` — All neurons (miners + validators) in a subnet
- `/public/v1/subnets/weights/{netuid}/` — Weight matrix (validator → miner scores, u16 values 0-65535)
- `/public/v1/blocks/` — Block data
- `/public/v1/transactions/` — Transaction history
- `/public/v1/extrinsics/` — Blockchain extrinsics
- `/public/v1/events/` — Blockchain events
- `/public/v1/accounts/` — Account and wallet data
- `/public/v1/market/` — Market data (CoinMarketCap)
- `/public/v1/analytics/` — Timeseries analytics (has sub-endpoints)
- `/public/v1/validators/{hotkey}/` — Validator detail by hotkey

### SSE Streaming Endpoints

Real-time data via Server-Sent Events (use `Accept: text/event-stream` header):

- `/public/v1/sse/blocks/` — New block notifications
- `/public/v1/sse/subnets/table/` — Subnet table updates
- `/public/v1/sse/subnets/info/` — Network info updates
- `/public/v1/sse/subnets/prices/` — Real-time subnet prices
- `/public/v1/sse/subnets/tokenomics/` — Tokenomics data
- `/public/v1/sse/subnets/{netuid}/` — Single subnet stream
- `/public/v1/sse/subnets/neurons/{netuid}/` — Neuron state stream

## Documentation

- [Full API documentation (markdown)](https://api.taomarketcap.com/llms-full.txt)
- [OpenAPI 3.0 schema (JSON)](https://api.taomarketcap.com/api/public-oas3.json?format=json)
- [Interactive docs](https://api.taomarketcap.com/developer/documentation/)
- [Developer portal](https://api.taomarketcap.com/developer/)
- [Bittensor concepts & glossary](https://docs.taomarketcap.com/llms.txt)