Skip to main content

​
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": "coinbase",
    "display_name": "Coinbase"
  }
]

​
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=trade"
Response
{
  "items": [
    {
      "datastream_id": 123,
      "exchange": "binance",
      "instrument": "BTCUSDT",
      "stream_type": "trade",
      "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": "trade",
    "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": "trade",
        "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,
  "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,
      "status": "succeeded",
      "created_at": "2024-12-21T13:00:00Z",
      "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
}

​
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": "trade",
    "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=trade" \
  | 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"