cURL Examples

This page provides ready-to-use cURL examples for all major API operations.

Setup

Set your API key as an environment variable for convenience:

export TICKSUPPLY_API_KEY="your_api_key_here"

Catalog operations

List exchanges

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

Response

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

List instruments

# List all instruments for Binance
curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/exchanges/binance/instruments

# Search for BTC pairs with limit
curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  "https://api.ticksupply.com/v1/exchanges/binance/instruments?search=BTC&limit=10"

Response

{
  "items": [
    {
      "symbol": "BTCUSDT",
      "base": "BTC",
      "quote": "USDT",
      "instrument_type": "spot"
    },
    {
      "symbol": "BTCBUSD",
      "base": "BTC",
      "quote": "BUSD",
      "instrument_type": "spot"
    }
  ],
  "total": 1500,
  "limit": 100,
  "next_page_token": "eyJpZCI6MTB9"
}

List datastreams

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

Response

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

Subscription operations

Create a subscription

curl -X POST -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -d '{"datastream_id": 123}' \
  https://api.ticksupply.com/v1/subscriptions

Response

{
  "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": []
}

List subscriptions

# List first 20 subscriptions
curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  "https://api.ticksupply.com/v1/subscriptions?limit=20"

# Get next page
curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  "https://api.ticksupply.com/v1/subscriptions?limit=20&page_token=TOKEN"

Response

{
  "items": [
    {
      "id": "sub_550e8400e29b41d4a716446655440000",
      "datastream_id": 123,
      "status": "active",
      "created_at": "2024-12-21T12:00:00Z",
      "datastream": {
        "datastream_id": 123,
        "exchange": "binance",
        "instrument": "BTCUSDT",
        "stream_type": "trades",
        "wire_format": "json"
      }
    }
  ],
  "total": 5,
  "limit": 20,
  "next_page_token": null
}

Get a specific subscription

curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/subscriptions/sub_550e8400e29b41d4a716446655440000

Pause a subscription

curl -X POST -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/subscriptions/sub_550e8400e29b41d4a716446655440000/pause

Returns 204 No Content on success.

Resume a subscription

curl -X POST -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/subscriptions/sub_550e8400e29b41d4a716446655440000/resume

Returns 204 No Content on success.

Get subscription spans

curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/subscriptions/sub_550e8400e29b41d4a716446655440000/spans

Response

[
  {
    "id": "spn_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
    "started_at": "2024-12-21T12:00:00Z",
    "ended_at": null
  }
]

Delete a subscription

curl -X DELETE -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  https://api.ticksupply.com/v1/subscriptions/sub_550e8400e29b41d4a716446655440000

Returns 204 No Content on success.

Export operations

Create an export

# Export last 24 hours (calculate timestamps in nanoseconds)
NOW_NS=$(python3 -c "import time; print(int(time.time() * 1e9))")
DAY_AGO_NS=$(python3 -c "import time; print(int((time.time() - 86400) * 1e9))")

curl -X POST -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -d "{\"datastream_id\": 123, \"start_time\": \"$DAY_AGO_NS\", \"end_time\": \"$NOW_NS\"}" \
  https://api.ticksupply.com/v1/exports

Response

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

List exports

curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  "https://api.ticksupply.com/v1/exports?limit=10"

Response

