Clarity is part of the contract.
Everything you need to explore the current sample API. One endpoint, four datasets, and no hidden assumptions.
01 / Make your first request
The sample endpoint is a real HTTP GET route. It returns fixed synthetic fixtures, requires no key, and accepts no user data. Replace YOUR_DOMAIN with the domain serving your deployed copy.
curl --fail --silent --show-error \ "https://YOUR_DOMAIN/api/sample?dataset=market&symbol=BTC-USDT"On an owner-private preview, external scripts may be blocked by site access controls. Use the browser playground or deploy the server edition for direct HTTP access.
Run it in the playground02 / Choose your parameters
GET /api/sample
| Parameter | Accepted values | Default |
|---|---|---|
| dataset | market, candles, funding, open-interest | market |
| symbol | BTC-USDT, ETH-USDT, SOL-USDT | BTC-USDT |
Values are case-sensitive. Unsupported values return HTTP 400. Omitted parameters use the defaults. On-chain and research features are roadmap entries with no endpoint yet.
03 / Read the response contract
| Common field | Definition |
|---|---|
| mode | Always synthetic_sample for this endpoint. |
| schema_version | Contract version, currently 1.0. |
| dataset / symbol | Requested dataset identifier and canonical base-quote instrument. |
| source / venue | cryptodataset_demo_fixture / SIMULATED; no exchange is connected. |
| as_of | Fixed fixture timestamp: 2026-01-01T12:00:00Z. |
| quality | status: synthetic and live: false. |
| license | Describes sample status; does not grant third-party data rights. |
| data | Dataset-specific object; array of six intervals for candles. |
Units and timestamps
- Prices and financial quantities use decimal strings. Use decimal arithmetic in applications that need precise accounting.
- Instrument names follow BASE-QUOTE. All current fixtures use USDT as the quote currency.
- Timestamps use UTC and ISO 8601. Candle time identifies the interval start. Six hourly sample bars cover 06:00–12:00 UTC on January 1, 2026.
- Funding rates are decimal fractions: 0.0001 means 0.01%. A positive value means longs pay shorts; the sample period is eight hours.
- Change values ending in _pct are percentage points: 2.4 means a 2.4% change, not 240%.
Inspect each dataset’s fields in the dataset catalog. HTTP responses include X-Data-Mode: synthetic-sample and public caching for 300 seconds.
04 / Handle errors explicitly
{ "error": { "code": "INVALID_PARAMETER", "message": "Choose a supported dataset and symbol.", "datasets": ["market", "candles", "funding", "open-interest"], "symbols": ["BTC-USDT", "ETH-USDT", "SOL-USDT"] }}Check the HTTP status before using the payload. Production rate limits, authentication errors, and service guarantees have not been defined. Do not use the sample endpoint for trading, valuation, or backtests.
05 / Context travels with data
CryptoDataset’s brand promise is a product design principle: every future production dataset should publish where data came from, when it was observed, what transformations were applied, and what its license permits.
- Declare the source. Venue and upstream provider identifiers must accompany market observations.
- Separate observation from processing. Collection time, event time, correction time, and schema version should be distinguishable.
- Show data quality. Missing intervals, outages, duplicates, and corrections should be visible, not silently filled.
- Respect the data contract. Record transformations and units; make breaking changes explicit.
These are principles for the planned service. The current release implements synthetic fixtures and metadata, not a production ingestion or validation pipeline.
06 / What happens next
The next product milestone is a small, licensed live-data pilot: validate one customer use case, confirm redistribution rights, connect an upstream source, and publish measured coverage and reliability before selling API access.
Proposed subscriptions are product hypotheses. The website does not process payments, issue API keys, or deliver a paid data service. The MySQL server package stores consented early-access requests after you configure and deploy it.
View proposed plans