> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticksupply.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get your first data export from Ticksupply in under 5 minutes

# 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](https://ticksupply.com))
* An API key from your [dashboard](https://app.ticksupply.com/api-keys)
* Python 3.10+ (for the Python examples)

<Warning>
  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.
</Warning>

Install the official Python client:

```bash theme={"system"}
pip install ticksupply
```

## Step 1: Verify your API key

Test that your API key works by listing available exchanges:

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -H "X-Api-Key: YOUR_API_KEY" \
    https://api.ticksupply.com/v1/exchanges
  ```

  ```python Python theme={"system"}
  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}")
  ```

  ```javascript JavaScript theme={"system"}
  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);
  ```
</CodeGroup>

You should see a list of available exchanges:

```json theme={"system"}
[
  {
    "code": "binance",
    "display_name": "Binance"
  },
  {
    "code": "okx_spot",
    "display_name": "OKX Spot"
  }
]
```

<Check>
  If you see the exchange list, your API key is working correctly.
</Check>

## 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:

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -H "X-Api-Key: YOUR_API_KEY" \
    "https://api.ticksupply.com/v1/datastreams?exchange=binance&instrument=BTCUSDT&stream_type=trades"
  ```

  ```python Python theme={"system"}
  result = client.datastreams.list(
      exchange="binance",
      instrument="BTCUSDT",
      stream_type="trades"
  )
  datastream_id = result.items[0].datastream_id
  print(f"Found datastream: {datastream_id}")
  ```
</CodeGroup>

The response is a paginated list of available datastreams:

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

<Tip>
  Note the `datastream_id` value—you'll need it to create a subscription.
</Tip>

## Step 3: Create a subscription

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

<CodeGroup>
  ```bash cURL theme={"system"}
  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
  ```

  ```python Python theme={"system"}
  sub = client.subscriptions.create(datastream_id=123)
  print(f"Subscription: {sub.id}, status: {sub.status}")
  ```
</CodeGroup>

```json theme={"system"}
{
  "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": []
}
```

<Check>
  Data collection has started! The system is now recording trades as they happen.
</Check>

## Step 4: Create an export

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

<Note>
  Timestamps are in **nanoseconds** since Unix epoch. You can use integers or strings for large numbers.
</Note>

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](/guides/export-schemas).

<CodeGroup>
  ```bash cURL theme={"system"}
  # 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
  ```

  ```python Python theme={"system"}
  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}")
  ```
</CodeGroup>

```json theme={"system"}
{
  "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:

<CodeGroup>
  ```bash cURL theme={"system"}
  # 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
  ```

  ```python Python theme={"system"}
  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}")
  ```
</CodeGroup>

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

```json theme={"system"}
{
  "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
}
```

<Check>
  Download each artifact using its URL. Files are gzipped CSVs with your tick data.
</Check>

## Next steps

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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/getting-started/authentication">
    Learn about API key management and best practices
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/guides/rate-limiting">
    Understand rate limits and how to handle them
  </Card>

  <Card title="Pagination" icon="list" href="/guides/pagination">
    Handle large result sets efficiently
  </Card>

  <Card title="Export Schemas" icon="table-columns" href="/guides/export-schemas">
    Customize export output with column mappings
  </Card>

  <Card title="Error Handling" icon="circle-exclamation" href="/guides/error-handling">
    Handle errors gracefully in your application
  </Card>
</CardGroup>