{"openapi":"3.1.0","info":{"title":"Explore21 Data API","version":"1","summary":"Free Bitcoin on-chain data: realized price, MVRV, HODL waves and more.","description":"Free Bitcoin on-chain data for long-term holders: realized price, MVRV, HODL waves and more, computed from our own Bitcoin Core node. Built for long-term holders, not traders.\n\nNo key needed: 30 requests a minute per IP, or 120 a minute with a free Developer Key (header X-Developer-Key, from https://charts.explore21.com/data/key). Over the limit is HTTP 429 with Retry-After. Answers are cached for 10 minutes, and the data moves once a block at most.\n\nLicense: CC BY 4.0. Credit us as \"Data: Explore21 (https://charts.explore21.com), CC BY 4.0\", with a link to the chart page (chart_url in every answer).","license":{"name":"CC BY 4.0","identifier":"CC-BY-4.0"}},"servers":[{"url":"https://data.explore21.com"}],"security":[{},{"DeveloperKey":[]}],"externalDocs":{"url":"https://charts.explore21.com/data","description":"The data, the CSV files and how to credit us"},"paths":{"/v1/metrics":{"get":{"operationId":"listMetrics","summary":"Every published metric, with its columns and links","responses":{"200":{"description":"The metrics, in the order the site lists them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricList"}}}},"401":{"$ref":"#/components/responses/UnknownKey"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/metrics/{id}":{"get":{"operationId":"getMetric","summary":"One metric's daily series, or the series as published on a past day","parameters":[{"$ref":"#/components/parameters/MetricId"},{"name":"format","in":"query","description":"json (the default) or csv. The CSV has the same columns as the JSON objects.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"from","in":"query","description":"First UTC day to include, yyyy-MM-dd.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Last UTC day to include, yyyy-MM-dd.","schema":{"type":"string","format":"date"}},{"name":"If-None-Match","in":"header","description":"The ETag of an earlier answer. Unchanged data answers 304 with no body.","schema":{"type":"string"}},{"name":"as_published","in":"query","description":"A past UTC day, yyyy-MM-dd: the whole series exactly as published that day (a Vintage), with its SHA-256 and the OpenTimestamps proof on Bitcoin. The JSON answer is then a Vintage; the CSV is the archived bytes unchanged. Not with from or to. GET /v1/metrics/{id}/vintages lists the days.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"The rows, oldest first.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator over the data alone."},"X-As-Of-Block":{"schema":{"type":"integer"},"description":"CSV only: the chain height, when known."},"X-Method-Version":{"schema":{"type":"integer"},"description":"CSV only: the method version."},"X-License":{"schema":{"type":"string"},"description":"CSV only: CC BY 4.0."},"X-Attribution":{"schema":{"type":"string"},"description":"CSV only: the credit line."},"Link":{"schema":{"type":"string"},"description":"CSV only: the chart page, rel=\"related\"."},"X-Sha256":{"schema":{"type":"string"},"description":"as_published CSV only: SHA-256 of the body."},"X-Proof-Url":{"schema":{"type":"string"},"description":"as_published CSV only: the proof file."},"X-Proof-Status":{"schema":{"$ref":"#/components/schemas/ProofStatus"},"description":"as_published CSV only."}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Series"},{"$ref":"#/components/schemas/Vintage"}]}},"text/csv":{"schema":{"type":"string"}}}},"304":{"description":"Not modified since the ETag in If-None-Match."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/UnknownKey"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"as_published only: the kept file no longer matches its manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/metrics/{id}/vintages":{"get":{"operationId":"listVintages","summary":"The days the archive kept this metric (point-in-time history), newest first","parameters":[{"$ref":"#/components/parameters/MetricId"}],"responses":{"200":{"description":"One entry per kept day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VintageList"}}}},"401":{"$ref":"#/components/responses/UnknownKey"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/vintages/{day}/{file}":{"get":{"operationId":"getVintageFile","summary":"A day's manifest (SHA-256 of every dataset) or its OpenTimestamps proof","parameters":[{"name":"day","in":"path","required":true,"schema":{"type":"string","format":"date"}},{"name":"file","in":"path","required":true,"schema":{"type":"string","enum":["manifest.json","manifest.json.ots"]}}],"responses":{"200":{"description":"The file as the archive keeps it.","content":{"application/json":{"schema":{"type":"object"}},"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"401":{"$ref":"#/components/responses/UnknownKey"},"404":{"description":"No such day, or no proof for it yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/metrics/{id}/latest":{"get":{"operationId":"getMetricLatest","summary":"One metric's newest day (within from and to, if given)","parameters":[{"$ref":"#/components/parameters/MetricId"},{"name":"format","in":"query","description":"json (the default) or csv. The CSV has the same columns as the JSON objects.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"from","in":"query","description":"First UTC day to include, yyyy-MM-dd.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Last UTC day to include, yyyy-MM-dd.","schema":{"type":"string","format":"date"}},{"name":"If-None-Match","in":"header","description":"The ETag of an earlier answer. Unchanged data answers 304 with no body.","schema":{"type":"string"}}],"responses":{"200":{"description":"The rows, oldest first.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator over the data alone."},"X-As-Of-Block":{"schema":{"type":"integer"},"description":"CSV only: the chain height, when known."},"X-Method-Version":{"schema":{"type":"integer"},"description":"CSV only: the method version."},"X-License":{"schema":{"type":"string"},"description":"CSV only: CC BY 4.0."},"X-Attribution":{"schema":{"type":"string"},"description":"CSV only: the credit line."},"Link":{"schema":{"type":"string"},"description":"CSV only: the chart page, rel=\"related\"."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Series"}},"text/csv":{"schema":{"type":"string"}}}},"304":{"description":"Not modified since the ETag in If-None-Match."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/UnknownKey"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/snapshot":{"get":{"operationId":"getSnapshot","summary":"Where each long-term reading sits today: Percentile Rank and past cycle tops and lows","description":"Price, MVRV, MVRV Z-Score, realized price (all holders and short-term), % supply in profit, Mayer Multiple, 200-week moving average, Puell Multiple, hashrate, difficulty and block interval. Describes, never advises.","parameters":[{"name":"If-None-Match","in":"header","description":"The ETag of an earlier answer. Unchanged data answers 304 with no body.","schema":{"type":"string"}}],"responses":{"200":{"description":"One entry per reading that could be loaded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"}}}},"304":{"description":"Not modified since the ETag in If-None-Match."},"401":{"$ref":"#/components/responses/UnknownKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/learn/search":{"get":{"operationId":"searchLearn","summary":"Search the teaching pages: the course, the guides and the glossary, in English and Bulgarian","parameters":[{"name":"q","in":"query","required":true,"description":"The words to search for.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"lang","in":"query","description":"Which language comes first. Guessed from the query (Cyrillic means bg) if left out.","schema":{"type":"string","enum":["en","bg"]}}],"responses":{"200":{"description":"Up to 10 pages, the asked language first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnSearch"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/UnknownKey"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/metrics/{id}/changelog":{"get":{"operationId":"getMetricChangelog","summary":"Every change to how the metric is computed, newest first","parameters":[{"$ref":"#/components/parameters/MetricId"}],"responses":{"200":{"description":"The method history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Changelog"}}}},"401":{"$ref":"#/components/responses/UnknownKey"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"components":{"securitySchemes":{"DeveloperKey":{"type":"apiKey","in":"header","name":"X-Developer-Key","description":"Optional and free, from https://charts.explore21.com/data/key: 120 requests a minute instead of 30."}},"parameters":{"MetricId":{"name":"id","in":"path","required":true,"description":"The metric, as listed by /v1/metrics.","schema":{"type":"string","enum":["bitcoin-mvrv-z-score","bitcoin-price","bitcoin-mayer-multiple","bitcoin-200-week-moving-average","bitcoin-hodl-waves","bitcoin-hashrate","bitcoin-mining-difficulty","bitcoin-puell-multiple","bitcoin-block-interval","bitcoin-block-size","bitcoin-transactions-per-day","bitcoin-mvrv-ratio","bitcoin-realized-price","bitcoin-percent-supply-in-profit","bitcoin-realized-cap","bitcoin-realized-profit-loss"]}}},"schemas":{"MetricSummary":{"type":"object","required":["id","title","description","columns","url","chart_url","csv_url","method_version","changelog_url"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"columns":{"type":"array","items":{"type":"string"},"description":"Column names; the first is the UTC day. Empty if the metric could not be loaded just now."},"url":{"type":"string","format":"uri"},"chart_url":{"type":"string","format":"uri"},"csv_url":{"type":"string","format":"uri"},"method_version":{"type":"integer","minimum":1,"description":"Goes up by one each time the way the metric is computed changes."},"changelog_url":{"type":"string","format":"uri"}}},"MetricList":{"type":"object","required":["metrics","as_of_block","license","attribution"],"properties":{"metrics":{"type":"array","items":{"$ref":"#/components/schemas/MetricSummary"}},"as_of_block":{"type":["integer","null"],"description":"The chain height the data reflects, or null when it could not be read."},"license":{"type":"string","const":"CC BY 4.0"},"attribution":{"type":"string","description":"The credit line to show next to the data."}}},"Row":{"type":"object","description":"One UTC day. Keys are the metric's columns; a missing value is null.","additionalProperties":{"type":["number","string","null"]}},"Series":{"type":"object","required":["metric","as_of_block","license","attribution","chart_url","data"],"properties":{"metric":{"$ref":"#/components/schemas/MetricSummary"},"as_of_block":{"type":["integer","null"],"description":"The chain height the data reflects, or null when it could not be read."},"license":{"type":"string","const":"CC BY 4.0"},"attribution":{"type":"string","description":"The credit line to show next to the data."},"chart_url":{"type":"string","format":"uri"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Row"}}}},"Changelog":{"type":"object","required":["id","method_version","changes","license","attribution","chart_url"],"properties":{"id":{"type":"string"},"method_version":{"type":"integer","minimum":1},"changes":{"type":"array","items":{"type":"object","required":["version","date","summary"],"properties":{"version":{"type":"integer","minimum":1},"date":{"type":"string","format":"date"},"summary":{"type":"string"}}}},"license":{"type":"string","const":"CC BY 4.0"},"attribution":{"type":"string","description":"The credit line to show next to the data."},"chart_url":{"type":"string","format":"uri"}}},"ProofStatus":{"type":"string","enum":["confirmed","pending","missing"],"description":"confirmed: the proof names a Bitcoin block. pending: it waits for one (usually a few hours). missing: stamping failed and the next daily run stamps the same manifest."},"Vintage":{"type":"object","required":["id","as_published","sha256","proof_url","proof_status","proof_note","manifest_url","csv_url","how_to_verify","license","attribution","chart_url","data"],"properties":{"id":{"type":"string"},"as_published":{"type":"string","format":"date"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Of the CSV bytes, as in the manifest."},"proof_url":{"type":"string","format":"uri","description":"The day's manifest.json.ots."},"proof_status":{"$ref":"#/components/schemas/ProofStatus"},"proof_note":{"type":"string"},"manifest_url":{"type":"string","format":"uri"},"csv_url":{"type":"string","format":"uri","description":"The exact archived bytes."},"how_to_verify":{"type":"string"},"license":{"type":"string","const":"CC BY 4.0"},"attribution":{"type":"string","description":"The credit line to show next to the data."},"chart_url":{"type":"string","format":"uri"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Row"}}}},"VintageList":{"type":"object","required":["id","vintages","note","license","attribution"],"properties":{"id":{"type":"string"},"vintages":{"type":"array","items":{"type":"object","required":["day","sha256","proof_status","url","proof_url"],"properties":{"day":{"type":"string","format":"date"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"proof_status":{"$ref":"#/components/schemas/ProofStatus"},"url":{"type":"string","format":"uri"},"proof_url":{"type":"string","format":"uri"}}}},"note":{"type":"string"},"license":{"type":"string","const":"CC BY 4.0"},"attribution":{"type":"string","description":"The credit line to show next to the data."}}},"CycleKind":{"type":"string","enum":["top","low","low_so_far"],"description":"low_so_far: the low after the latest top, which a lower close can still replace."},"Reading":{"type":"object","required":["key","title","metric","date","value","percentile_rank","since","summary","at_cycle_tops_and_lows","method_version","chart_url","url"],"properties":{"key":{"type":"string","description":"The CSV column the number appears under."},"title":{"type":"string"},"metric":{"type":"string","description":"The metric id in /v1/metrics."},"date":{"type":"string","format":"date"},"value":{"type":"number"},"percentile_rank":{"type":"number","minimum":0,"maximum":100,"description":"Share of days (or difficulty epochs) since `since` with a lower value."},"since":{"type":"string","format":"date"},"summary":{"type":"string"},"at_cycle_tops_and_lows":{"type":"array","items":{"type":"object","required":["kind","date","value"],"properties":{"kind":{"$ref":"#/components/schemas/CycleKind"},"date":{"type":"string","format":"date"},"value":{"type":["number","null"],"description":"Null if the series had not started."}}}},"method_version":{"type":"integer","minimum":1},"chart_url":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}}},"Snapshot":{"type":"object","required":["readings","cycle_tops_and_lows","unavailable","note","as_of_block","license","attribution"],"properties":{"readings":{"type":"array","items":{"$ref":"#/components/schemas/Reading"}},"cycle_tops_and_lows":{"type":"array","items":{"type":"object","required":["kind","date","btc_close_usd"],"properties":{"kind":{"$ref":"#/components/schemas/CycleKind"},"date":{"type":"string","format":"date"},"btc_close_usd":{"type":"number"}}}},"unavailable":{"type":"array","items":{"type":"string"},"description":"Readings that could not be loaded just now, and cycle_tops_and_lows when the price history could not."},"note":{"type":"string"},"as_of_block":{"type":["integer","null"],"description":"The chain height the data reflects, or null when it could not be read."},"license":{"type":"string","const":"CC BY 4.0"},"attribution":{"type":"string","description":"The credit line to show next to the data."}}},"LearnSearch":{"type":"object","required":["query","lang","results"],"properties":{"query":{"type":"string"},"lang":{"type":"string","enum":["en","bg"]},"results":{"type":"array","items":{"type":"object","required":["title","url","lang","kind","excerpt"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"lang":{"type":"string","enum":["en","bg"]},"kind":{"type":"string","enum":["course","guide","word"]},"excerpt":{"type":"string"}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"BadRequest":{"description":"A query parameter is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No metric with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Over the per-minute limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the next minute starts."}}},"UnknownKey":{"description":"The X-Developer-Key is not known.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"The data could not be loaded just now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}