# TMC Public API Public REST API for Tao Market Cap — blockchain analytics for the Bittensor (TAO) network. ## Authentication All `/public/v1/` endpoints are accessible **without authentication**, with per-IP rate limits (10 req/min, 600 req/hour, 100k req/month, 2 concurrent SSE connections). ## Higher limits with an API key For higher per-user limits, subscribe to a paid plan at `/developer/plans` and create an API key. The Free plan is grandfathered — existing Free keys keep working, but new ones are no longer issued. 1. **Register**: `POST /auth/users/` with `{username, email, password, re_password}` 2. **Login**: `POST /auth/jwt/create/` with `{username, password}` → returns `{access, refresh}` 3. **Subscribe**: visit `/developer/plans` and subscribe to Pro or Business 4. **Create key**: `POST /developer/keys/api/` with header `Authorization: JWT ` → returns `{token, key}` 5. **Use key**: Add header `Authorization: .` to `/public/v1/` requests ## Rate limits Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. On `429`, honour `Retry-After`. ## Notes - All `/public/v1/` endpoints are **GET-only** - SSE streaming: `/public/v1/sse/*` - LLM-friendly docs: `/llms.txt` and `/llms-full.txt` ## Getting Started Follow these steps to obtain an API key and start making requests. **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. For most LLM use cases, the anonymous tier (100,000 requests/month per IP, no key required) is sufficient. ### 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": "", "re_password": ""}' ``` Required fields: `username`, `email`, `password` (min 12 characters), `re_password` (must match `password`). Returns `201 Created` with `{"id": 1, "username": "...", "email": "..."}`. Limit: 3 registrations per IP per day. ### Step 2: Get a JWT Token ```bash curl -X POST https://api.taomarketcap.com/auth/jwt/create/ \ -H "Content-Type: application/json" \ -d '{"username": "my_agent", "password": ""}' ``` Returns `{"access": "eyJ...", "refresh": "eyJ..."}`. Use the `access` token in the next step. ### Step 3: Create an API Key ```bash curl -X POST https://api.taomarketcap.com/developer/keys/api/ \ -H "Content-Type: application/json" \ -H "Authorization: JWT " \ -d '{"name": "my-agent-key"}' ``` Returns `{token, key}`. The `token` field contains your API key in `.` format. **Save it immediately** — it is shown only once and cannot be retrieved later. ### Step 4: Make API Requests ```bash curl https://api.taomarketcap.com/public/v1/subnets/ \ -H "Authorization: ." ``` Include the `Authorization: .` header in every request to `/public/v1/` endpoints. ## 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). ## 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). ## 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"}`. ## Important Notes - All `/public/v1/` endpoints accept **GET only** - Response format is **JSON** - SSE streaming is available at `/public/v1/sse/*` (requires `Accept: text/event-stream` header) - API keys can be revoked via `POST /developer/keys//revoke/` with JWT auth ## Endpoints ### GET /public/v1/accounts/coldkey-chart/{coldkey}/ Retrieves the historical balance of a specific coldkey over time. The data is provided in hourly snapshots, showing the `free`, `total`, and `staked` balances. Supports time span filtering (1D, 1W, 1M, 1Y, ALL). Results are cached for 12 seconds. #### Parameters - **coldkey** (path, string, **required**) - **span** (query, string, optional) Time span filter for historical data. Available values: 1D, 1W, 1M, 1Y, ALL. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json [ [ { "timestamp": "2024-01-15T10:00:00Z", "block_number": 4200000, "free": "10000.00", "total": "25000.00", "staked": "15000.00" }, { "timestamp": "2024-01-15T11:00:00Z", "block_number": 4200300, "free": "10100.50", "total": "25250.50", "staked": "15150.00" } ] ] ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/accounts/coldkey-count-chart/ Retrieves time series data showing the historical count of coldkeys on the network. This endpoint is useful for visualizing the growth of the network over time. #### Parameters - **span** (query, string, optional) Time span filter for historical data. Available values: 1D, 1W, 1M, 1Y, ALL. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json [ { "timestamp": "2024-01-15T10:00:00Z", "block_number": 4200000, "value": 45000 }, { "timestamp": "2024-01-15T11:00:00Z", "block_number": 4200300, "value": 45100 } ] ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/accounts/coldkey-historical-subnets/{coldkey_id}/ Retrieves a list of all subnets where a specific coldkey has ever held a stake. This endpoint provides a historical record of a coldkey's participation across the network. #### Parameters - **coldkey_id** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "coldkey": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "subnets": [ 1, 2, 3, 5, 8 ] } ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/accounts/coldkey-identities/ Retrieves a list of all registered coldkey identities, including their metadata such as name, URL, image, and social links. This endpoint provides a comprehensive directory of all known coldkey identities on the network. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json [ { "coldkey": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "name": "Example Validator", "url": "https://example.com", "github_repo": "example/repo", "image": "https://example.com/logo.png", "discord": "examplevalidator#1234", "description": "A reliable validator.", "additional": { "telegram": "@example" }, "block_number": 4234567, "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-16T12:00:00Z" } ] ``` **500** - Internal server error ### GET /public/v1/accounts/coldkey-stakes/{nominator_coldkey}/ Retrieves an enhanced and more structured view of a coldkey's staking information, organized by subnet. This endpoint provides a detailed breakdown of a coldkey's stakes, including the validators it is staked to within each subnet. #### Parameters - **nominator_coldkey** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "coldkey": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "total_stake": "15000.50", "total_subnets": 2, "stakes_by_subnet": [ { "subnet_id": 1, "subnet_name": "Main Subnet", "total_stake": "5000.00", "validators": [ { "hotkey": "5HYk8J9PErYqpmV63jPPQRvFhJhXgZdF...", "stake": "5000.00" } ] }, { "subnet_id": 3, "subnet_name": "Research Subnet", "total_stake": "10000.50", "validators": [ { "hotkey": "5GpzS9f...8d9fE2g", "stake": "10000.50" } ] } ] } ``` **404** - Not found **500** - Internal server error ### GET /public/v1/accounts/coldkey-subnet-chart/{coldkey_id}/ Retrieves time series data of a coldkey's stake history in a specific subnet or across all subnets. If a `subnet` ID is provided, it shows the stake history for that subnet; otherwise, it returns the aggregated stake history across all subnets. Supports time span filtering and an optional `join_swapped` flag to merge history from previous swapped coldkeys up to their swap time. #### Parameters - **coldkey_id** (path, string, **required**) - **group_threshold** (query, number, optional) Percentage threshold (0-100) for grouping small subnets. Subnets below this percentage of total stake (based on latest data) will be grouped into a single 'Others' entry. Only applies when viewing all subnets (no subnet filter). Example: 10 means subnets < 10% will be grouped. - **join_swapped** (query, boolean, optional) Include historical data from previous coldkeys that swapped into the requested coldkey. Only earlier coldkeys are joined. - **skip_grouped_netuids** (query, boolean, optional) Skip the list of netuids in grouped subnets entry. When group_threshold is used, small subnets are grouped into an entry with netuid -1. By default, this entry includes a list of all netuids in the group. Set this to true to omit the list and reduce response size. Example: ?skip_grouped_netuids=1 - **span** (query, string, optional) Time span filter for historical data. Available values: 1D, 1W, 1M, 1Y, ALL. - **subnet** (query, integer, optional) Subnet ID to filter chart data. If omitted, data across all subnets is returned. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Chart data for a coldkey's stake in a specific subnet or across all subnets. Content-Type: `application/json` Example (Example): ```json [ { "timestamp": "2024-01-15T10:00:00Z", "block_number": 4200000, "stake": "5000.00", "subnet_id": 1 }, { "timestamp": "2024-01-15T11:00:00Z", "block_number": 4200300, "stake": "5100.00", "subnet_id": 1 } ] ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/accounts/coldkeys/ Retrieves a paginated list of all coldkeys, including their balance, staking data, and network rank. This endpoint supports pagination (`limit`, `offset`), ordering by `free` balance, `tao_staked` amount, or `rank`, and searching by coldkey address. Each coldkey in the response includes a `stakes` array, detailing stakes to different hotkeys across various subnets. The data is cached for 12 seconds to ensure performance. #### Parameters - **free_gte** (query, integer, optional) - **free_lte** (query, integer, optional) - **id** (query, string, optional) - **limit** (query, integer, optional) Number of items to return per page. - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. - **ordering** (query, string, optional) Field to order the results by. Available options: `free`, `tao_staked`, `rank`. - **search** (query, string, optional) A search term to filter results by coldkey address. - **subnet** (query, string, optional) - **tao_staked_gte** (query, integer, optional) - **tao_staked_lte** (query, integer, optional) - **total_gte** (query, integer, optional) - **total_lte** (query, integer, optional) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 50000, "next": "http://api.example.com/public/v1/accounts/coldkeys/?limit=25&offset=25", "previous": null, "results": [ { "id": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", "free": "10000.50", "total": "25000.50", "staked": "15000.00", "tao_staked": "12500.50", "rank": 42, "tao_change_24h": "250.50", "percent_change_24h": 2.5, "stakes": [ { "stake": "5000.00", "hotkey": "5HYk8J9PErYqpmV63jPPQRvFhJhXgZdF...", "netuid": 1, "taoStaked": "4500.00" }, { "stake": "10000.00", "hotkey": "5HEo5i7921x3k4v4KjW78g2z5E9b2Q8vV...", "netuid": 3, "taoStaked": "8000.50" } ] }, { "id": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty", "free": "500.00", "total": "500.00", "staked": "0.00", "tao_staked": "0.00", "rank": 1024, "tao_change_24h": "-50.00", "percent_change_24h": -0.5, "stakes": [] } ] } ] } ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/accounts/coldkeys/{id}/ Retrieves detailed information for a specific coldkey by its SS58 address. The response includes balance details, staking information, rank, and identity metadata if available. If the address is valid but not yet recorded on-chain, a mock response with zeroed balance values is returned. Results are cached for 12 seconds. #### Parameters - **id** (path, string, **required**) A unique value identifying this coldkey balances. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "id": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", "public_key": "0xabc123...", "free": "10000.50", "total": "25000.50", "staked": "15000.00", "tao_staked": "12500.50", "block_number": 4234567, "rank": 42, "created_at_block": 3500000, "updated_at": "2024-01-15T10:00:00Z", "tao_change_24h": "250.50", "percent_change_24h": 2.5, "free_change_24h": "100.00", "coldkey_identity": { "name": "Example Validator", "url": "https://example.com", "image": "https://example.com/logo.png", "discord": "examplevalidator#1234", "description": "A reliable and community-focused validator." }, "stakes": [ { "stake": "5000.00", "hotkey": "5HYk8J9PErYqpmV63jPPQRvFhJhXgZdF...", "netuid": 1, "taoStaked": "4500.00" } ] } ``` **404** - Not found **500** - Internal server error ### GET /public/v1/accounts/coldkeys/histogram/ Get histogram distribution for a numeric field. Returns array of [bucket_value, count] pairs. #### Parameters - **buckets** (query, integer, optional) Number of buckets (2-100, default 20) - **clip_max** (query, number, optional) Exclude values above this - **clip_min** (query, number, optional) Exclude values below this - **field** (query, string, **required**) Numeric field to histogram - **round** (query, integer, optional) Round bucket values to N decimals (0=int) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "object" } ``` ### GET /public/v1/accounts/exchanges/ Retrieves aggregated statistics for known exchange wallets, including their current balance, 24-hour inflows and outflows, and a list of associated coldkey addresses. This endpoint is useful for monitoring the activity of exchange wallets on the network. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json [ [ { "exchange": "binance", "current_balance": "1000000.50", "inflows24h": "50000.00", "outflows24h": "45000.00", "coldkeys": [ "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "5DTestABC123456DEF789GHI012..." ] }, { "exchange": "kucoin", "current_balance": "750000.00", "inflows24h": "30000.00", "outflows24h": "32000.00", "coldkeys": [ "5Ek4f...8d2hA4f" ] } ] ] ``` **500** - Internal server error ### GET /public/v1/accounts/exchanges/{exchange}/ Retrieves aggregated statistics for a specific exchange, identified by its name. The response includes the current balance, total inflows and outflows over the last 24 hours, and a list of associated coldkey addresses. Results are cached for 12 seconds. #### Parameters - **exchange** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "exchange": "binance", "current_balance": "1000000.50", "inflows24h": "50000.00", "outflows24h": "45000.00", "coldkeys": [ "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "5DTestABC123456DEF789GHI012..." ] } ``` **404** - Not found **500** - Internal server error ### GET /public/v1/accounts/exchanges/chart/{exchange}/ Historical chart for a single exchange: per-bucket balance and rolling 24h inflow/outflow. Granularity is hourly for spans <= 1M and daily for 1Y/ALL. #### Parameters - **exchange** (path, string, **required**) - **span** (query, string, optional) Time span filter. Available values: 1D, 1W, 1M, 1Y, ALL. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Chart series **400** - Invalid span **404** - Exchange not found ### GET /public/v1/accounts/exchanges/chart/total/ Historical chart aggregating balances of all known exchanges per bucket. Each entry exposes an `exchanges` map of {exchange_name: balance}. Granularity is hourly for spans <= 1M and daily for 1Y/ALL. #### Parameters - **span** (query, string, optional) Time span filter. Available values: 1D, 1W, 1M, 1Y, ALL. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Pivoted chart series **400** - Invalid span ### GET /public/v1/accounts/hotkey-historical-subnets/{hotkey_id}/ Retrieves a list of all subnets where a specific hotkey has ever been active. This endpoint provides a historical record of a hotkey's participation across the network. #### Parameters - **hotkey_id** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - No response body **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/accounts/hotkey-metagraph-chart/{hotkey_id}/ Retrieves time series data of a hotkey's metagraph history in a specific subnet or across all subnets. The optional `field` parameter accepts a comma-separated list of metrics (incentive, vtrust, dividends, dominance, apy, miner_performance, alpha_stake, tao_stake, total_stake, alpha_per_day); if omitted, all fields are returned. If a `subnet` is provided, returns flat entries with each requested field as a top-level key. Otherwise, returns per-bucket entries with a `subnets` map keyed by stringified netuid: {netuid: {field: value, ...}, ...}. Scales: `incentive`, `vtrust`, `dividends`, `dominance`, `apy` are returned in 0..100 percent; `miner_performance` in -100..100; stake fields as decimal RAO strings; `alpha_per_day` as a RAO string (TAO * 1e9, decimals truncated). Supports time span filtering (1D, 1W, 1M, 1Y, ALL). #### Parameters - **field** (query, string, optional) Optional comma-separated list of metagraph fields to include. Available values: incentive, vtrust, dividends, dominance, apy, miner_performance, alpha_stake, tao_stake, total_stake, alpha_per_day. If omitted, all fields are returned. Example: ?field=incentive,apy,total_stake - **hotkey_id** (path, string, **required**) - **span** (query, string, optional) Time span filter for historical data. Available values: 1D, 1W, 1M, 1Y, ALL. - **subnet** (query, integer, optional) Subnet ID to filter chart data. If omitted, data across all subnets is returned. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Time series of the requested hotkey metagraph field, either flat (when subnet is provided) or grouped by timestamp with per-subnet entries. **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/accounts/hotkeys/ Retrieves a paginated list of all hotkeys, including their total stake and the number of subnets they are active in. This endpoint is useful for getting a high-level overview of all hotkeys on the network. #### Parameters - **address** (query, string, optional) - **coldkey** (query, string, optional) - **id** (query, string, optional) - **is_neuron** (query, boolean, optional) - **limit** (query, integer, optional) Number of items to return per page. - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. - **subnet** (query, string, optional) - **uid** (query, integer, optional) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 100000, "next": "http://api.example.com/public/v1/accounts/hotkeys/?limit=25&offset=25", "previous": null, "results": [ { "address": "5HYk8J9PErYqpmV63jPPQRvFhJhXgZdF...", "total_stake": "15000.50", "subnet_count": 3 }, { "address": "5GpzS9f...8d9fE2g", "total_stake": "12000.00", "subnet_count": 1 } ] } ] } ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/accounts/hotkeys/{address}/ Retrieves detailed information for a specific hotkey, including its total stake and a breakdown of its stakes across different subnets. This endpoint provides a comprehensive view of a hotkey's activity and performance on the network. #### Parameters - **address** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "address": "5HYk8J9PErYqpmV63jPPQRvFhJhXgZdF...", "total_stake": "15000.50", "subnets": [ { "subnet_id": 1, "uid": 42, "stake": "5000.00", "rank": 0.95, "trust": 0.98 }, { "subnet_id": 3, "uid": 12, "stake": "10000.50", "rank": 0.88, "trust": 0.92 } ] } ``` **404** - Not found **500** - Internal server error ### GET /public/v1/accounts/info/ Retrieves aggregated statistics for all accounts on the network, including the total number of coldkeys and hotkeys, as well as the total staked and free balances. This endpoint provides a high-level overview of the network's account landscape. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "total_coldkeys": 50000, "total_hotkeys": 100000, "total_staked": "5000000.00", "total_free": "2000000.00" } ``` **500** - Internal server error ### GET /public/v1/accounts/proxies/ Retrieves all active proxy relationships. Filter by `delegator` or `delegatee` query params. #### Parameters - **delegatee** (query, string, optional) Filter by delegatee coldkey address. - **delegator** (query, string, optional) Filter by delegator coldkey address. - **limit** (query, integer, optional) Number of items to return per page. - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. - **real_pays_fee** (query, boolean, optional) Filter by real_pays_fee boolean value. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json [ { "count": 2, "next": null, "previous": null, "results": [ { "delegator": "5Grwv...fc8", "delegatee": "5FZi...f6Z", "proxy_type": "Staking", "delay": 0, "block_number": 1234567, "created_at": "2024-01-15T10:30:00Z" } ] } ] ``` ### GET /public/v1/accounts/proxies/{coldkey}/ Retrieves active proxies granted BY this coldkey (where coldkey is delegator). #### Parameters - **coldkey** (path, string, **required**) - **limit** (query, integer, optional) Number of items to return per page. - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json [ { "count": 2, "next": null, "previous": null, "results": [ { "delegator": "5Grwv...fc8", "delegatee": "5FZi...f6Z", "proxy_type": "Staking", "delay": 0, "block_number": 1234567, "created_at": "2024-01-15T10:30:00Z" } ] } ] ``` **400** - Invalid coldkey address ### GET /public/v1/accounts/subnet-holders/{subnet_id}/ Retrieves a paginated list of all accounts holding tokens for a specific subnet, including their balance, stake, and both realized and unrealized profit and loss (PnL). This endpoint is useful for analyzing the distribution of tokens within a subnet. #### Parameters - **limit** (query, integer, optional) Number of items to return per page. - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. - **subnet_id** (path, integer, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "count": 1000, "next": "http://api.example.com/public/v1/accounts/subnet-holders/1/?limit=25&offset=25", "previous": null, "results": [ { "coldkey": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "balance": "1000.50", "stake": "500.00", "realized_pnl": 150, "unrealized_pnl": 200 }, { "coldkey": "5FHneW46xGXgs5mUiveU4sbTyGBzms...", "balance": "2500.00", "stake": "1500.00", "realized_pnl": -50, "unrealized_pnl": 120 } ] } ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/analytics/chain/ Retrieves chain-wide analytics timeseries data from the chain_analytics_hourly table. Use span=1D, 1W, 1M, 1Y, or ALL to select the time range. Hourly data is returned for 1D/1W/1M, while 1Y and ALL return daily end-of-day values. #### Parameters - **fields** (query, string, optional) Comma-separated list of fields to include in the response (e.g., 'ts,block_number,total_chain_buys'). If specified, only these fields are returned. - **omit** (query, string, optional) Comma-separated list of fields to exclude from the response (e.g., 'trading_volume_cumulative'). Ignored if 'fields' is specified. - **span** (query, string, optional) Time range for analytics data. Supported values: 1D, 1W, 1M, 1Y, ALL. Hourly granularity is used for 1D/1W/1M, daily end-of-day values are used for 1Y/ALL. ALL returns the last 365 days. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Chain analytics timeseries data. Content-Type: `application/json` Example (Example): ```json [ [ { "ts": "2024-01-01T00:00:00Z", "block_number": 1234567, "total_chain_buys": 150, "root_amount": 1000000000000, "total_subnet_tao": 5000000000000, "total_issuance": 21000000000000000, "total_staked_tao": 15000000000000000, "tao_on_wallets_percent": 28.5, "tao_in_subnets_percent": 23.8, "tao_on_root_percent": 47.7, "trading_volume_1h": 500000000000, "trading_volume_cumulative": 10000000000000000 }, { "ts": "2024-01-01T01:00:00Z", "block_number": 1234867, "total_chain_buys": 152, "root_amount": 1000100000000, "total_subnet_tao": 5001000000000, "total_issuance": 21000100000000000, "total_staked_tao": 15000100000000000, "tao_on_wallets_percent": 28.4, "tao_in_subnets_percent": 23.9, "tao_on_root_percent": 47.7, "trading_volume_1h": 480000000000, "trading_volume_cumulative": 10000480000000000 } ] ] ``` ### GET /public/v1/analytics/root-claim/ Retrieves root claim type analytics timeseries data from the coldkey_claim_type_hourly table. Use span=1D, 1W, 1M, 1Y, or ALL to select the time range. Hourly data is returned for 1D/1W/1M, while 1Y and ALL return daily end-of-day values. #### Parameters - **fields** (query, string, optional) Comma-separated list of fields to include in the response (e.g., 'ts,block_number,total_chain_buys'). If specified, only these fields are returned. - **omit** (query, string, optional) Comma-separated list of fields to exclude from the response (e.g., 'trading_volume_cumulative'). Ignored if 'fields' is specified. - **span** (query, string, optional) Time range for analytics data. Supported values: 1D, 1W, 1M, 1Y, ALL. Hourly granularity is used for 1D/1W/1M, daily end-of-day values are used for 1Y/ALL. ALL returns the last 365 days. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Root claim analytics timeseries data. Content-Type: `application/json` Example (Example): ```json [ [ { "ts": "2024-01-01T00:00:00Z", "block_number": 1234567, "accounts_keep": 15000, "accounts_swap": 8500, "accounts_keep_subnets": 12000, "tao_staked_keep": 8000000000000000, "tao_staked_swap": 4500000000000000, "root_staked_keep": 3000000000000000, "root_staked_swap": 1500000000000000 } ] ] ``` ### GET /public/v1/analytics/subnet/{netuid}/ Retrieves per-subnet analytics timeseries data from the subnet_analytics_hourly table. Requires a netuid path parameter. Use span=1D, 1W, 1M, 1Y, or ALL to select the time range. Hourly data is returned for 1D/1W/1M, while 1Y and ALL return daily end-of-day values. #### Parameters - **fields** (query, string, optional) Comma-separated list of fields to include in the response (e.g., 'ts,block_number,total_chain_buys'). If specified, only these fields are returned. - **netuid** (path, integer, **required**) The subnet network UID (netuid) to retrieve analytics for. - **omit** (query, string, optional) Comma-separated list of fields to exclude from the response (e.g., 'trading_volume_cumulative'). Ignored if 'fields' is specified. - **span** (query, string, optional) Time range for analytics data. Supported values: 1D, 1W, 1M, 1Y, ALL. Hourly granularity is used for 1D/1W/1M, daily end-of-day values are used for 1Y/ALL. ALL returns the last 365 days. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Subnet analytics timeseries data. Content-Type: `application/json` Example (Example): ```json [ [ { "ts": "2024-01-01T00:00:00Z", "netuid": 1, "block_number": 1234567, "emission_percent": 5.25, "chain_buys": 25, "subnet_tao": 100000000000000, "total_tao_buy": 50000000000000, "total_tao_sell": 45000000000000, "total_tao_buy_24h": 5000000000000, "total_tao_sell_24h": 4500000000000, "volume_24h": 9500000000000, "tx_amount_24h": 150000000000, "tx_count_24h": 1250, "neuron_registrations_24h": 15, "circulation_supply": 21000000000000000, "total_supply": 21000000000000000, "daily_emission": 500000000000, "rao_recycled_24h": 120000000000, "daily_inflation": 300000000000, "tao_price_usd": 325.5, "tao_price_eur": 298.1 } ] ] ``` ### GET /public/v1/analytics/tax-report/ Generate a CSV tax report for a coldkey address. Returns daily balance snapshots with TAO price, plus intra-day transactions (fees, transfers, token swaps). Output matches the taostats accounting CSV format. Requires an API key with a plan that has tax report access enabled. Each plan has a monthly limit on tax report requests. #### Parameters - **coldkey** (query, string, **required**) Coldkey address (SS58 format) - **date_end** (query, string, **required**) End date (YYYY-MM-DD) - **date_start** (query, string, **required**) Start date (YYYY-MM-DD) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "string", "format": "binary" } ``` ### GET /public/v1/analytics/trending/ Retrieves a list of trending entities across the network, including subnets, validators, and coldkeys. The trending score is based on page view analytics over the last 7 days. The response includes the entity type, ID, total views, and the percentage change in views compared to the previous 7-day period. #### Parameters - **limit** (query, integer, optional) Number of items to return (1-50). #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Trending data for all entity types. Content-Type: `application/json` Example (Example): ```json { "analytics_available": true, "data": { "subnets": [ { "entity_type": "subnets", "entity_id": "1", "views": 1500, "percentage_change": 25.5 } ], "validators": [ { "entity_type": "validators", "entity_id": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", "views": 1200, "percentage_change": 15.0 } ], "coldkeys": [ { "entity_type": "coldkeys", "entity_id": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty", "views": 900, "percentage_change": -5.2 } ] }, "total_items": 3 } ``` ### GET /public/v1/analytics/trending/coldkeys/ Retrieves a list of trending coldkeys based on page view analytics. This can help in identifying wallets that are currently of high interest to the community. #### Parameters - **limit** (query, integer, optional) Number of items to return (1-50). #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Trending coldkeys data. Content-Type: `application/json` Example (Example): ```json { "analytics_available": true, "data": [ { "entity_type": "coldkeys", "entity_id": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty", "views": 900, "percentage_change": -5.2 } ], "total_items": 1 } ``` ### GET /public/v1/analytics/trending/subnets/ Retrieves a list of trending subnets based on page view analytics. This endpoint provides a focused view of the most popular subnets, helping to identify which are gaining the most attention. #### Parameters - **limit** (query, integer, optional) Number of items to return (1-50). #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Trending subnets data. Content-Type: `application/json` Example (Example): ```json { "analytics_available": true, "data": [ { "entity_type": "subnets", "entity_id": "1", "views": 1500, "percentage_change": 25.5 }, { "entity_type": "subnets", "entity_id": "3", "views": 1100, "percentage_change": 10.0 } ], "total_items": 2 } ``` ### GET /public/v1/analytics/trending/validators/ Retrieves a list of trending validators based on page view analytics. This is useful for identifying which validators are currently most viewed or researched by the community. #### Parameters - **limit** (query, integer, optional) Number of items to return (1-50). #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Trending validators data. Content-Type: `application/json` Example (Example): ```json { "analytics_available": true, "data": [ { "entity_type": "validators", "entity_id": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY", "views": 1200, "percentage_change": 15.0 } ], "total_items": 1 } ``` ### GET /public/v1/blocks/ Retrieves a paginated list of all blocks, ordered by height in descending order. This endpoint provides an overview of the most recent blocks on the chain. #### Parameters - **hash** (query, string, optional) - **height** (query, integer, optional) - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 6116422, "next": "http://api.example.com/public/v1/blocks/?limit=25&offset=25", "previous": null, "results": [ { "height": 6116422, "hash": "0x...", "parent_hash": "0x...", "state_root": "0x...", "extrinsics_root": "0x...", "timestamp": "2025-07-31T10:45:12+02:00", "spec_version": 298 } ] } ] } ``` ### GET /public/v1/blocks/{id}/ Retrieves detailed information for a specific block, identified by its height or hash. #### Parameters - **id** (path, string, **required**) A unique value identifying this block. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "height": 6116422, "hash": "0x...", "parent_hash": "0x...", "state_root": "0x...", "extrinsics_root": "0x...", "timestamp": "2025-07-31T10:45:12+02:00", "spec_version": 298 } ``` ### GET /public/v1/events/ Retrieves a paginated list of all events, ordered by block number and event index in descending order. This endpoint supports filtering by various parameters such as block, hotkey, coldkey, subnet, and more. #### Parameters - **block** (query, integer, optional) Filter by block number. - **category** (query, string, optional) Filter by category. - **coldkey** (query, string, optional) Filter by coldkey address. - **event_idx** (query, integer, optional) Filter by event index. - **expand** (query, string, optional) Expand related fields. Available options: `block`, `extrinsic`. - **extrinsic_idx** (query, integer, optional) Filter by extrinsic index. - **hotkey** (query, string, optional) Filter by hotkey address. - **limit** (query, integer, optional) Number of results to return per page. - **method** (query, string, optional) Filter by method. - **offset** (query, integer, optional) The initial index from which to return the results. - **subnet** (query, integer, optional) Filter by subnet ID. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 1000, "next": "http://api.example.com/public/v1/events/?limit=25&offset=25", "previous": null, "results": [ { "id": "12345", "block_number": 6116422, "event_idx": 1, "extrinsic_idx": 2, "method": "Transfer", "category": "balances", "data": "..." } ] } ] } ``` ### GET /public/v1/events/{id}/ Retrieves detailed information for a specific event, identified by its ID. The response can be expanded to include related block and extrinsic data. #### Parameters - **expand** (query, string, optional) Expand related fields. Available options: `block`, `extrinsic`. - **id** (path, string, **required**) A unique value identifying this event. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "id": "12345", "block_number": 6116422, "event_idx": 1, "extrinsic_idx": 2, "method": "Transfer", "category": "balances", "data": "...", "block": { "height": 6116422, "hash": "0x...", "timestamp": "2025-07-31T10:45:12+02:00" }, "extrinsic": { "id": "67890", "hash": "0x...", "method": "transfer", "section": "balances" } } ``` ### GET /public/v1/extrinsics/ List extrinsics with optional filters and pagination. Returns recent 5000 extrinsics when no filters applied for optimal performance. Supports extensive filtering by block, coldkey, hotkey, subnet, call module/function/name, and success flag. Use 'hotkey' parameter for optimized queries when filtering by hotkey address. Results include basic extrinsic data with first call information. #### Parameters - **block** (query, string, optional) Filter by block ID - **call_function** (query, string, optional) Filter by call function - **call_module** (query, string, optional) Filter by call module - **call_name** (query, string, optional) Filter by call name - **coldkey** (query, string, optional) Filter by coldkey address - **expand** (query, string, optional) Expand related fields. Available options: `events`. - **hash** (query, string, optional) Filter by extrinsic hash - **hotkey** (query, string, optional) Filter by hotkey address - **limit** (query, integer, optional) Number of items to return - **offset** (query, integer, optional) Starting point for pagination - **subnet** (query, integer, optional) Filter by subnet ID - **success** (query, boolean, optional) Filter by success flag #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 5000, "next": "http://api.example.com/public/v1/extrinsics/?limit=25&offset=25", "previous": null, "results": [ { "id": "4234567-3", "block_number": 4234567, "extrinsic_idx": 3, "timestamp": "2024-01-15T10:00:00Z", "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "success": true, "hash": "0x1234567890abcdef...", "call_module": "SubtensorModule", "call_function": "add_stake", "call_name": "add_stake" } ] } ] } ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/extrinsics/{id}/ Retrieve detailed information for a specific extrinsic by ID. Returns complete extrinsic data including block info, all calls, events, and associated accounts. Extrinsic ID format: {block_number}-{extrinsic_idx} (e.g., '4234567-3'). #### Parameters - **expand** (query, string, optional) Expand related fields. Available options: `events`. - **id** (path, string, **required**) A unique value identifying this extrinsic. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "id": "4234567-3", "block_number": 4234567, "extrinsic_idx": 3, "timestamp": "2024-01-15T10:00:00Z", "address": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "success": true, "hash": "0x1234567890abcdef...", "block": { "id": 4234567, "hash": "0xabcdef1234567890...", "timestamp": "2024-01-15T10:00:00Z" }, "calls": [ { "module": "SubtensorModule", "function": "add_stake", "name": "add_stake", "args": { "hotkey": "5HYk8J9PErYqpmV...", "amount": "1000" } } ], "proxy_error": { "value": { "error": "0x15000000", "index": 7 }, "__kind": "Module", "decoded": { "errorName": "HotKeyAlreadyRegisteredInSubNet", "errorIndex": 21, "palletName": "SubtensorModule", "palletIndex": 7, "errorDescription": "The caller is requesting registering a neuron which already exists in the active set." } }, "events": [ { "id": 98765, "event_idx": 12, "module": "SubtensorModule", "name": "StakeAdded" } ], "extrinsic_accounts": [ { "account": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "account_type": "signer" } ], "tao_price_usd": 452.35, "tao_price_eur": 415.12 } ``` **404** - Resource not found **500** - Internal server error ### GET /public/v1/extrinsics/staking-activity/ List stake activity using denormalized stake_activity table for comprehensive tracking. Returns all staking movements with from/to details for coldkeys, hotkeys, and subnets. Enriched with TAO price in USD at the time of activity for value calculation. Supports extensive filtering by block, coldkey, hotkey, subnet, signer, function, time range, and alpha amount. Use 'exclude_function' to filter out specific staking functions. Optimized with EXPLAIN-based count estimation for large result sets. #### Parameters - **FROM** (query, string, optional) Start time (ISO datetime) - **TO** (query, string, optional) End time (ISO datetime) - **alpha_gte** (query, number, optional) Alpha amount >= value (from_alpha_amount or to_alpha_amount) - **alpha_lte** (query, number, optional) Alpha amount <= value (from_alpha_amount or to_alpha_amount) - **block_number** (query, integer, optional) Filter by exact block number - **coldkey** (query, string, optional) Filter by coldkey (matches from_coldkey or to_coldkey) - **exclude_function** (query, string, optional) Comma-separated list of staking functions to exclude - **from_netuid** (query, integer, optional) Filter by source subnet ID (exact match on from_netuid) - **function** (query, string, optional) Comma-separated list of staking functions to include - **hotkey** (query, string, optional) Filter by hotkey (matches from_hotkey or to_hotkey) - **is_evm** (query, boolean, optional) Filter by EVM origin - **is_proxy** (query, boolean, optional) Filter by proxy execution - **limit** (query, integer, optional) Number of items to return - **offset** (query, integer, optional) Starting point for pagination - **signer** (query, string, optional) Filter by signer coldkey - **subnet** (query, integer, optional) Filter by subnet ID (matches from_netuid or to_netuid) - **success** (query, boolean, optional) Filter by success flag - **to_netuid** (query, integer, optional) Filter by destination subnet ID (exact match on to_netuid) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 50000, "next": "http://api.example.com/public/v1/extrinsics/stake-activity/?limit=25&offset=25", "previous": null, "results": [ { "id": 12345, "block_number": 4234567, "extrinsic_idx": 3, "timestamp": "2024-01-15T10:00:00Z", "function": "add_stake", "success": true, "signer": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "from_coldkey": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHp...", "to_coldkey": null, "from_hotkey": null, "to_hotkey": "5HYk8J9PErYqpmV...", "from_netuid": null, "to_netuid": 1, "from_alpha_amount": null, "to_alpha_amount": "1000.5", "tao_price_usd": 450.75, "tao_price_eur": 413.65, "usd_value": 451251.375 } ] } ] } ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/extrinsics/staking-activity/histogram/ Histogram distribution for a staking activity numeric field. #### Parameters - **buckets** (query, integer, optional) Number of buckets (2-100, default 20) - **clip_max** (query, number, optional) Exclude values above this - **clip_min** (query, number, optional) Exclude values below this - **field** (query, string, **required**) Numeric field to histogram - **round** (query, integer, optional) Round bucket values to N decimals (0=int) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "object" } ``` ### GET /public/v1/extrinsics/staking-activity/pressure/ Get buy/sell pressure time series for stake activity. Returns aggregated TAO amounts per time bucket (hourly or daily). Buy pressure = stake flowing INTO subnets (to_tao_amount). Sell pressure = stake flowing OUT OF subnets (from_tao_amount). Only successful transactions are counted. Intra-subnet move_stake/transfer_stake operations are excluded to avoid double-counting. Results are cached per bucket for optimal performance with dynamic time ranges. Values are in RAO (1 TAO = 1e9 RAO). When 'subnet' parameter is provided, response includes 'ema_price' field with volume-weighted average alpha price per bucket. #### Parameters - **FROM** (query, string, **required**) Start time in ISO 8601 format (e.g., '2025-01-01T00:00:00Z'). Will be snapped to bucket boundary. - **TO** (query, string, **required**) End time in ISO 8601 format (e.g., '2025-01-02T00:00:00Z'). Will be snapped to bucket boundary. - **bucket** (query, string, optional) Time bucket size: '1h' (hourly, default) or '1d' (daily). Values are aggregated per bucket. - **side** (query, string, **required**) Pressure side: 'buy' (stake flowing into subnets) or 'sell' (stake flowing out of subnets). Alias: 'type' (also accepted). - **subnet** (query, integer, optional) Filter by subnet ID. If omitted, returns total pressure across all subnets. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example(total)): ```json [ { "timestamp": 1704067200000, "value": 1500000000000 }, { "timestamp": 1704070800000, "value": 2300000000000 }, { "timestamp": 1704074400000, "value": 1800000000000 } ] ``` Example (Example(withSubnetAndPrice)): ```json [ { "timestamp": 1704067200000, "value": 1500000000000, "ema_price": 0.4523 }, { "timestamp": 1704070800000, "value": 2300000000000, "ema_price": 0.4587 }, { "timestamp": 1704074400000, "value": 1800000000000, "ema_price": 0.4551 } ] ``` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/extrinsics/swap-calls/ Swap-related calls: add_liquidity, remove_liquidity, modify_position. #### Parameters - **block_number** (query, integer, optional) Filter by block number - **coldkey** (query, string, optional) Filter by coldkey address - **extrinsic_id** (query, string, optional) Filter by extrinsic ID - **limit** (query, integer, optional) Number of items to return - **offset** (query, integer, optional) Starting point for pagination - **subnet** (query, integer, optional) Filter by subnet ID (args.netuid) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` **400** - Invalid query parameters **500** - Internal server error ### GET /public/v1/general/constants/ Retrieves the latest chain constants by block number. These constants define the fundamental parameters of the blockchain. The `type` parameter can be used to filter for specific constant types, such as balances, proxy, or swap. #### Parameters - **type** (query, string, optional) Filter to return only a specific constant type: balances, proxy, subtensor_module, or swap. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "id": "6608228", "block_number": 6608228, "spec_version": 326, "timestamp": "2025-10-07T16:08:36+02:00", "balances": { "maxHolds": null, "maxLocks": 50, "maxFreezes": 50, "maxReserves": 50, "existentialDeposit": "500" }, "proxy": { "maxPending": 75, "maxProxies": 20, "proxyDepositBase": "60000000", "proxyDepositFactor": "33000000", "announcementDepositBase": "36000000", "announcementDepositFactor": "68000000" }, "subtensor_module": { "alphaLow": 45875, "alphaHigh": 58982, "initialRho": 10, "initialBurn": "100000000", "keySwapCost": "100000000", "initialKappa": 32767, "initialTempo": 360, "liquidAlphaOn": false, "hotkeySwapCost": null, "initialMaxBurn": "100000000000", "initialMinBurn": "500000", "initialMinTake": null, "initialIssuance": "0", "initialTaoWeight": "971718665099567868", "initialDifficulty": "10000000", "maxBurnLowerBound": "100000000", "minBurnUpperBound": "1000000000", "initialDefaultTake": null, "initialSubnetLimit": null, "initialTxRateLimit": "1000", "durationOfStartCall": "50400", "initialBondsPenalty": 65535, "initialBondsResetOn": false, "initialPruningScore": 65535, "keySwapOnSubnetCost": "1000000", "initialEmissionValue": 0, "initialMaxDifficulty": "4611686018427387903", "initialMinDifficulty": "10000000", "initialActivityCutoff": 5000, "initialBaseDifficulty": null, "initialImmunityPeriod": 4096, "initialMaxAllowedUids": 4096, "initialMinAllowedUids": 64, "initialSubnetOwnerCut": 11796, "initialAdjustmentAlpha": "0", "initialMaxChildKeyTake": 11796, "initialMaxWeightsLimit": 1000, "initialMinChildKeyTake": 0, "initialMinDelegateTake": 0, "initialNetworkMaxStake": null, "initialScalingLawPower": 50, "initialNetworkRateLimit": "7200", "initialServingRateLimit": "50", "maxImmuneUidsPercentage": 80, "initialMinAllowedWeights": 1024, "initialValidatorEpochLen": null, "initialValidatorPruneLen": "1", "initialWeightsVersionKey": "0", "initialAdjustmentInterval": 100, "initialBondsMovingAverage": "900000", "initialNetworkMinLockCost": "1000000000000", "initialValidatorBatchSize": null, "hotkeySwapOnSubnetInterval": "36000", "initialDefaultChildKeyTake": 0, "initialDefaultDelegateTake": 11796, "initialHotkeyEmissionTempo": null, "initialMaxAllowedValidators": 128, "initialValidatorSequenceLen": null, "initialAlphaSigmoidSteepness": 1000, "initialEmaPriceHalvingPeriod": "201600", "initialNetworkImmunityPeriod": "1296000", "initialNetworkMinAllowedUids": null, "initialSynergyScalingLawPower": null, "initialTargetStakesPerInterval": null, "initialTxChildKeyTakeRateLimit": "216000", "initialTxDelegateTakeRateLimit": "216000", "initialValidatorEpochsPerReset": null, "initialMaxRegistrationsPerBlock": 1, "initialValidatorExcludeQuantile": null, "initialValidatorLogitsDivergence": null, "initialRaoRecycledForRegistration": "0", "initialColdkeySwapScheduleDuration": 36000, "leaseDividendsDistributionInterval": 100, "initialNetworkLockReductionInterval": "100800", "initialColdkeySwapRescheduleDuration": 7200, "initialSenateRequiredStakePercentage": "1", "initialTargetRegistrationsPerInterval": 2, "initialDissolveNetworkScheduleDuration": 36000 }, "swap": { "maxFeeRate": 10000, "protocolId": "0x74656e2f73776170", "maxPositions": 100, "minimumReserve": "1000000", "minimumLiquidity": "1000" } } ``` ### GET /public/v1/general/global-search/ Performs a global search across the platform for a given query string. The search covers various entities, including blocks, subnets, validators, and coldkeys. #### Parameters - **q** (query, string, optional) Search query string. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json [ { "type": "coldkey", "value": "5FqACMtcegZxxopgu1g7TgyrnyD8skurr9QDPLPhxNQzsThe" }, { "type": "hotkey", "value": "5FqACMtcegZxxopgu1g7TgyrnyD8skurr9QDPLPhxNQzsThe" } ] ``` ### GET /public/v1/general/senate-members/ Retrieves the current list of senate members. The data is fetched from the latest block's storage and includes the block number, spec version, and a list of member addresses. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "members": [ "5CsvRJXuR955WojnGMdok1hbhffZyB4N5ocrv82f3p5A2zVp", "5D4gEn5S422dTGR5NJJKZ93FNV6hDmfwDPfxFNgcoVnUkZ4f", "5DXdHixxtCvoa6GHKs2Jgrdzc61882Ftx1zN2sYFQuwgL1S1", "5Dd8gaRNdhm1YP7G1hcB1N842ecAUQmbLjCRLqH5ycaTGrWv", "5FxcZraZACr4L78jWkcYe3FHdiwiAUzrKLVtsSwkvFobBKqq", "5Fy3MjrdKRvUWSuJa4Yd5dmBYunzKNmXnLcvP22NfaTvhQCY", "5G3wMP3g3d775hauwmAZioYFVZYnvw6eY46wkFy8hEWD5KP3", "5GKH9FPPnWSUoeeTJp19wVtd84XqFW4pyK2ijV2GsFbhTrP1", "5GP7c3fFazW9GXK8Up3qgu2DJBk8inu4aK9TZy3RuoSWVCMi", "5Gq2gs4ft5dhhjbHabvVbAhjMCV2RgKmVJKAFCUWiirbRT21", "5HK5tp6t2S59DywmHRWPBVJeJ86T61KjurYqeooqj8sREpeN", "5HmkM6X1D3W3CuCSPuHhrbYyZNBy2aGAiZy9NczoJmtY25H7" ], "required_stake_percentage": 1 } ``` ### GET /public/v1/general/staking-constants/ Retrieves the current staking constants from the Subtensor repository. These constants define the rules and parameters of the staking mechanism. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (Example): ```json { "DefaultMinStake": 500000, "DefaultFeeRate": 33 } ``` ### GET /public/v1/market/candle-data/ Get OHLCV candle data for TAO cryptocurrency. Query Parameters: - period: Interval for OHLCV data (default: 1h) Valid values: 5m, 15m, 1h, 4h, 1d - from_timestamp: ISO 8601 timestamp to start returning data from (optional, defaults to now-30d) - to_timestamp: ISO 8601 timestamp to stop returning data (optional) If from/to are not provided, data is fetched for the last 30 days. #### Parameters - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/market/chart-data/ Get chart data for a cryptocurrency. Query Parameters: - coin_id: CoinMarketCap coin ID (default: 22974 for TAO) - span: Time range for chart data (default: 1D) #### Parameters - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/market/market-data/ Returns the market data for the block with id=1. #### Parameters - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/ #### Parameters - **limit** (query, integer, optional) Number of results to return per page. - **netuid** (query, integer, optional) - **offset** (query, integer, optional) The initial index from which to return the results. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/{id}/ Retrieve subnet detail. Tries pure Redis first (zero DB queries), then DB fallback. #### Parameters - **id** (path, string, **required**) A unique value identifying this subnet. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/{id}/candle-chart/ Get candlestick price data for a specific subnet Query parameters: - period: 5m, 1h (default), 1d - from_timestamp: ISO datetime for start time - to_timestamp: ISO datetime for end time #### Parameters - **id** (path, string, **required**) A unique value identifying this subnet. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/{id}/candle-chart-compact/ Get compact candlestick price data for a specific subnet Returns list of arrays: [ts, block_number, o, h, l, c, v, start_volume, tao_price] with 4-decimal precision for floats. When the coldkey query param is provided, a 10th element lists that signer's staking transactions for the candle. #### Parameters - **id** (path, string, **required**) A unique value identifying this subnet. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/{id}/line-chart/ Get price timeseries data for a specific subnet #### Parameters - **id** (path, string, **required**) A unique value identifying this subnet. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/burn/ #### Parameters - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/burn/{id}/ Retrieve subnet burn chart data by subnet_id #### Parameters - **id** (path, string, **required**) A unique value identifying this subnet burn chart. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/historical/{field_name}/ #### Parameters - **field_name** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "object", "additionalProperties": {} } ``` ### GET /public/v1/subnets/info/ Overview & compressed series for subnets info - Optimized version #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/network-lock-cost/ Delta-only dataset for network last lock cost chart #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/neurons/ #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "object", "additionalProperties": {} } ``` ### GET /public/v1/subnets/neurons/{id}/ Retrieve neuron state data by subnet_id #### Parameters - **id** (path, string, **required**) A unique value identifying this neuron state. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "object", "additionalProperties": {} } ``` ### GET /public/v1/subnets/sum-candle-chart/ Get candlestick price data for sum of all subnets Query parameters: - period: 1m, 5m, 15m, 1h (default), 4h, 1d, 1w - from_timestamp: ISO datetime for start time - to_timestamp: ISO datetime for end time #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/sum-candle-chart-compact/ Get compact candlestick price data for sum of all subnets Query parameters: - period: 1m, 5m, 15m, 1h (default), 4h, 1d, 1w - from_timestamp: ISO datetime for start time - to_timestamp: ISO datetime for end time Returns list of arrays: [ts, block_number, o, h, l, c, v, start_volume, tao_price] with 4-decimal precision for floats. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/sum-of-sn-prices/ Delta-only dataset for sum of subnet prices chart #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/table/ Subnet table data with pricing information (from Redis cache) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/tokenomics/ s Get tokenomics data for all subnets #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/uids/ Get UIDs for all subnets as lists of "coldkey-hotkey" strings. Each inner list represents one subnet, ordered by UID. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/validators/ Get validators for all subnets with their performance and apy Query parameters from ValidatorSubnetFilter: - subnet: filter by specific subnet ID - hotkey: partial search on hotkey field - apy_gte/lte: numeric range filters for apy - alpha_stake_gte/lte: numeric range filters for alpha_stake - tao_stake_gte/lte: numeric range filters for tao_stake #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/weekly-prices/ #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/subnets/weights/{id}/ Retrieve a specific weights data by netuid #### Parameters - **id** (path, string, **required**) A unique value identifying this weights data. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/stakes/stake-added/ #### Parameters - **block** (query, string, optional) - **event** (query, string, optional) - **hotkey** (query, string, optional) - **id** (query, string, optional) - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. - **subnet** (query, string, optional) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/stakes/stake-added/{id}/ #### Parameters - **id** (path, string, **required**) A unique value identifying this stake added transaction. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/stakes/stake-moved/ #### Parameters - **block** (query, string, optional) - **destination_hotkey** (query, string, optional) - **event** (query, string, optional) - **id** (query, string, optional) - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. - **origin_hotkey** (query, string, optional) - **subnet_from** (query, string, optional) - **subnet_to** (query, string, optional) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/stakes/stake-moved/{id}/ #### Parameters - **id** (path, string, **required**) A unique value identifying this stake moved transaction. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/stakes/stake-removed/ #### Parameters - **block** (query, string, optional) - **event** (query, string, optional) - **hotkey** (query, string, optional) - **id** (query, string, optional) - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. - **subnet** (query, string, optional) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/stakes/stake-removed/{id}/ #### Parameters - **id** (path, string, **required**) A unique value identifying this stake removed transaction. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/transfers/ DRF ViewSet mixin: ``GET .../histogram/?field=`` Optional: clip_min, clip_max, round, buckets. #### Parameters - **amount_gte** (query, integer, optional) - **amount_lte** (query, integer, optional) - **block** (query, string, optional) - **coldkey** (query, string, optional) - **event** (query, string, optional) - **from_coldkey** (query, string, optional) - **id** (query, string, optional) - **limit** (query, integer, optional) Number of results to return per page. - **offset** (query, integer, optional) The initial index from which to return the results. - **subnet** (query, number, optional) - **success** (query, boolean, optional) - **to_coldkey** (query, string, optional) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/transfers/{id}/ DRF ViewSet mixin: ``GET .../histogram/?field=`` Optional: clip_min, clip_max, round, buckets. #### Parameters - **id** (path, string, **required**) A unique value identifying this transfer. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/transactions/transfers/histogram/ Get histogram distribution for a numeric field. Returns array of [bucket_value, count] pairs. #### Parameters - **buckets** (query, integer, optional) Number of buckets (2-100, default 20) - **clip_max** (query, number, optional) Exclude values above this - **clip_min** (query, number, optional) Exclude values below this - **field** (query, string, **required**) Numeric field to histogram - **round** (query, integer, optional) Round bucket values to N decimals (0=int) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "object" } ``` ### GET /public/v1/validators/ List method is disabled for this endpoint. #### Parameters - **hotkey** (query, string, optional) - **limit** (query, integer, optional) Number of results to return per page. - **name** (query, string, optional) - **offset** (query, integer, optional) The initial index from which to return the results. - **ordering** (query, string, optional) Which field to use when ordering the results. - **tao_apy_gte** (query, number, optional) - **tao_apy_lte** (query, number, optional) - **total_alpha_staked_gte** (query, integer, optional) - **total_alpha_staked_lte** (query, integer, optional) - **total_tao_staked_gte** (query, integer, optional) - **total_tao_staked_lte** (query, integer, optional) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` ### GET /public/v1/validators/{hotkey}/ Retrieves detailed information about a specific validator by hotkey. Includes metrics, APY data across subnets, staking information, validator fee, daily rewards, and identity data if available. #### Parameters - **hotkey** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json { "hotkey": "some-hotkey", "coldkey": "some-coldkey", "rank": 1, "total_staked": 1000000000000, "total_tao_staked": 800000000000, "total_alpha_staked": 200000000000, "dominance": 5.5, "tao_apy": 12.5, "stakers_count": 150, "validator_fee": 18.0, "daily_staker_rewards": 1250.5, "daily_validator_reward": 250.5, "can_increase_fee": false, "registered_at": "2024-01-15T10:30:00Z", "name": "Validator Name", "apy": { "average_apy": 15.2, "subnets": { "1": 12.5, "3": 18.0 } }, "coldkey_identity": { "name": "Validator", "url": "https://example.com", "github_repo": "user/repo", "image": "https://example.com/image.png", "discord": "username", "description": "Validator description", "additional": {} } } ``` **404** - Validator not found ### GET /public/v1/validators/{hotkey}/apy-chart/{subnet}/ Retrieves historical APY data for a specific validator on a specific subnet. Returns time-series data points showing how the APY has changed over time. Supports different time spans (1D, 1W, 1M, 1Y, ALL). #### Parameters - **hotkey** (path, string, **required**) - **span** (query, string, optional) Time span filter. Available values: 1D, 1W, 1M, 1Y, ALL - **subnet** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - No response body **400** - Invalid subnet or span parameter ### GET /public/v1/validators/{hotkey}/childkeys/ Retrieves child validators for a specific parent validator. Shows all validators to which this parent delegates stake, grouped by subnet with detailed metrics including APY, stake amounts, and performance data. Supports filtering by child hotkey and subnet. #### Parameters - **child_hotkey** (query, string, optional) Filter by child hotkey (partial match) - **hotkey** (path, string, **required**) - **limit** (query, integer, optional) Number of items to return per page. - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. - **ordering** (query, string, optional) Field to order by. Prefix with '-' for descending order. Available fields: subnet, apy, alpha_stake, validator_dominance, child_count - **subnet** (query, integer, optional) Filter by subnet ID #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 50, "next": "http://api.example.com/validators/somehotkey/childkeys/?limit=25&offset=25", "previous": null, "results": [ { "subnet": 1, "child_count": 5, "apy": 12.5, "alpha_stake": 500000.5, "validator_dominance": 0.15, "childkeys": [ { "uid": 100, "subnet": 1, "hotkey": "child-hotkey", "owner": "child-coldkey", "alpha_stake": 100000000000, "apy": 12.5, "validator_fee": 18.0, "proportion": 100.0, "staked_percentage": 20.0 } ] } ] } ] } ``` ### GET /public/v1/validators/{hotkey}/parents/ Retrieves parent validators (delegators) for a specific child validator. Returns all subnets where this validator has parent relationships, showing who delegates stake to this validator and their proportions. Optionally filter by subnet ID to see parents for a specific subnet only. #### Parameters - **hotkey** (path, string, **required**) - **subnet** (query, integer, optional) Filter by subnet ID (optional). If provided, only returns parent data for the specified subnet. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ [ { "hotkey": "some-hotkey", "subnet": 51, "stake_weight": 14259, "root_stake": 13519, "alpha_stake": 242291219023689, "take": 0.0, "delegators": [ { "hotkey": "some-hotkey", "coldkey": "some-coldkey", "root_stake": 35689755620484, "alpha_stake": 28667571371, "take": 0.0, "proportion": 100.0 }, { "hotkey": "some-hotkey", "coldkey": "some-coldkey", "root_stake": 788519144393891, "alpha_stake": 149785183350405, "take": 18.0, "proportion": 20.0 } ] } ] ] } ``` **400** - Invalid subnet parameter **404** - Validator not found ### GET /public/v1/validators/{hotkey}/stake-allocation/ Retrieves the stake allocation distribution across subnets for a specific validator. Shows how the validator's stake is distributed across different subnets with percentages. #### Parameters - **hotkey** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ [ { "subnet": 1, "alpha_stake": 500000000000, "staked_percentage": 50.0, "apy": 12.5 }, { "subnet": 3, "alpha_stake": 300000000000, "staked_percentage": 30.0, "apy": 15.0 } ] ] } ``` ### GET /public/v1/validators/{hotkey}/stakers-histogram/ Histogram distribution of staker amounts for a specific validator. #### Parameters - **buckets** (query, integer, optional) Number of buckets (2-100, default 20) - **clip_max** (query, number, optional) Exclude values above this - **clip_min** (query, number, optional) Exclude values below this - **field** (query, string, **required**) Numeric field to histogram - **hotkey** (path, string, **required**) - **round** (query, integer, optional) Round bucket values to N decimals (0=int) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "object" } ``` ### GET /public/v1/validators/{hotkey}/stakers-table/ Retrieves a paginated list of all stakers (nominators) delegating to a specific validator. Shows coldkey addresses, amounts staked, percentages, and subnet distribution. Supports filtering by coldkey, subnet, and stake amounts. #### Parameters - **coldkey** (query, string, optional) Filter by nominator coldkey (partial match) - **hotkey** (path, string, **required**) - **limit** (query, integer, optional) Number of items to return per page. - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. - **ordering** (query, string, optional) Field to order by. Prefix with '-' for descending order. Available fields: rank, percentage, total_staked, tao_staked, alpha_staked - **subnet** (query, integer, optional) Filter by subnet ID #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 150, "next": "http://api.example.com/validators/somehotkey/stakers-table/?limit=25&offset=25", "previous": null, "results": [ { "rank": 1, "nominator_coldkey": "some-coldkey", "amount": 5000000000000, "alpha_staked_in_tao": 4500000000000, "tao_staked_subnet_0": 4500000000000, "percentage": 10.5, "subnets": [ 0, 1, 3 ] } ] } ] } ``` ### GET /public/v1/validators/{hotkey}/staking-chart/ Retrieves historical staking data for a specific validator over time. Returns time-series data points showing stake amount, block number, timestamp, and TAO price (USD) at each point. Supports filtering by subnet (shows subnet-specific stake) and time span (1D, 1W, 1M, 1Y, ALL). If no subnet is specified, returns total stake across all subnets. #### Parameters - **hotkey** (path, string, **required**) - **span** (query, string, optional) Time span filter for historical data. Available values: 1D, 1W, 1M, 1Y, ALL - **subnet** (query, integer, optional) Subnet ID to filter by (optional). If omitted, returns total stake across all subnets. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json [ [ { "timestamp": "2024-01-15T10:30:00Z", "block_number": 4234567, "value": 1000000000000, "tao_price_usd": 450.25, "tao_price_eur": 413.2 }, { "timestamp": "2024-01-16T10:30:00Z", "block_number": 4235000, "value": 1050000000000, "tao_price_usd": 452.5, "tao_price_eur": 415.26 } ] ] ``` **400** - Invalid subnet or hotkey parameter **500** - Error retrieving staking chart data ### GET /public/v1/validators/{hotkey}/subnet-monitor-table/ #### Parameters - **hotkey** (path, string, **required**) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "array", "items": {} } ``` ### GET /public/v1/validators/full/ Retrieves comprehensive validator data at the subnet level with filtering capabilities. Returns all validators with APY > 0, showing subnet-specific metrics including APY, stake amounts, validator fee, and staked percentage. Supports filtering by subnet, hotkey, APY range, and stake amounts. #### Parameters - **alpha_stake_gte** (query, number, optional) Filter validators with Alpha stake >= value - **alpha_stake_lte** (query, number, optional) Filter validators with Alpha stake <= value - **apy_gte** (query, number, optional) Filter validators with APY >= value - **apy_lte** (query, number, optional) Filter validators with APY <= value - **hotkey** (query, string, optional) Filter by validator hotkey (partial match) - **subnet** (query, integer, optional) Filter by subnet ID - **tao_stake_gte** (query, number, optional) Filter validators with TAO stake >= value - **tao_stake_lte** (query, number, optional) Filter validators with TAO stake <= value #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ [ { "id": "hotkey-1", "hotkey": "some-hotkey", "coldkey": "some-coldkey", "subnet": 1, "apy": 12.5, "alpha_stake": 100000000000, "tao_stake": 80000000000, "alpha_per_day": 150.25, "block_number": 4234567, "updated_at": "2024-01-15T10:30:00Z", "alpha_staked_in_tao": 90000000000, "staked_percentage": 5.5, "validator_fee": 18.0 }, { "id": "hotkey-3", "hotkey": "some-hotkey", "coldkey": "some-coldkey", "subnet": 3, "apy": 15.0, "alpha_stake": 50000000000, "tao_stake": 40000000000, "alpha_per_day": 200.5, "block_number": 4234567, "updated_at": "2024-01-15T10:30:00Z", "alpha_staked_in_tao": 45000000000, "staked_percentage": 3.2, "validator_fee": 18.0 } ] ] } ``` ### GET /public/v1/validators/full-compact/ Retrieves validator data in a lightweight, compact array format optimized for performance. Each validator is represented as an array: [subnet, hotkey, coldkey, apy, validator_fee, is_owner (optional)]. The is_owner flag (true) is appended only if the validator is the subnet owner. Supports same filtering as the full endpoint but with minimal data transfer. #### Parameters - **alpha_stake_gte** (query, number, optional) Filter validators with Alpha stake >= value - **alpha_stake_lte** (query, number, optional) Filter validators with Alpha stake <= value - **apy_gte** (query, number, optional) Filter validators with APY >= value - **apy_lte** (query, number, optional) Filter validators with APY <= value - **hotkey** (query, string, optional) Filter by validator hotkey (partial match) - **subnet** (query, integer, optional) Filter by subnet ID - **tao_stake_gte** (query, number, optional) Filter validators with TAO stake >= value - **tao_stake_lte** (query, number, optional) Filter validators with TAO stake <= value #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - No response body ### GET /public/v1/validators/histogram/ Get histogram distribution for a numeric field. Returns array of [bucket_value, count] pairs. #### Parameters - **buckets** (query, integer, optional) Number of buckets (2-100, default 20) - **clip_max** (query, number, optional) Exclude values above this - **clip_min** (query, number, optional) Exclude values below this - **field** (query, string, **required**) Numeric field to histogram - **round** (query, integer, optional) Round bucket values to N decimals (0=int) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Response schema: ```json { "type": "object" } ``` ### POST /public/v1/validators/subnet-apy-compare/ Return alpha APY rows (apy_current, apy_1d, apy_1w, apy_1m, apy_change_1d) for a list of (hotkey, netuid) positions. Intended for stake-rebalance UIs that need the current APY of every validator in a user's portfolio in one call. Response is grouped by netuid, matching the shape of /validators/subnets-top-apy/. Unknown (hotkey, netuid) positions are silently omitted. #### Request Body Content-Type: `application/json` #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json [ [ { "netuid": 5, "validators": [ { "hotkey": "hotkey1", "apy_current": 56.685084, "apy_1d": 232.796617, "apy_1w": 88.918282, "apy_1m": 78.287026, "apy_change_1d": -5.0828 } ] }, { "netuid": 7, "validators": [ { "hotkey": "hotkey2", "apy_current": 30.441165, "apy_1d": 1002.817965, "apy_1w": 566.121028, "apy_1m": 174.148393, "apy_change_1d": -11.1508 } ] } ] ] ``` **400** - Invalid request body ### GET /public/v1/validators/subnets-apy/{netuid}/ Retrieves all validator APY rows for a specific subnet from the `validator_apy` table. Returns the current APY and rolling 1D, 1W, and 1M APY values, along with the 1D APY change, for each validator in that subnet. #### Parameters - **limit** (query, integer, optional) Number of items to return per page. - **netuid** (path, integer, **required**) Subnet ID to return validator APY rows for - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. - **ordering** (query, string, optional) Field to order by. Prefix with '-' for descending order. Available fields: apy_current, apy_1d, apy_1w, apy_1m, apy_change_1d #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json [ { "count": 2, "next": null, "previous": null, "results": [ { "hotkey": "some-hotkey", "apy_current": 12.5, "apy_1d": 12.1, "apy_1w": 11.8, "apy_1m": 10.7, "apy_change_1d": -0.4 }, { "hotkey": "another-hotkey", "apy_current": 8.9, "apy_1d": 9.1, "apy_1w": 8.7, "apy_1m": 8.2, "apy_change_1d": 0.2 } ] } ] ``` ### GET /public/v1/validators/subnets-top-apy/ Retrieves top validator APY rows for the requested subnets from the `validator_apy` table. Returns one group per requested subnet, with validators sorted within each subnet by the selected APY window. #### Parameters - **limit** (query, integer, optional) Number of top validators to return per subnet - **ordering** (query, string, optional) APY field to order validators by within each subnet. Available values: apy_1d, -apy_1d, apy_1w, -apy_1w, apy_1m, -apy_1m - **subnets** (query, string, **required**) Comma-separated subnet IDs to return top APY rows for #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json [ [ { "netuid": 1, "validators": [ { "hotkey": "some-hotkey", "apy_current": 12.5, "apy_1d": 12.1, "apy_1w": 11.8, "apy_1m": 10.7, "apy_change_1d": -0.4 } ] }, { "netuid": 3, "validators": [ { "hotkey": "another-hotkey", "apy_current": 8.9, "apy_1d": 9.1, "apy_1w": 8.7, "apy_1m": 8.2, "apy_change_1d": 0.2 } ] } ] ] ``` **400** - Invalid subnets, limit or ordering parameter ### GET /public/v1/validators/table/ Retrieves a paginated list of all validators with filtering and ordering capabilities. Supports filtering by hotkey, name, stake amounts, and APY. Results can be ordered by various metrics. #### Parameters - **hotkey** (query, string, optional) Filter by validator hotkey (partial match) - **limit** (query, integer, optional) Number of items to return per page. - **name** (query, string, optional) Filter by validator name (partial match) - **offset** (query, integer, optional) The starting position of the query in relation to the complete set of items. - **ordering** (query, string, optional) Field to order by. Prefix with '-' for descending order. Available fields: tao_apy, tao_apy_1d, tao_apy_1w, tao_apy_1m, dominance, total_staked, total_tao_staked, total_alpha_staked, stakers_count, validator_fee, rank, total_subnets, average_apy, daily_staker_rewards, daily_validator_reward, block_number - **tao_apy_gte** (query, number, optional) Filter validators with TAO APY >= value - **tao_apy_lte** (query, number, optional) Filter validators with TAO APY <= value - **total_alpha_staked_gte** (query, number, optional) Filter validators with total Alpha staked >= value - **total_alpha_staked_lte** (query, number, optional) Filter validators with total Alpha staked <= value - **total_tao_staked_gte** (query, number, optional) Filter validators with total TAO staked >= value - **total_tao_staked_lte** (query, number, optional) Filter validators with total TAO staked <= value #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - Content-Type: `application/json` Example (ExampleResponse): ```json { "count": 123, "next": "http://api.example.org/accounts/?offset=400&limit=100", "previous": "http://api.example.org/accounts/?offset=200&limit=100", "results": [ { "count": 500, "next": "http://api.example.com/validators/table/?limit=25&offset=25", "previous": null, "results": [ { "hotkey": "some-hotkey", "name": "Validator Name", "tao_apy": 12.5, "tao_apy_1d": 12.1, "tao_apy_1w": 11.8, "tao_apy_1m": 10.7, "tao_apy_change_1d": -0.4, "dominance": 5.5, "total_staked": 1000000000000, "total_tao_staked": 800000000000, "total_alpha_staked": 200000000000, "stakers_count": 150, "validator_fee": 18.0, "subnet_stakes": { "1": 100000000000 } } ] } ] } ``` ### GET /public/v1/sse/blocks/ **Summary:** Block Stream Streams new block heights as they are processed. ### Connection Behavior 1. Client connects to SSE endpoint 2. Server validates API key and checks connection limits 3. Server sends current block height 4. Connection remains open for streaming updates (~12 seconds per block) ### Response Format Initial event and updates both contain the current block height: ```json {{ "height": 4567890 }} ``` ### Use Cases - Monitor blockchain progress - Trigger actions on new blocks - Display real-time block counter ### Connection Limits SSE endpoints are limited by concurrent connections per API key. Exceeding your plan's limit will result in a 429 (Too Many Requests) response. ### Example (JavaScript) ```javascript const eventSource = new EventSource( 'https://api.taomarketcap.com/public/v1/sse/blocks/', {{ headers: {{ 'Authorization': 'your-api-key' }} }} ); eventSource.onmessage = (event) => {{ const data = JSON.parse(event.data); console.log('New block:', data.height); }}; ``` #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream with block heights. Update frequency: ~12 seconds per block Content-Type: `text/event-stream` Response schema: ```json { "type": "object", "properties": { "height": { "type": "integer", "description": "Current block height", "example": 4567890 } } } ``` **401** - Unauthorized - Invalid or missing API key **403** - Forbidden - IP address not in allowlist **429** - Too Many Requests - Concurrent connection limit exceeded ### GET /public/v1/sse/subnets/table/ **Summary:** Subnet Table Stream Streams the complete subnet table with registration and activity data for up to 200 subnets. ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Full Event Example ```json { "type": "full", "data": [ { "subnet": 1, "symbol": "α", "name": "Apex", "price": 0.009461598984153307, "emission": 0.9220561, "circulating_supply": 3252346506459309, "marketcap": 30772.39840162996, "volume": 103.681974705, "is_active": true, "tao_liquidity": 22712285967190, "alpha_liquidity": 2400575740347686 } ] } ``` ### Delta Event Example ```json { "type": "delta", "changes": { "1": { "price": 0.009462, "volume": 104.5 } }, "added": [ { "subnet": 42, "name": "New Subnet", "price": 0.001234 } ] } ``` ### Key Fields - `subnet`: Subnet ID (netuid) - `price`: Current alpha token price in TAO - `emission`: Current emission rate (percentage) - `marketcap`: Market capitalization in USD - `volume`: 24h trading volume in USD - `tao_liquidity`: TAO in liquidity pool (in RAO) - `alpha_liquidity`: Alpha in liquidity pool (in RAO) ### Update Frequency Every block (~12 seconds) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream with subnet table data Content-Type: `text/event-stream` Response schema: ```json { "type": "string", "description": "Event stream data with full/delta/heartbeat events" } ``` **401** - Unauthorized - Invalid or missing API key **403** - Forbidden - IP address not in allowlist **429** - Too Many Requests - Concurrent connection limit exceeded ### GET /public/v1/sse/subnets/info/ **Summary:** Network Info Stream Streams general network statistics and metrics. ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Full Event Example ```json { "type": "full", "data": { "total_networks": 129, "network_rate_limit": 28800, "network_lock_cost": 361303739648, "sum_of_sn_burns": 28707662034601853 } } ``` ### Update Frequency Every block (~12 seconds) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream with network info Content-Type: `text/event-stream` Response schema: ```json { "type": "string" } ``` **401** - Unauthorized **403** - Forbidden **429** - Too Many Requests ### GET /public/v1/extrinsics/stream/ **Summary:** Extrinsics Stream Streams extrinsics in the same format as `GET /extrinsics/` with all existing query params supported (filters, pagination, expand). ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Behavior - Sends the latest page immediately (cached snapshot when available) - On each block, emits a delta (added/updated/removed) or a heartbeat - Heartbeat includes `block_number` every ~12s when no changes ### Examples Subscribe to a filtered feed: `/public/v1/extrinsics/stream/?coldkey=&limit=25&offset=0` #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream of extrinsic list data Content-Type: `text/event-stream` Response schema: ```json { "type": "string", "description": "Full/delta/heartbeat events for extrinsics" } ``` **401** - Unauthorized - Invalid or missing API key **403** - Forbidden - IP address not in allowlist **429** - Too Many Requests - Concurrent connection limit exceeded ### GET /public/v1/extrinsics/staking-activity/stream/ **Summary:** Stake Activity Stream Streams stake activity in the same shape as `GET /extrinsics/staking-activity/`, honoring all query params and pagination. ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Behavior - Immediate full payload on connect (cached when available) - Per-block delta or heartbeat with `block_number` #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream of stake activity data Content-Type: `text/event-stream` Response schema: ```json { "type": "string", "description": "Full/delta/heartbeat events for stake activity" } ``` **401** - Unauthorized - Invalid or missing API key **403** - Forbidden - IP address not in allowlist **429** - Too Many Requests - Concurrent connection limit exceeded ### GET /public/v1/transactions/transfers/stream/ **Summary:** Transfers Stream Streams transfers in the same format as `GET /transactions/transfers/`, including all filters and pagination. ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Behavior - Immediate full payload on connect (cached when available) - Per-block delta or heartbeat with `block_number` #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream of transfer data Content-Type: `text/event-stream` Response schema: ```json { "type": "string", "description": "Full/delta/heartbeat events for transfers" } ``` **401** - Unauthorized - Invalid or missing API key **403** - Forbidden - IP address not in allowlist **429** - Too Many Requests - Concurrent connection limit exceeded ### GET /public/v1/sse/subnets/tokenomics/ **Summary:** Tokenomics Stream Streams tokenomics data including supply, staking metrics, and distribution. ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Update Frequency Every block (~12 seconds) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream with tokenomics data Content-Type: `text/event-stream` Response schema: ```json { "type": "string" } ``` **401** - Unauthorized **403** - Forbidden **429** - Too Many Requests ### GET /public/v1/sse/subnets/weekly-prices/ **Summary:** Weekly Prices Stream Streams rolling 100-block price history for all subnets. ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Data Format - Keys are subnet IDs (as strings) - Values are arrays of 100 prices (floats) - Prices are ordered **newest first** (index 0 = most recent) - Each price represents the subnet's alpha price at that block ### Update Frequency Every block (~12 seconds) #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream with 100-block price history Content-Type: `text/event-stream` Response schema: ```json { "type": "string" } ``` **401** - Unauthorized **403** - Forbidden **429** - Too Many Requests ### GET /public/v1/sse/subnets/prices/ **Summary:** Subnet Prices Stream Streams current alpha prices for all subnets (real-time price updates). ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Data Format - Keys are subnet IDs (as strings) - Values are current alpha prices (floats) - `null` value indicates subnet was removed ### Update Frequency Real-time (when prices change). This stream uses a different Redis channel and may update more frequently than block-based streams. #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream with real-time subnet prices Content-Type: `text/event-stream` Response schema: ```json { "type": "string" } ``` **401** - Unauthorized **403** - Forbidden **429** - Too Many Requests ### GET /public/v1/sse/subnets/{netuid}/ **Summary:** Subnet Detail Stream Streams detailed information for a specific subnet. ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Key Fields - `netuid`: Subnet identifier - `blocks_until_next_epoch`: Blocks remaining until next epoch - `latest_snapshot`: Current subnet parameters from chain storage - `stake_threshold`: Minimum stake to be a validator (in TAO) ### Update Frequency Every block (~12 seconds) #### Parameters - **netuid** (path, integer, **required**) Subnet ID (netuid) to stream data for #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream with subnet detail data Content-Type: `text/event-stream` Response schema: ```json { "type": "string" } ``` **400** - Bad Request - Invalid subnet ID format **404** - Not Found - Subnet does not exist **401** - Unauthorized **403** - Forbidden **429** - Too Many Requests ### GET /public/v1/sse/subnets/neurons/{netuid}/ **Summary:** Neuron State Stream Streams the state of all neurons (validators and miners) in a specific subnet. ### Event Types All SSE endpoints use a consistent event structure with three event types: **1. Full Event (type: "full")** Sent immediately upon connection. Contains the complete current state. ```json { "type": "full", "data": { /* complete resource data */ } } ``` **2. Delta Event (type: "delta")** Sent when data changes. Contains only the fields that changed. ```json { "type": "delta", "changes": { /* only changed fields */ } } ``` **3. Heartbeat Event (type: "heartbeat")** Sent when a new block is processed but no data changed. ```json { "type": "heartbeat", "block_number": 1234567 } ``` ### Key Fields - `uid`: Unique neuron identifier within subnet - `hotkey`: Neuron's hotkey address - `owner`: Neuron's coldkey address (owner) - `alpha_stake`: Alpha tokens staked (in RAO) - `tao_stake`: TAO tokens staked (in RAO) - `emission`: Current emission rate (in RAO) - `validator_permit`: Whether neuron can validate - `is_validator`: Whether neuron is a validator - `is_miner`: Whether neuron is a miner - `apy`: Annual percentage yield ### Update Frequency Every block (~12 seconds) ### Use Cases - Monitor validator/miner performance - Track stake changes - Display subnet participant list - Alert on neuron registration/deregistration #### Parameters - **netuid** (path, integer, **required**) Subnet ID (netuid) to stream neuron data for #### Authentication Anonymous access by default (per-IP rate limits apply). For higher limits, send optional header: `Authorization: .` #### Responses **200** - SSE stream with neuron state data Content-Type: `text/event-stream` Response schema: ```json { "type": "string" } ``` **400** - Bad Request - Invalid subnet ID format **404** - Not Found - Subnet does not exist **401** - Unauthorized **403** - Forbidden **429** - Too Many Requests --- ### Contact **Name:** TMC **Website:** https://taomarketcap.com **License:** Proprietary