Frequently Asked Questions

Our mission is to advance public understanding of Bitcoin. We believe that explaining the protocol clearly and transparently strengthens the network and its adoption. To support this, we offer free charting and free or very low-cost API access to on-chain data.

The Bitcoin Lab API is a RESTful service that exposes our on-chain metrics and aggregates.

All blockchain data is harvested from our own nodes and processed in-house, making us a truly independent source of on-chain data.

Bitcoin Lab V2 will continue to be free to use and accessible for everyone. This upgrade improves performance, consistency, and developer experience.

What’s changing

• Authentication & access: Updated token flow and header usage.
• Endpoints & params: Many paths are renamed or new, some retired.
• Query params: Time is now in RFC3339 standard.
• Responses: Stricter schemas and status codes; more consistent error bodies.
• Payload: Now based on data points retrived, still very generous.

Key dates

• Now–Oct 2025: Test V2 alongside V1 (backwards-incompatible changes exist).
• Nov 2025: V2 becomes default; V1 enters deprecation.
• Jan 2026 (planned): V1 shutdown.

The live OpenAPI documentation is available here: /docs.

The searchable Metrics Catalog is available here: /metrics/.

Our mission is to advance public understanding of Bitcoin, and we encourage you to share the data. You may share and redistribute it, provided you clearly attribute it to Bitcoin Lab.

You should include Bitcoin Lab, and one of these website urls:
- www.researchbitcoin.net
- api.researchbitcoin.net

All data provided is informational purposes only and should not be considered as investment advice. All data is produced using own methods and has not been extensively validated.

We cannot and will not be held responsible for any losses or damages that may arise from the use of this website, the The Bitcoin Lab onchain analysis suite, or the API.

Do read the https://researchbitcoin.net/important-disclaimer/

Thank you! You can support us by subscribing to Tier 1 or Tier 2. One-off contributions in BTC are also welcome — contact researchbitcoinnow@gmail.com.

You can also help by spreading the word. Please feel free to share or republish our charts and datasets, but clearly attribute "Bitcoin Lab” and link back to the source page.

Finally, your interest and use of the Bitcoin Lab is our inspiration!

You subscribe by using the Sign Up (upper right screen) to create an account.
This will provide you a free Tier 0 access, see: /tier.

If you are interested in Tier 1 or Tier 2 access, please use the automatic onboarding system.

The Bitcoin Lab API is exceptionally low-cost. Tier 0 is free to use. We also offer Tier 1 and Tier 2 as low-cost subscription plans. The fee helps sustain the Bitcoin Lab service. At present, subscriptions do not expire (but this might change).
We hope users view the fee as a support of the Bitcoin Lab service.

Read more on available Tiers here: /tier.

Tier 0 provides access to most endpoints, but has limitation on historical data and allowed payload per week.
Read more on available Tiers here: /tier.

The Tier 1 and Tier 2 onboarding is quick and fully automated:

1. Email researchbitcoinnow@gmail.com with the subject exactly API request.
2. You will receive a BTC deposit address and our terms.
3. Deposit ≥ 0.00025 BTC for Tier 1, or ≥ 0.00100 BTC for Tier 2.
4. After your transaction is confirmed on the Bitcoin blockchain (typically 10–30 minutes), your Tier is activated automatically.

Currently we only accept bitcoin. If there is demand we may introduce support for Lightening and stablecoins.

API usage is measured in data points (DP), also referred to as payload. One DP equals one numeric value for one metric at one timestamp. Binned data has multiple numeric values per timestamp.. Quota is charged 1:1 with DP.

Examples:

• Simple series: DP = timestamps
  • realized_profit: 500 days at h12 (2 samples/day) ⇒ ≈1,000 DP ⇒ 1,000 quota.
• Binned series: DP = timestamps × bins
  • spent_output_by_age_sumbtc:
    500 days at daily resolution with 7 bins ⇒ 3,500 DP ⇒ 3,500 quota.
  • urpd_log_supply_btc:
    1 timepoint with ~1,000 bins ⇒ ≈1,000 DP ⇒ 1,000 quota.

Payload refers to the total amount of data returned by your API request. It is measured in data points (DP), which determine how much quota is consumed. The payload depends on:

• Time range – more timestamps increase DP.
• Resolution – higher frequency (e.g., h1 vs d1) yields more data points.
• Bins – binned series multiply DP by the number of bins.

In short: Payload = number of data points returned = quota charged.

Follow these steps:
1. Use the Sign Up (upper right screen) to create an account.
2. If already signed up, make sure you are logged in.
3. Generate a token here: Get API Token.
4. Copy the token from the screen and store it safely..

Note:

• Your token is personal—do not share it or put it in the query string.
• Tokens are per-user and associated with the registering email address.
• Token are only valid for (90 days), after which the token must be renewed.

Basics

• Token can be renewed on the website and via API.
• Token is valid for 90 days.
• Generating a new immediately invalidates the previous token.
• The token MUST be renewed on the website every 180 days, regardless of any API-based renewals.

Website renewal (any time)

