{
 "name": "Transit Fabric testnet stats API",
 "version": "v0",
 "network": "Bittensor testnet (test), subnet 611. Testnet only: nothing here is mainnet, and testnet numbers are not rewards.",
 "source": "Built only from data a strict majority of the subnet's validators serve identically (their attested peer directory, topology snapshot, validator set and route table), plus the testnet chain (UIDs, hotkeys, weights). Validated regions use each vantage validator's own probe batches, checked against its on-chain commitment. A value no majority agrees on is left out or null, never guessed.",
 "cadence": "A publisher reads the validators and the chain every 30 minutes and updates every endpoint at once. A window is 360 blocks, about 72 minutes.",
 "caching": "Responses are cached for up to 2 minutes. Poll no faster than once a minute; requests are rate-limited per client.",
 "privacy": "No internet address of any kind is published, and no coldkey. The one address-shaped value is each node's `fabric_address`: the overlay address derived from the node key; not routable on the internet; reveals nothing beyond the public node key. Location is country and first-level region only, looked up on the publisher in a local database, and only for addresses already public: a public node's endpoint in the validators' peer directory, and the seed nodes a tester release lists. Other nodes behind NAT have no location of their own. Fleets also get a UID-level `axon_location` from the axon address each UID publishes on chain: country and region only, never the address. Each node's `validated_region` comes from round-trip times alone, never an address: a circle centred on a whole degree, with a radius of tens to thousands of km. A node's `claimed_location` is looked up by each validator from the address its probe session comes from, on the validator itself: only country, first-level region and whole-degree coordinates leave it, never the address or a city, and the publisher refuses to publish if a city-level field appears. UIDs and hotkeys are public on chain, and so are node keys (in the validators' signed snapshot): `node` is a 16-hex-character prefix, `node_key` the full key. Requests to this API: we set no cookies, run no analytics and keep no request log. Your address is used only in memory as a rate-limit key (an IPv4 address, or an IPv6 /64) and is not stored by us. Cloudflare hosts the API and processes requests as our processor. Full policy: https://transitfabric.xyz/privacy.html",
 "privacy_policy": "https://transitfabric.xyz/privacy.html",
 "terms": "https://transitfabric.xyz/terms.html",
 "attribution": "IP Geolocation by DB-IP (https://db-ip.com), IP to City Lite database, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Only country, region and continent are used, plus whole-degree coordinates for claimed locations (looked up on the validators).",
 "validated_region": {
  "about": "Where a node can physically be, from the round trips validators measured to it, not from any address. Each vantage is a validator's probe agent, placed at its metro centre. For every node and vantage the publisher takes the smallest `vantage:<node>` round trip in the validators' committed probe batches over the last `windows` windows, turns it into a maximum great-circle distance, and intersects those spherical caps on a `grid_deg` grid. A validator that moves keeps its earlier samples at its old metro, and the window it moved in counts for neither.",
  "formula": "d_max_km = (rtt_ms / 2) x fiber_km_per_ms x slack + position_uncertainty_km",
  "property": "Delay can only be added (queueing, detours, forwarding, processing), never removed, so each cap is at least as large as the truth and the region can only grow. It can't place a node closer to a vantage than physics allows. A node can make its region bigger by delaying replies, never smaller or somewhere else, unless it answers different validators from different machines; then the caps may not meet.",
  "fiber_km_per_ms": 200,
  "slack": 1,
  "position_uncertainty_km": 50,
  "windows": 20,
  "grid_deg": 0.5,
  "min_vantages": 3,
  "relaxation": "When the caps don't meet, every cap's round-trip term is multiplied by 1.5 (fibre to light in vacuum), at most 2 times; `relaxed` gives the factor used. Past that the region is null with reason `inconsistent_rtts`.",
  "precision": "The centroid is rounded to 1 degree and the radius, measured from the rounded centroid, rounded up to 10 km. Countries are named only when the radius is at most 1000 km.",
  "vantages": [
   {
    "metro": "ewr",
    "name": "New York / New Jersey",
    "lat": 40.7,
    "lon": -74.2
   },
   {
    "metro": "fra",
    "name": "Frankfurt",
    "lat": 50.1,
    "lon": 8.7
   },
   {
    "metro": "nrt",
    "name": "Tokyo",
    "lat": 35.7,
    "lon": 139.7
   },
   {
    "metro": "sgp",
    "name": "Singapore",
    "lat": 1.3,
    "lon": 103.8
   }
  ],
  "fleet_anchors": "The project's own testnet nodes, at the metros their instances run in, also bound other nodes. A validator's `link:<s>:<d>` sample times one loop: its agent hands a probe to s, s forwards it to d, d echoes it back. When s is one of these anchors the packet really passes s, so the loop is at least d(V,s) + d(s,d) + d(d,V) long and d lies in the ellipse with foci s and the validator V. Only these known nodes anchor, never another operator's node (its place is unknown), only as the forwarding s (in `link:<d>:<s>` the unknown node could answer for s), and never for itself. Anchors and vantages are deduplicated per metro and count the same toward `min_vantages`; `anchors` in a region gives the anchor metros used.",
  "anchor_formula": "d(s,p) + d(p,V) <= rtt_ms x fiber_km_per_ms x slack - d(V,s) + 4 x position_uncertainty_km, using the smallest link RTT per (anchor metro, validator metro); never wider than the cap of rtt/2 around s",
  "anchors": [
   {
    "metro": "ams",
    "name": "Amsterdam",
    "lat": 52.4,
    "lon": 4.9
   },
   {
    "metro": "ewr",
    "name": "New York / New Jersey",
    "lat": 40.7,
    "lon": -74.2
   },
   {
    "metro": "lax",
    "name": "Los Angeles",
    "lat": 34.1,
    "lon": -118.2
   },
   {
    "metro": "lhr",
    "name": "London",
    "lat": 51.5,
    "lon": -0.1
   },
   {
    "metro": "nrt",
    "name": "Tokyo",
    "lat": 35.7,
    "lon": 139.7
   },
   {
    "metro": "ord",
    "name": "Chicago",
    "lat": 41.9,
    "lon": -87.6
   }
  ],
  "sources": "Round trips: the `vantage:<node>` samples (STAMP inside the probe session the node opened) and, for fleet anchors, the `link:<s>:<d>` samples of each validator's probe batch, read only when its bytes hash to the batch its manifest names and the manifest hashes to the commitment the validator's hotkey made on chain. Vantage and anchor positions: metro centres of the validators' and the project's own nodes' testnet instances (deploy/testnet-fleet/fleet.json). Countries: a 0.5 degree raster of Natural Earth 1:50m Admin 0 countries (public domain)."
 },
 "geo_claims": {
  "about": "Where the address a node's probe session comes from says the node is, checked against its `validated_region`. Each validator's probe agent looks up the source address of the WireGuard session the node opened to it in its own local copy of the DB-IP Lite City database and keeps only the country, the first-level region and the coordinates rounded to whole degrees; the address and the city never leave the validator, which serves the result unsigned on `GET /v0/geo-claims/<window>` of its store.",
  "agreement": "The publisher reads every validator's claims for the current and previous window (the current one wins) and keeps a node's claim only when a strict majority of the validators that report one for it agree on its (country, region). The point is the most common whole-degree point among those.",
  "check": "consistent when great_circle(claim point, validated_region centre) <= validated_region.radius_km + tolerance_km; else inconsistent",
  "tolerance_km": 150,
  "tolerance": "150 km covers the geolocation database placing an address at a nearby city or region centroid instead of the machine, and the whole-degree rounding of the claim (up to about 79 km).",
  "precision": "Country, first-level region (state or province) and whole-degree coordinates only: the same level as `axon_location`. Never a city, never an address.",
  "statuses": {
   "consistent": "The claim lies inside the validated region; `display_location` is the claim.",
   "inconsistent": "The claim lies outside it (a VPN, a proxy, a database error, or a node answering from elsewhere); `display_location` is the validated region only.",
   "unchecked": "A majority claim, but the node has no validated region to check it against; `display_location` is null.",
   "no_claim": "No majority claim (no validator saw the session's address, or they disagree); `display_location` is the validated region when there is one."
  },
  "why_both": "An address's location is precise but forgeable; the round-trip region can't be made smaller or moved, only bigger, but it is coarse. A claim is shown only where the measurements allow it.",
  "display_only": "Never a scoring input, never a reward or geography bonus: validators keep it out of every batch, hash and commitment."
 },
 "licence": "Data CC BY 4.0, with the attribution above for locations.",
 "endpoints": {
  "/v0/summary": {
   "about": "The current state in one object.",
   "fields": {
    "network": "Always \"test\".",
    "netuid": "The subnet, 611.",
    "generated_at": "When the publisher built this data (UTC, ISO 8601). Every endpoint shares it.",
    "update_every_minutes": "The publisher's cadence.",
    "window": "The current window, from the majority-agreed peer directory.",
    "block": "The block that directory was cut at.",
    "chain_block": "The chain head when the publisher read the chain.",
    "snapshot_window": "The window of the newest majority-agreed topology snapshot. It trails `window`: validators attest a snapshot after it is measured.",
    "snapshot_stale": "True when no majority served the same snapshot this run; node data is then from `snapshot_window`.",
    "nodes": "Nodes in that snapshot.",
    "nodes_with_capacity": "Of those, nodes with verified capacity above zero (passed a capacity test).",
    "fleets": "UIDs with at least one node in that snapshot.",
    "registered_uids": "UIDs registered on the subnet (nodes' operators, solvers and validators).",
    "validators": "Validators in the majority-agreed validator set.",
    "total_verified_capacity_mbps": "Sum of verified capacity over the snapshot's nodes, Mbps.",
    "nodes_located": "Nodes in the snapshot with a known coarse location of their own.",
    "nodes_with_validated_region": "Nodes in the snapshot with a `validated_region` (see `validated_region` in this document).",
    "geo_claims": "Nodes in the snapshot by `claim_status`: `{ consistent, inconsistent, unchecked, no_claim }` (see `geo_claims` in this document).",
    "fleets_with_axon_location": "Fleets with an `axon_location`.",
    "uids_with_axon_location": "Registered UIDs (any role) whose on-chain axon has a coarse location.",
    "agreement": "For each object read (snapshot, directory, validator_set, table): how many validators served the agreed copy (`agree`) of how many configured (`of`) and its window (the validator set's block). `status` is `majority` when all four have a strict majority, `partial` or `none`. `weights` gives, per mechanism, `all_agree`, `majority`, `no_majority` or `none_set` for the validators' on-chain weights.",
    "route_table": "The majority-agreed route table: its window, solver label and route count."
   }
  },
  "/v0/nodes": {
   "about": "Every node seen in a majority-agreed snapshot in the last 7 days (140 windows). Filter with `?uid=<n>`.",
   "fields": {
    "node": "First 16 hex characters of the node's ed25519 key (the short form).",
    "node_key": "The node's full ed25519 key, 64 hex characters, as `bwos` prints it. Public in the validators' signed snapshot.",
    "fabric_address": "The node's fabric address: the overlay address derived from the node key; not routable on the internet; reveals nothing beyond the public node key. `0xfc || SHA-512(SHA-512(node key))[0:15]`, so always in the fc00/8 block, as RFC 5952 text (`docs/specs/identity.md` \"Node address\"). Null only if `node_key` is not a 64-hex key.",
    "uid": "The UID the node is bound to.",
    "reachability": "`public` when the validators' attested peer directory lists a public endpoint for the node; `no_public_endpoint` when it is listed without one; null when it is not listed. It is not a NAT test: today the validators' directory lists no endpoint for any node (an endpoint is listed only once a validator has matched it to the node's own sessions, which no release does yet), so every listed node reads `no_public_endpoint`, servers with their own public address included.",
    "overlay_asn": "The node's own BGP ASN on the overlay, derived from its key and claimed in the validators' signed snapshot (`asn_claims`). It is not the ASN of the network the node is hosted in, which no validator publishes. Null when the snapshot has no claim for it.",
    "location": "`{ country, region, continent, source }` (ISO 3166-1 alpha-2 country, first-level region name, continent code) or null when unknown.",
    "axon_location": "The coarse location of the node's UID from that UID's on-chain axon, the same object as the fleet's `axon_location`. UID-level, not this node's location: the operator's nodes may be anywhere. Null when the UID serves no axon or a non-routable one.",
    "validated_region": "`{ lat, lon, radius_km, vantages, anchors, relaxed, country, countries, continent }`: the circle the node must be in, from validators' round trips (method under `validated_region` in this document). `lat`/`lon` is the centroid in whole degrees, `radius_km` holds the whole region, `vantages` the distinct metros used (validator vantages and fleet anchors together), `anchors` how many of those are fleet-anchor metros, `relaxed` the factor the caps were widened by (1 when not). `countries` lists every country the region touches and `country` is set when that is one, both only when `radius_km` is at most 1000 (else null); `continent` when the region touches one. Null when there is none; see `validated_region_reason`. Works for nodes behind NAT too.",
    "validated_region_reason": "Null when `validated_region` is set; otherwise `no_vantage_samples`, `fewer_than_3_vantages` or `inconsistent_rtts` (the caps don't meet even relaxed).",
    "claimed_location": "`{ country, region, lat, lon }`: where the address the node's probe sessions come from is, by the validators' local lookups, majority-agreed (method under `geo_claims` in this document). Region level and whole degrees only; `region` may be null. Null without a majority claim. A claim, not a measurement: read it with `claim_status`.",
    "claim_status": "`consistent` (the claim lies inside `validated_region`, with the tolerance), `inconsistent` (it lies outside), `unchecked` (no `validated_region` to check it against) or `no_claim`.",
    "display_location": "What to show on a map: `{ source: \"claim\", country, region, lat, lon }` when `claim_status` is `consistent`; otherwise `{ source: \"rtt\", lat, lon, radius_km }`, the validated region, when there is one; else null.",
    "capacity_mbps": "Verified capacity credit in the newest snapshot, Mbps; 0 when it passed no capacity test or is not in it.",
    "capacity_reason": "Null when `capacity_mbps` is above 0. Otherwise, in this order: `dark` (no validator got a vantage reply from it in the last 3 recorded windows and it has no drawn pair), `unknown` (its UID's declaration could not be read this run), `no_declaration` (its UID's current manifest declares no capacity for it), `test_failed` or `penalty` (its newest capacity test in the validators' committed probe batches failed, or passed yet scoring credits 0: a penalty, probation or a window's lag), `no_test_yet` (no capacity test of it in the recorded batches, which go back about 20 windows).",
    "last_capacity_test": "`{ window, result_mbps, outcome, validators }`: the node's newest capacity test in the validators' committed probe batches the publisher has recorded (about the last 20 windows): the window, the highest throughput measured, `passed` when any validator's test of it passed (else `failed`), and how many validators tested it. Null when none is recorded. Scoring's own credit for a test (its verdict against the declaration, probation) is not published; see `capacity_reason`.",
    "declared_mbps": "The capacity its operator declares for it, Mbps: from the capacity declaration its UID's current on-chain commitment names, read from the validators' stores and checked by hash. Null when none is declared or it could not be read. Compare with `capacity_mbps` (verified).",
    "in_latest_snapshot": "Whether the node is in the newest majority-agreed snapshot.",
    "uptime": "`ratio`: of the recorded windows since the node was first seen (at most the last 140), the share in which the snapshot lists it with capacity above zero; `windows_up` and `windows_observed` are the counts. Observed by this API, not the scoring uptime.",
    "peering": "`listed`: in the peer directory; `drawn_pairs`: distinct peers the node has a measured link with in the newest snapshot.",
    "first_seen_window": "The first recorded window the node was in (records start when the publisher started).",
    "last_seen_window": "The last recorded window the node was in."
   }
  },
  "/v0/fleets": {
   "about": "One entry per UID with a node in the newest snapshot.",
   "fields": {
    "uid": "The UID.",
    "hotkey": "Its hotkey (ss58), public on chain.",
    "nodes": "Its nodes in the newest snapshot.",
    "nodes_with_capacity": "Of those, nodes with capacity above zero.",
    "capacity_mbps": "Their total verified capacity, Mbps.",
    "countries": "Countries of its located nodes.",
    "regions": "`country/region` of its located nodes.",
    "avg_uptime": "Mean of its nodes' `uptime.ratio` (observed by this API, not the scoring uptime).",
    "binding": "`{ hash, path, held_by, of }`: the node binding in force for the UID, from its current on-chain commitment. `path` is `inline` (the binding is in the commitment itself, ADR-0058, and takes precedence; `hash` is the hash validators give it) or `manifest` (named by the commitment manifest, read from the validators' stores and checked by hash); `held_by` of `of` is how many validators' stores serve that binding's bytes (null for inline). Whether a validator pulled the binding from the operator or a node forwarded it over a probe session is not published, so `path` doesn't say pulled or forwarded. Null when the commitment names no binding; `path` `unknown` when it couldn't be read yet. The binding validators score with is the one in force at each window's chain read, which can trail a new commitment by a window.",
    "agreed_weight": "`{ transit, routing }`: the UID's share of the weight row most validators set on chain for each mechanism (`transit` is mechanism 0, `routing` mechanism 1), 0 to 1, rounded to 6 places. Null for a mechanism with no majority row. It is the agreed weight, not emission or a payout, and it trails the newest snapshot by the reveal delay. The scoring uptime is not here: it is computed inside scoring from every validator's revealed batches and not published, and this API does not recompute it.",
    "validated_regions": "`{ nodes, countries, continents, places }` over its nodes in the newest snapshot that have a `validated_region`: how many, the `country` and `continent` values they name, and each distinct circle as `{ lat, lon, radius_km, nodes }`.",
    "geo_claims": "`{ consistent, inconsistent, unchecked, no_claim, consistent_regions }`: its nodes in the newest snapshot by `claim_status`, and the `country/region` of each consistent claim, sorted.",
    "axon_location": "`{ country, region, continent, source }` looked up from the UID's axon address, which the operator publishes on chain, with `source` \"chain axon (UID-level, not per node)\". It says where the UID's axon is, not where its nodes are. Null when the UID serves no axon or a non-routable one. The address itself is never published."
   }
  },
  "/v0/validators": {
   "about": "The majority-agreed validator set.",
   "fields": {
    "uid": "The validator's UID (null if its hotkey is not registered).",
    "hotkey": "Its hotkey (ss58).",
    "stake_share": "Its stake over the set's total stake, from the attested validator set.",
    "attested_latest_snapshot": "Whether it signed the majority-agreed snapshot.",
    "weights": "Per mechanism (`transit` is mechanism 0, `routing` is mechanism 1): `set` (it has weights on chain), `agrees_with_majority` (its weight row is identical to the row most validators hold; null without a majority or without weights) and `last_update_block`."
   }
  },
  "/v0/history": {
   "about": "A per-window rollup, newest first, for up to the last 480 recorded windows (about 24 days). `?window=<n>` returns one window; `?last=<n>` the newest n.",
   "fields": {
    "window": "The window.",
    "nodes": "Nodes in that window's majority-agreed snapshot.",
    "nodes_with_capacity": "Of those, nodes with capacity above zero.",
    "fleets": "Distinct UIDs among them.",
    "capacity_mbps": "Their total verified capacity, Mbps.",
    "agree": "Validators that served that snapshot when it was first recorded.",
    "of": "Validators configured then."
   }
  },
  "/v0/meta": {
   "about": "This document."
  }
 },
 "notes": {
  "kind": "Nodes have no `kind` (kernel, no-root or container): validators don't publish it, so the field was dropped rather than shown as unknown.",
  "version": "A node's release version is not published: no validator measures or attests it, so this API has no per-node `version`.",
  "route_table": "On testnet the route table has 0 routes while every validator serves it: the reference solver routes demand, and there is no customer demand on testnet yet. Transit is measured with probes and capacity tests meanwhile. 0 routes is expected, not a fault.",
  "shared_centroids": "Validated regions are published with whole-degree centroids, so many nodes share one point (for example 50, 9 near Frankfurt). That is by design, for privacy; a map should spread nodes that share a point.",
  "axon_counts": "`uids_with_axon_location` counts every registered UID whose on-chain axon has a coarse location, validators and solvers included; `fleets_with_axon_location` counts only UIDs with a node in the newest snapshot. Validators serve axons for their stores, so the first is larger.",
  "history": "History starts when this publisher began recording (window 23496, 2026-11-16). It can't be backfilled from validators: their stores serve only the latest signed snapshot, keep older ones for a short time and index none by window, so earlier snapshots can't be fetched."
 },
 "errors": "Errors are JSON `{ \"error\": \"<code>\" }`: `not_found`, `no_data_yet`, `rate_limited` (with Retry-After), `method_not_allowed`, `bad_query`."
}