{
  "items": [
    {
      "id": "exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
      "datastream_id": 123,
      "start_time": 1703116800000000000,
      "end_time": 1703203200000000000,
      "format": "csv",
      "status": "succeeded",
      "created_at": "2024-12-21T13:00:00Z",
      "started_at": "2024-12-21T13:00:05Z",
      "finished_at": "2024-12-21T13:01:30Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "next_page_token": null
}

Get export details

curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/exports/exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4

Response

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

Download export

# Get presigned URLs for all artifacts
curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/exports/exp_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4/download

# Download each artifact using its URL
curl -o "binance_BTCUSDT_trades_part_001.csv.gz" "PRESIGNED_URL_FROM_ARTIFACTS_ARRAY"

Response

{
  "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
}

Export schema operations

Create a custom schema

curl -X POST -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_trades",
    "stream_category": "trade",
    "unfold": {
      "bybit_linear": { "path": "data" }
    },
    "columns": [
      { "output_column": "timestamp_ns", "meta": { "value": "collection_timestamp_ns", "format": "ns" } },
      { "output_column": "price", "data": {
          "binance": { "json": { "path": "data.p", "type": "decimal(18)" } },
          "bybit_linear": { "json": { "path": "data.p", "type": "decimal(18)" } }
      }},
      { "output_column": "side", "data": {
          "binance": { "json": { "path": "data.m", "type": "bool" }, "transform": "CASE WHEN {v} = false THEN '\''buy'\'' ELSE '\''sell'\'' END" },
          "bybit_linear": { "json": { "path": "data.S", "type": "string" } }
      }}
    ]
  }' \
  https://api.ticksupply.com/v1/export-schemas

List schemas

curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/export-schemas

Use a schema in an export

curl -X POST -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -d "{\"datastream_id\": 123, \"start_time\": \"$DAY_AGO_NS\", \"end_time\": \"$NOW_NS\", \"schema\": \"my_trades\"}" \
  https://api.ticksupply.com/v1/exports

Delete a schema

curl -X DELETE -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  https://api.ticksupply.com/v1/export-schemas/sch_0194a1b2c3d4e5f6a7b8c9d0e1f2a3b4

Returns 204 No Content on success.

Availability

Check data availability

curl -H "X-Api-Key: $TICKSUPPLY_API_KEY" \
  "https://api.ticksupply.com/v1/availability?datastream_id=123"

Response

{
  "datastream": {
    "datastream_id": 123,
    "exchange": "binance",
    "instrument": "BTCUSDT",
    "stream_type": "trades",
    "wire_format": "json"
  },
  "ranges": [
    {
      "from": 1701388800000000000,
      "to": 1703160000000000000,
      "rows_estimate": 5000000
    }
  ],
  "updated_at": "2024-12-21T12:30:00Z"
}

Complete workflow example

Here’s a complete script that subscribes to data and exports it:

#!/bin/bash
set -e

API_KEY="$TICKSUPPLY_API_KEY"
BASE_URL="https://api.ticksupply.com"

# 1. Find datastream ID for BTCUSDT trades
echo "Finding BTCUSDT trade stream..."
DATASTREAM_ID=$(curl -s -H "X-Api-Key: $API_KEY" \
  "$BASE_URL/v1/datastreams?exchange=binance&instrument=BTCUSDT&stream_type=trades" \
  | jq '.items[0].datastream_id')

echo "Found datastream ID: $DATASTREAM_ID"

# 2. Create subscription
echo "Creating subscription..."
SUB_RESPONSE=$(curl -s -X POST -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -d "{\"datastream_id\": $DATASTREAM_ID}" \
  "$BASE_URL/v1/subscriptions")

SUB_ID=$(echo $SUB_RESPONSE | jq -r '.id')
echo "Subscription created: $SUB_ID"

# 3. Wait for some data to be collected
echo "Waiting 60 seconds for data collection..."
sleep 60

# 4. Create export
NOW_NS=$(python3 -c "import time; print(int(time.time() * 1e9))")
HOUR_AGO_NS=$(python3 -c "import time; print(int((time.time() - 3600) * 1e9))")

echo "Creating export..."
EXPORT_RESPONSE=$(curl -s -X POST -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -d "{\"datastream_id\": $DATASTREAM_ID, \"start_time\": \"$HOUR_AGO_NS\", \"end_time\": \"$NOW_NS\"}" \
  "$BASE_URL/v1/exports")

EXPORT_ID=$(echo $EXPORT_RESPONSE | jq -r '.id')
echo "Export created: $EXPORT_ID"

# 5. Poll for completion
echo "Waiting for export to complete..."
while true; do
  STATUS=$(curl -s -H "X-Api-Key: $API_KEY" \
    "$BASE_URL/v1/exports/$EXPORT_ID" | jq -r '.status')

  echo "Status: $STATUS"

  if [ "$STATUS" = "succeeded" ]; then
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Export failed!"
    exit 1
  fi

  sleep 5
done

# 6. Download all artifacts
echo "Downloading export..."
DOWNLOAD_RESPONSE=$(curl -s -H "X-Api-Key: $API_KEY" \
  "$BASE_URL/v1/exports/$EXPORT_ID/download")

# Download each artifact
echo "$DOWNLOAD_RESPONSE" | jq -r '.artifacts[] | "\(.url) \(.filename)"' | while read url filename; do
  echo "Downloading $filename..."
  curl -o "$filename" "$url"
done

echo "Download complete"

Getting Started

Guides

Examples

cURL Examples

cURL Examples

Setup

Catalog operations

List exchanges

List instruments

List datastreams

Subscription operations

Create a subscription

List subscriptions

Get a specific subscription

Pause a subscription

Resume a subscription

Get subscription spans

Delete a subscription

Export operations

Create an export

List exports

Get export details

Download export

Export schema operations

Create a custom schema

List schemas

Use a schema in an export

Delete a schema

Availability

Check data availability

Complete workflow example

​cURL Examples

​Setup

​Catalog operations

​List exchanges

​List instruments

​List datastreams

​Subscription operations

​Create a subscription

​List subscriptions

​Get a specific subscription

​Pause a subscription

​Resume a subscription

​Get subscription spans

​Delete a subscription

​Export operations

​Create an export

​List exports

​Get export details

​Download export

​Export schema operations

​Create a custom schema

​List schemas

​Use a schema in an export

​Delete a schema

​Availability

​Check data availability

​Complete workflow example

cURL Examples

Setup

Catalog operations

List exchanges

List instruments

List datastreams

Subscription operations

Create a subscription

List subscriptions

Get a specific subscription

Pause a subscription

Resume a subscription

Get subscription spans

Delete a subscription

Export operations

Create an export

List exports

Get export details

Download export

Export schema operations

Create a custom schema

List schemas

Use a schema in an export

Delete a schema

Availability

Check data availability

Complete workflow example