{
 "openapi": "3.1.0",
 "info": {
  "title": "dTAOscan API",
  "version": "1.12.6",
  "description": "Public, no-key, Ed25519-signed Bittensor dTAO subnet data, read directly from Subtensor. Free reads are rate limited to 10 requests/min per IP; send an API key as `Authorization: Bearer <key>` for higher volume. Every data response is wrapped `{ data, receipt }` where `receipt` is an Ed25519 signature over the exact bytes of `data` (verify against /keys.json).",
  "contact": {
   "url": "https://dtaoscan.io"
  },
  "license": {
   "name": "Proprietary data, free to read"
  }
 },
 "servers": [
  {
   "url": "https://dtaoscan.io"
  }
 ],
 "paths": {
  "/api/subnets": {
   "get": {
    "operationId": "listSubnets",
    "summary": "Every dTAO subnet at the latest snapshot block",
    "description": "Pool price, TAO + alpha reserves, neuron count, owner-lock state and logo for every Bittensor subnet. Signed.",
    "responses": {
     "200": {
      "description": "Signed subnet directory",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited (10/min/IP without a key)"
     }
    }
   }
  },
  "/api/subnet/{netuid}": {
   "get": {
    "operationId": "getSubnet",
    "summary": "One subnet in depth",
    "description": "Current pool economics, the last 48 snapshots (price history), and the per-UID miner/validator table. Signed.",
    "parameters": [
     {
      "name": "netuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 0
      },
      "description": "Subnet id."
     }
    ],
    "responses": {
     "200": {
      "description": "Signed subnet detail",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "404": {
      "description": "Unknown netuid"
     },
     "429": {
      "description": "Rate limited (10/min/IP without a key)"
     }
    }
   }
  },
  "/api/ecosystem": {
   "get": {
    "operationId": "getEcosystem",
    "summary": "Network totals: the whole dTAO economy in one call",
    "description": "Total-issued and staked alpha market cap (TAO and USD), TAO in pools, subnet count, and owners-unwinding count, root excluded, with the method stated inline. Signed.",
    "responses": {
     "200": {
      "description": "Signed ecosystem totals",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited (10/min/IP without a key)"
     }
    }
   }
  },
  "/api/synergy": {
   "get": {
    "operationId": "getSynergy",
    "summary": "Cross-subnet validator overlap",
    "description": "Every validator hotkey holding permits on two or more subnets, with the subnets it secures. The network concentration signal. Signed.",
    "responses": {
     "200": {
      "description": "Signed validator overlap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited (10/min/IP without a key)"
     }
    }
   }
  },
  "/api/pro/returns": {
   "get": {
    "operationId": "proReturns",
    "summary": "Dual-denominated returns (Pro)",
    "description": "TAO-denominated 7d/30d return per subnet - the honest number the alpha-APY hides. Signed.",
    "security": [
     {
      "proKey": []
     }
    ],
    "parameters": [],
    "responses": {
     "200": {
      "description": "Signed response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/pro/concentration": {
   "get": {
    "operationId": "proConcentration",
    "summary": "Emission concentration (Pro)",
    "description": "Top-1/5 reward share, Nakamoto coefficient, and validator-vs-miner split per subnet. Signed.",
    "security": [
     {
      "proKey": []
     }
    ],
    "parameters": [],
    "responses": {
     "200": {
      "description": "Signed response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/pro/flow": {
   "get": {
    "operationId": "proFlow",
    "summary": "Net stake flow (Pro)",
    "description": "Net stake flow (accumulation vs exit) valued in TAO, plus 7d pool-liquidity flow, per subnet. Signed.",
    "security": [
     {
      "proKey": []
     }
    ],
    "parameters": [],
    "responses": {
     "200": {
      "description": "Signed response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/pro/dereg-risk": {
   "get": {
    "operationId": "proDeregRisk",
    "summary": "Deregistration risk (Pro)",
    "description": "Subnets ranked by 7d EMA price ascending - closest to the pruning line first, with trend and cushion. Signed.",
    "security": [
     {
      "proKey": []
     }
    ],
    "parameters": [],
    "responses": {
     "200": {
      "description": "Signed response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/pro/liquidity": {
   "get": {
    "operationId": "proLiquidity",
    "summary": "Liquidity depth + price impact (Pro)",
    "description": "Effective price impact of a 1k/10k TAO order (size / tao_in, how far above spot you execute, matching the stake calculator) and the order size at 2% impact, per subnet. Signed.",
    "security": [
     {
      "proKey": []
     }
    ],
    "parameters": [],
    "responses": {
     "200": {
      "description": "Signed response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/pro/correlation": {
   "get": {
    "operationId": "proCorrelation",
    "summary": "Return correlation (Pro)",
    "description": "Pearson correlation of hourly TAO returns. Pass netuid for one subnet's peers + inverse hedges; omit for the top pairs that move as one. Signed.",
    "security": [
     {
      "proKey": []
     }
    ],
    "parameters": [
     {
      "name": "netuid",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0
      },
      "description": "One subnet's peers; omit for the pairs board."
     },
     {
      "name": "window",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 30
      },
      "description": "Trailing window in days (1-30, default 7)."
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50
      },
      "description": "Rows returned (1-50, default 15)."
     }
    ],
    "responses": {
     "200": {
      "description": "Signed response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/pro/query": {
   "get": {
    "operationId": "proQuery",
    "summary": "Custom historical query (Pro)",
    "description": "One aggregation of a metric over the retained snapshot window, ranked. Signed.",
    "security": [
     {
      "proKey": []
     }
    ],
    "parameters": [
     {
      "name": "metric",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "price_tao",
        "tao_in_pool",
        "alpha_in",
        "alpha_out",
        "mcap"
       ]
      },
      "description": "Column to aggregate."
     },
     {
      "name": "agg",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "last",
        "first",
        "min",
        "max",
        "avg",
        "change",
        "change_pct"
       ]
      },
      "description": "Aggregation (default change_pct)."
     },
     {
      "name": "window",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 30
      },
      "description": "Trailing window in days (1-30, default 7)."
     },
     {
      "name": "subnets",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Comma list of netuids to filter (max 60); omit for all."
     },
     {
      "name": "sort",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "asc",
        "desc"
       ]
      },
      "description": "Sort direction (default desc)."
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 128
      },
      "description": "Rows returned (1-128, default 20)."
     }
    ],
    "responses": {
     "200": {
      "description": "Signed response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/pro/history": {
   "get": {
    "operationId": "proHistory",
    "summary": "Full snapshot history (Pro)",
    "description": "The whole retained snapshot window for one subnet (the free /api/subnet returns only the last 48). Signed.",
    "security": [
     {
      "proKey": []
     }
    ],
    "parameters": [
     {
      "name": "netuid",
      "in": "query",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 0
      },
      "description": "Subnet id."
     }
    ],
    "responses": {
     "200": {
      "description": "Signed response",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SignedEnvelope"
        }
       }
      }
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/export/subnets.csv": {
   "get": {
    "operationId": "proExportCsv",
    "summary": "Bulk CSV export (Pro)",
    "description": "Every subnet at the latest block as a CSV download.",
    "security": [
     {
      "proKey": []
     }
    ],
    "responses": {
     "200": {
      "description": "CSV of every subnet"
     },
     "401": {
      "description": "Invalid or expired Pro key"
     },
     "402": {
      "description": "Payment required: buy a Pro pass at POST /api/pro"
     }
    }
   }
  },
  "/api/pro": {
   "post": {
    "operationId": "buyPro",
    "summary": "Buy a 30-day Pro pass",
    "description": "Pay the Pro price with x402 (an `X-PAYMENT` header carrying a signed USDC authorization on Base) and receive a 30-day Pro key. Call without the header to get the 402 payment menu.",
    "responses": {
     "200": {
      "description": "Pro key minted (shown once)"
     },
     "402": {
      "description": "Payment required: the x402 payment menu"
     }
    }
   }
  },
  "/healthz": {
   "get": {
    "operationId": "health",
    "summary": "Freshness probe",
    "description": "Last indexed block, its timestamp, and age in seconds.",
    "responses": {
     "200": {
      "description": "Freshness"
     }
    }
   }
  },
  "/keys.json": {
   "get": {
    "operationId": "signingKeys",
    "summary": "Ed25519 public keys that sign every /api response",
    "responses": {
     "200": {
      "description": "Public key set"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "http",
    "scheme": "bearer",
    "description": "Optional. Raises the per-IP rate limit."
   },
   "proKey": {
    "type": "http",
    "scheme": "bearer",
    "description": "A 30-day Pro pass key (dtp_...). Gives access to the deep-analytics endpoints. Buy at POST /api/pro."
   }
  },
  "schemas": {
   "SignedEnvelope": {
    "type": "object",
    "required": [
     "data",
     "receipt"
    ],
    "properties": {
     "data": {
      "type": "object",
      "description": "The payload. `receipt` signs the exact bytes of this object serialized."
     },
     "receipt": {
      "type": [
       "object",
       "null"
      ],
      "description": "Ed25519 provenance receipt over `data`. Verify against /keys.json."
     }
    }
   }
  }
 }
}