1. Log into website Get API Token.
2. Click Generate New Token.
3. Copy and store the new token.

API renewal (headless, near-expiry)

1. Allowed only:

• within the last 7 days before the token expires
• before a new web-issued token is required.
2. Call:

    curl -X POST \
      "https://beta.thebitcoinresearcher.net/v2/v2/auth/renew" \
      -H "Authorization: Bearer YOUR-TOKEN"
      

3. On success, you receive a new token and refreshed expiry.

Note: You can also renew token in /docs . Just make sure you have the token string in Authorize - BearerAuth, and select Authentication: /v2/auth/renew

Include your API token in the X-API-Token header on every request.
Example:

curl -H "X-API-Token: YOUR_TOKEN" \
"beta.thebitcoinresearcher.net/v2/cointime_statistics/active_cap?resolution=h8&output_format=json"

You can check your status via the API endpoint Info System andd User using data_field user_info.
This is easy on /docs, or you can use query directly, e.g.:

 curl -X 'GET' \
  'https://beta.thebitcoinresearcher.net/v2/info/user_info' \
  -H 'accept: application/json' \
  -H 'X-API-Token: YOUR-TOKEN'

JSON is returned by default and is convenient for programmatic use.

All endpoints support CSV via output_format=csv.
CSV is significantly more transfer-efficient and is recommended for large or high-granularity queries (resolutions finer than 1D).

• from_time:
  RFC3339 UTC YYYY-MM-DDTHH:MM:SSZ (e.g., 2025-09-20T10:30:00Z)
  or date-only YYYY-MM-DD (interpreted as 00:00:00Z).
  Inclusive lower bound.
• to_time:
  RFC3339 UTC YYYY-MM-DDTHH:MM:SSZ
  or YYYY-MM-DD (→ 00:00:00Z).
  Exclusive upper bound.
• urpd_time:
  RFC3339 UTC YYYY-MM-DDTHH:MM:SSZ
  or YYYY-MM-DD (→ 00:00:00Z)
  or a UTC timestamp without suffix such as YYYY-MM-DD HH:MM[:SS].
  Selects the first available snapshot at or after the given time.
• resolution: block | h1 | h4 | h8 | h12 | d1
• output_format: json (default) | csv

Notes: Milliseconds (.SSS) are accepted but optional. If you omit the timezone suffix we assume UTC; YYYY-MM-DD HH:MM[:SS] style inputs work and are coerced to Z. Not all parameters are available for all endpoints, check the documentation.

All times are in UTC. We use RFC3339 (ISO-8601 extended) with a literal Z for both request parameters and responses (e.g., 2025-09-20T10:30:00Z). Date-only inputs (YYYY-MM-DD) are interpreted as 00:00:00Z. See FAQ “Common query parameters” for details.

Each response has a format-specific limit (CSV has higher max payload than csv).
If a request exceeds the limit, the API returns: 422 Unprocessable Entity with:

Payload must be ≤ {limit} data points for {output_format}. Please paginate the query.

To resolve: reduce the time range, use a coarser resolution, switch to output_format=csv, or split the request into smaller time windows.

The Bitcoin Lab API has employed rate limits to prevent abuse and ensure fair distribution of resources.
Exceeding limits returns 429 Too Many Requests.

Responses headers include: X-RateLimit-Limit and X-RateLimit-Remaining and x-ratelimit-reset.

Standard HTTP codes with JSON body:

• 400 invalid params
• 401 missing/invalid token
• 403 forbidden (including not allowed for your tier(
• 404 not found
• 429 rate limited
• 5xx transient server error

You have used you allowed quota for this week. Quota will automatically replenish. You can check your status and time of replenishment via the API endpoint info using data_field user_info. This is easy on /docs, or you can use query directly, e.g.:

 curl -X 'GET' \
  'https://beta.thebitcoinresearcher.net/v2/info/user_info' \
  -H 'accept: application/json' \
  -H 'X-API-Token: YOUR-TOKEN'

Prefer server-side calls. Fetch data on your server and relay it to the client—this keeps your API token private and avoids CORS issues.

Browsers are not designed for very large datasets. For heavy queries, paginate by time and prefer output_format=csv for downloads.

Visit the System Status dashboard for a quick overview of backend ingestion and API freshness.
You can also query the API endpoint Info System and User with data_field system_info.
This is easy on /docs, or you can call it directly, e.g.:

 curl -X 'GET' \
  'https://beta.thebitcoinresearcher.net/v2/info/system_info' \
  -H 'accept: application/json' \
  -H 'X-API-Token: YOUR-TOKEN'

Data is updated continously as new blocks hit the chain.
Expect a few minutes delay to ensure no forks and to process the new data.

Aggregated data summarize metrics over fixed time intervals (e.g., 1-hour, 4-hour, 1-day). The aggregation method depends on the metric and may include:

• Last value – commonly used for unspent outputs.
• Mean (average) – typical for spent outputs.
• Weighted average – values weighted by number or value of outputs, often for spent outputs.
• Median, minimum, or maximum – used where appropriate.