{
  "openapi": "3.0.3",
  "info": {
    "title": "Kairos Signal DePIN Intelligence API",
    "description": "Verifiable DePIN data API. A 731-entry catalog, 370+ networks with live data, 315+ with first-party telemetry. Every value carries a verify_url. Bitcoin-anchored via OpenTimestamps. Access model (verified 2026-09-13): browsing surfaces (/try, /v1/networks, /v1/network/{symbol}, /v1/supply, /v1/market, /v1/revenue, /v1/provenance, /v1/history, /v1/attest, /v1/attestations, /v1/credits/pricing, /v1/credits/register, /v1/brief, /mcp, /api/order) are keyless. The X-API-Key header authenticates account surfaces only: credit balance, purchase, top-up. GET data endpoints never debit credits; credits are spent only via POST /v1/credits/purchase. A key with credits does not change your tier — tier-gated views are unlocked only by a paid subscription tier.",
    "version": "1.0.0",
    "contact": {
      "email": "support@kairossignal.com",
      "name": "Kairos Signal"
    },
    "termsOfService": "https://kairossignal.com/agents"
  },
  "servers": [
    {
      "url": "https://kairossignal.com",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Network": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string",
            "example": "AKT"
          },
          "name": {
            "type": "string",
            "example": "Akash Network"
          },
          "category": {
            "type": "string",
            "example": "Compute"
          },
          "telemetry_tier": {
            "type": "string",
            "example": "first_party"
          },
          "live_series": {
            "type": "integer",
            "example": 41
          }
        }
      },
      "SupplyData": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string"
          },
          "metric": {
            "type": "string",
            "example": "registered_gpu_count"
          },
          "value": {
            "type": "number"
          },
          "unit": {
            "type": "string",
            "example": "count"
          },
          "source": {
            "type": "string",
            "example": "io.net API"
          },
          "verify_url": {
            "type": "string",
            "format": "uri"
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MarketData": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string"
          },
          "price_usd": {
            "type": "number"
          },
          "market_cap_usd": {
            "type": "number"
          },
          "fully_diluted_valuation_usd": {
            "type": "number"
          },
          "verify_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "RevenueData": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string"
          },
          "fees_24h_usd": {
            "type": "number"
          },
          "fees_7d_usd": {
            "type": "number"
          },
          "fees_30d_usd": {
            "type": "number"
          },
          "tvl_usd": {
            "type": "number"
          },
          "verify_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ProvenanceRecord": {
        "type": "object",
        "properties": {
          "metric": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "verify_url": {
            "type": "string",
            "format": "uri"
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "staleness_flag": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "paths": {
    "/mcp": {
      "post": {
        "summary": "MCP JSON-RPC endpoint (Streamable HTTP)",
        "description": "MCP protocol endpoint (Streamable HTTP; MCP 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05) for AI agents. Tools: find_networks, get_network, get_metric_history, verify_value, register_agent, list_products, purchase_data, topup_credits, check_balance, list_datasets, get_stats, get_data_dictionary, get_derivation_ledger, fetch_dataset, verify_footprint. Read-only edition: /mcp/public.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "example": "2.0"
                  },
                  "method": {
                    "type": "string",
                    "example": "tools/list"
                  },
                  "params": {
                    "type": "object"
                  },
                  "id": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          }
        }
      }
    },
    "/try": {
      "get": {
        "summary": "Try the API free (no key required)",
        "description": "Returns 3 showcase DePIN networks with full supply telemetry and verify_urls.",
        "responses": {
          "200": {
            "description": "Sample data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/brief": {
      "get": {
        "summary": "Weekly Design Partner Brief (machine-readable)",
        "description": "Measured judgment, not raw feeds: capacity-vs-demand divergence per network (with implausible rows withheld and named), upstream feeds that answer but have stopped updating, on-chain supply verifiability with the exact contract read, exchange-wallet flow extremes, holder concentration and 7-day supply movers. Generated weekly (Mondays 08:00 UTC) from measured data only; every figure carries its source, as-of time and how to verify it. Free on every tier.",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "2026-08-24"
            },
            "description": "Edition to fetch (YYYY-MM-DD). Defaults to the newest."
          }
        ],
        "responses": {
          "200": {
            "description": "Brief document"
          },
          "404": {
            "description": "No brief published, or no edition for that date"
          }
        }
      }
    },
    "/v1/credits/balance": {
      "get": {
        "summary": "Current credit balance for the key in X-API-Key",
        "parameters": [
          {
            "name": "X-API-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Key from POST /v1/credits/register"
          }
        ],
        "responses": {
          "200": {
            "description": "Balance and account identity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "credits_balance": {
                      "type": "number"
                    },
                    "agent_name": {
                      "type": "string"
                    },
                    "spending_status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or unknown API key"
          }
        }
      }
    },
    "/v1/credits/pricing": {
      "get": {
        "summary": "Get full pricing catalog",
        "responses": {
          "200": {
            "description": "Pricing details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/credits/purchase": {
      "post": {
        "summary": "Spend credits on a dataset. THE reason to hold an API key — it is the only call an anonymous caller cannot make. Product keys come from GET /v1/credits/pricing: the section keys ARE the product_key values.",
        "parameters": [
          {
            "name": "X-API-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Key from POST /v1/credits/register"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "product_key"
                ],
                "properties": {
                  "product_key": {
                    "type": "string",
                    "example": "depin_provenance",
                    "description": "e.g. depin_provenance ($0.49), depin_networks ($0.99), depin_revenue_snapshot ($2.99)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Purchased; data delivered inline in the response body",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "purchased"
                    },
                    "price_paid": {
                      "type": "number"
                    },
                    "remaining_balance": {
                      "type": "number"
                    },
                    "delivery": {
                      "type": "string",
                      "example": "inline"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits — the response states the shortfall and how to top up"
          }
        }
      }
    },
    "/v1/credits/register": {
      "post": {
        "summary": "Register for free API key + $5 credits (first 3 keys per IP per 30 days)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "agent_name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "API key and credits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "type": "string"
                    },
                    "credits_balance": {
                      "type": "number"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/export": {
      "get": {
        "summary": "Bulk export of the data your tier already entitles, as one CSV or NDJSON file instead of per-query JSON. Grants no extra breadth: it calls the same entitled endpoint with your own key, so if you cannot GET it you cannot export it. Requires a tier with the `exports` capability (pro, enterprise); anything else receives 402.",
        "parameters": [
          {
            "name": "dataset",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "networks",
                "grades",
                "correlations",
                "lead-lag",
                "indicators",
                "changes",
                "digest",
                "supply",
                "history"
              ]
            },
            "description": "Which dataset to export. `history` accepts `symbol` and `days`."
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "ndjson"
              ],
              "default": "csv"
            },
            "description": "csv for tabular sets (networks, grades, correlations, lead-lag, changes, indicators); ndjson for the deeply nested ones (digest, supply), where CSV flattens to thousands of columns."
          },
          {
            "name": "X-API-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file. `X-Kairos-Export-Rows` gives the row count and `X-Kairos-Export-Source` names the endpoint the rows came from, so any export can be re-derived from the JSON API.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Unknown dataset or format; the response lists the valid values"
          },
          "402": {
            "description": "Your tier does not include `exports`"
          },
          "422": {
            "description": "That dataset has no tabular body to export"
          },
          "503": {
            "description": "The underlying dataset endpoint was unavailable"
          }
        }
      }
    },
    "/v1/market": {
      "get": {
        "summary": "Price, market cap, FDV (256 networks)",
        "responses": {
          "200": {
            "description": "Market data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MarketData"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/network/{symbol}": {
      "get": {
        "summary": "Get all metrics for one network",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "AKT"
          }
        ],
        "responses": {
          "200": {
            "description": "Network metrics with provenance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SupplyData"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/networks": {
      "get": {
        "summary": "List all 745 networks",
        "description": "Coverage list with symbol, name, category, telemetry tier.",
        "responses": {
          "200": {
            "description": "Network catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Network"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/provenance": {
      "get": {
        "summary": "Provenance disclosure for all values",
        "description": "Every source, verify_url, as_of timestamp, and staleness flag.",
        "responses": {
          "200": {
            "description": "Provenance records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProvenanceRecord"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/revenue": {
      "get": {
        "summary": "Protocol fees and TVL (92 networks)",
        "responses": {
          "200": {
            "description": "Revenue data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RevenueData"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/supply": {
      "get": {
        "summary": "First-party supply telemetry (171 networks)",
        "responses": {
          "200": {
            "description": "Supply data with verify_urls",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SupplyData"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/credits/purchases": {
      "get": {
        "operationId": "listPurchases",
        "summary": "Your purchase history with verifiable receipts (no charge)",
        "parameters": [
          {
            "name": "X-API-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "purchases with purchase_id, price, payload_sha256"
          }
        }
      }
    },
    "/v1/credits/purchases/{purchase_id}": {
      "get": {
        "operationId": "getPurchaseReceipt",
        "summary": "Verify a purchase receipt; ?include=data re-delivers the product free",
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "data"
              ]
            }
          },
          {
            "name": "X-API-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "receipt (price, payload_sha256, purchased_at); retry after a dropped connection is a GET, never a second charge"
          },
          "404": {
            "description": "no purchase with this id for this key"
          }
        }
      }
    },
    "/x402/v1/data/depin_provenance": {
      "get": {
        "operationId": "x402_depin_provenance",
        "summary": "DePIN product depin_provenance ($0.49 per request, x402)",
        "description": "First-party DePIN supply telemetry (node counts, capacity, utilisation) for every network /v1/supply carries; each value with source, as_of and an upstream verify_url.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.49"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/depin_networks": {
      "get": {
        "operationId": "x402_depin_networks",
        "summary": "DePIN product depin_networks ($0.99 per request, x402)",
        "description": "The DePIN network catalog with live-coverage and first-party-telemetry flags per network and a market summary; values carry source, as_of and verify_url.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/depin_revenue_snapshot": {
      "get": {
        "operationId": "x402_depin_revenue_snapshot",
        "summary": "DePIN product depin_revenue_snapshot ($2.99 per request, x402)",
        "description": "On-chain fee/revenue figures for the DePIN networks covered by the DefiLlama fees dataset, with verify URLs.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "2.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/node_quality_score": {
      "get": {
        "operationId": "x402_node_quality_score",
        "summary": "DePIN product node_quality_score ($4.99 per request, x402)",
        "description": "Quality-adjusted node counts (raw node count x active/raw) for networks whose inputs meet a same-collection-cycle contract; methodology included.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "4.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/dilution_risk_map": {
      "get": {
        "operationId": "x402_dilution_risk_map",
        "summary": "DePIN product dilution_risk_map ($4.99 per request, x402)",
        "description": "FDV/MC dilution ratios across DePIN networks, with the measurement contract and classification thresholds.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "4.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/gpu_supply_demand": {
      "get": {
        "operationId": "x402_gpu_supply_demand",
        "summary": "DePIN product gpu_supply_demand ($9.99 per request, x402)",
        "description": "GPU supply read from the io.net Explorer and Akash Console APIs (plus Golem), with a cross-network comparison.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "9.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/sector_health_index": {
      "get": {
        "operationId": "x402_sector_health_index",
        "summary": "DePIN product sector_health_index ($4.99 per request, x402)",
        "description": "Composite health score per DePIN category, with methodology and component weights.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "4.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/geo_concentration": {
      "get": {
        "operationId": "x402_geo_concentration",
        "summary": "DePIN product geo_concentration ($4.99 per request, x402)",
        "description": "Country distribution from first-party telemetry, for the networks that publish node locations.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "4.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/dev_velocity": {
      "get": {
        "operationId": "x402_dev_velocity",
        "summary": "DePIN product dev_velocity ($4.99 per request, x402)",
        "description": "GitHub public-repository metrics per DePIN network.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "4.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    },
    "/x402/v1/data/competitive_landscape": {
      "get": {
        "operationId": "x402_competitive_landscape",
        "summary": "DePIN product competitive_landscape ($9.99 per request, x402)",
        "description": "Market share by market cap within each DePIN category, with HHI concentration.",
        "tags": [
          "x402"
        ],
        "security": [],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "9.99"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Data inline, with a PAYMENT-RESPONSE settlement receipt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: the PAYMENT-REQUIRED header and the body carry the offer (standard x402 exact on Base first)"
          }
        }
      }
    }
  }
}