Skip to main content
GET
https://api.polaris.supply
/
download
Download
curl --request GET \
  --url https://api.polaris.supply/download
{
  "redirect": "<string>",
  "url": "<string>",
  "expires_in_seconds": 123
}
Use GET /download when you already have a snapshot key from Snapshots and want to fetch the file itself. This endpoint does not require an Authorization header for open datasets. Bearer auth (or machine payment) is only required when the dataset access policy for the snapshot requires it. The endpoint auto-detects whether the key refers to a standard hourly snapshot or a raw snapshot based on the key prefix (standard- vs raw-).

​
Endpoint

GET /download

​
Parameters

​
key
string
required
Snapshot key returned by GET /snapshots, such as standard-hyperliquid-BTC-USD-2026-05-07-00 for standard files, or a raw snapshot key like raw-hyperliquid-BTC-USD-2026-05-07-000000 from a GET /snapshots?raw=true listing.
​
mode
string
Optional response mode. Use url or json to receive JSON with a pre-signed URL instead of a 302 redirect.

​
Access behavior

  • Bearer auth is only required when the dataset access policy for the snapshot requires it.
  • For restricted datasets, machine payment (x402 / MPP) is also accepted as an alternative to bearer auth.
  • mode=url and mode=json both return JSON with url and expires_in_seconds.

​
Key detection

The endpoint auto-detects the snapshot type by key prefix:
Key prefixType
standard-…Standard hourly snapshot
raw-…Raw snapshot (requires paid auth)

​
Response fields

​
redirect
string
The endpoint typically responds with a 302 redirect to the downloadable snapshot file.
​
url
string
Pre-signed download URL when you request mode=url or mode=json.
​
expires_in_seconds
number
Lifetime of the pre-signed URL, typically 86400 (24 hours).
The downloaded .jsonl.zst file contains standardized event records for standard keys, or venue-native payloads for raw keys. See Standardised formats for the event envelope inside standard files.

​
Example

curl -L \
  "https://api.polaris.supply/download?key=standard-hyperliquid-BTC-USD-2026-05-07-00" \
  -o hyperliquid_BTC-USD_2026-05-07_00.jsonl.zst
JSON mode example: 
curl "https://api.polaris.supply/download?key=standard-hyperliquid-BTC-USD-2026-05-07-00&mode=json"

{
  "url": "https://storage.polaris.supply/...",
  "expires_in_seconds": 86400
}

​
Error behavior

  • 400 for a missing or invalid key
  • 401 when bearer auth is required by dataset policy
  • 402 when the dataset requires payment and no auth or payment is provided
  • 403 for forbidden key prefixes
  • 404 when the snapshot file is not found

​
Next steps

  • Read Snapshots if you need to list available files before downloading one.
  • Read Standardised formats to understand the event envelope inside snapshot files.