Quickstart

This guide walks you through creating your first subscription and exporting data from Ticksupply. By the end, you’ll have downloaded historical trade data for analysis.

Prerequisites

Before you begin, you need:

A Ticksupply account (sign up here)
An API key from your dashboard
Python 3.10+ (for the Python examples)

Keep your API key secure. Never commit it to version control or share it publicly. All requests made with your key are associated with your account.

Install the official Python client:

pip install ticksupply

Step 1: Verify your API key

Test that your API key works by listing available exchanges:

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://api.ticksupply.com/v1/exchanges

from ticksupply import Client

client = Client(api_key="YOUR_API_KEY")
exchanges = client.exchanges.list()
for ex in exchanges:
    print(f"{ex.code}: {ex.display_name}")

const response = await fetch("https://api.ticksupply.com/v1/exchanges", {
  headers: { "X-Api-Key": "YOUR_API_KEY" }
});
const exchanges = await response.json();
console.log(exchanges);

You should see a list of available exchanges:

[
  {
    "code": "binance",
    "display_name": "Binance"
  },
  {
    "code": "okx_spot",
    "display_name": "OKX Spot"
  }
]

If you see the exchange list, your API key is working correctly.

Step 2: Find the data stream you want

Browse available data streams for a specific exchange and trading pair. Let’s find Binance BTCUSDT trades:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.ticksupply.com/v1/datastreams?exchange=binance&instrument=BTCUSDT&stream_type=trades"

result = client.datastreams.list(
    exchange="binance",
    instrument="BTCUSDT",
    stream_type="trades"
)
datastream_id = result.items[0].datastream_id
print(f"Found datastream: {datastream_id}")

The response is a paginated list of available datastreams:

{
  "items": [
    {
      "datastream_id": 123,
      "exchange": "binance",
      "instrument": "BTCUSDT",
      "stream_type": "trades",
      "wire_format": "json"
    }
  ],
  "total": 1,
  "limit": 100,
  "next_page_token": null
}

Note the datastream_id value—you’ll need it to create a subscription.

Step 3: Create a subscription

Start collecting data by creating a subscription. Replace 123 with your actual datastream ID:

curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datastream_id": 123}' \
  https://api.ticksupply.com/v1/subscriptions

sub = client.subscriptions.create(datastream_id=123)
print(f"Subscription: {sub.id}, status: {sub.status}")

{
  "id": "sub_550e8400e29b41d4a716446655440000",
  "status": "active",
  "datastream": {
    "datastream_id": 123,
    "exchange": "binance",
    "instrument": "BTCUSDT",
    "stream_type": "trades",
    "wire_format": "json"
  },
  "created_at": "2024-12-21T12:00:00Z",
  "spans": []
}

Data collection has started! The system is now recording trades as they happen.

Step 4: Create an export

After your subscription has been collecting data (even for just a few minutes), you can export it.

Timestamps are in nanoseconds since Unix epoch. You can use integers or strings for large numbers.

Create an export for a specific time range. By default, exports use the raw schema (timestamp + raw JSON). For structured columns, you can specify a built-in or custom schema.

# Export last hour of data
# Calculate timestamps: now - 1 hour to now, in nanoseconds
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datastream_id": 123,
    "start_time": "1703116800000000000",
    "end_time": "1703120400000000000"
  }' \
  https://api.ticksupply.com/v1/exports

from datetime import datetime, timedelta, timezone

end = datetime.now(timezone.utc)
start = end - timedelta(hours=1)

job = client.exports.create(
    datastream_id=123,
    start_time=start,
    end_time=end,
)
print(f"Export created: {job.id}")

{
  "id": "exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
  "datastream_id": 123,
  "start_time": 1703116800000000000,
  "end_time": 1703203200000000000,
  "format": "csv",
  "status": "queued",
  "created_at": "2024-12-21T13:00:00Z",
  "started_at": null,
  "finished_at": null
}

Step 5: Check export status and download

Poll the export status until it completes:

# Check status
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://api.ticksupply.com/v1/exports/exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4

# When status is "succeeded", get download URLs
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://api.ticksupply.com/v1/exports/exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4/download

import time

# Poll until complete
while True:
    job = client.exports.get(job.id)
    if job.status.value == "succeeded":
        break
    elif job.status.value == "failed":
        raise Exception("Export failed")
    print(f"Status: {job.status}, waiting...")
    time.sleep(5)

# Get download URLs
download = client.exports.get_download(job.id)
for artifact in download.artifacts:
    print(f"Download: {artifact.filename} ({artifact.bytes:,} bytes)")
    print(f"URL: {artifact.url}")

The download endpoint returns presigned URLs (valid for 5 minutes) for all export artifacts:

{
  "artifacts": [
    {
      "id": "art_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
      "url": "https://tickstore-exports.s3.amazonaws.com/exports/...",
      "bytes": 524288000,
      "filename": "binance_BTCUSDT_trades_part_001.csv.gz"
    }
  ],
  "count": 1,
  "total_bytes": 524288000
}

Download each artifact using its URL. Files are gzipped CSVs with your tick data.

Next steps

Now that you’ve completed your first export, explore these resources:

Authentication

Learn about API key management and best practices

Rate Limiting

Understand rate limits and how to handle them

Pagination

Handle large result sets efficiently

Export Schemas

Customize export output with column mappings

Error Handling

Handle errors gracefully in your application

Getting Started

Guides

Examples

Quickstart

Quickstart

Prerequisites

Step 1: Verify your API key

Step 2: Find the data stream you want

Step 3: Create a subscription

Step 4: Create an export

Step 5: Check export status and download

Next steps

Authentication

Rate Limiting

Pagination

Export Schemas

Error Handling

​Quickstart

​Prerequisites

​Step 1: Verify your API key

​Step 2: Find the data stream you want

​Step 3: Create a subscription

​Step 4: Create an export

​Step 5: Check export status and download

​Next steps

Authentication

Rate Limiting

Pagination

Export Schemas

Error Handling

Quickstart

Prerequisites

Step 1: Verify your API key

Step 2: Find the data stream you want

Step 3: Create a subscription

Step 4: Create an export

Step 5: Check export status and download

Next steps