REST API v1

TarDraw Developer API

Programmatic access to TarDraw packs. List available packs, open them, and receive provably-fair outcomes — perfect for bots, automation, and custom integrations.

Get API key Quick start

Pack operations

List and open any active pack

Secure keys

Bearer auth with hashed storage

Real outcomes

Same fairness engine as the web app

Overview

The TarDraw API is a simple REST interface authenticated with API keys. Each key is tied to your account — opens debit your wallet balance and items land in your inventory, exactly like opening a pack on the website.

Generate keys from Settings → API. Keys are shown once at creation; store them securely.

Authentication

Send your API key on every request using either header:

Authorization: Bearer td_live_… (recommended)
X-Api-Key: td_live_…

http

GET /v1/packs HTTP/1.1
Host: api.tardraw.com
Authorization: Bearer td_live_abc123xyz...

Base URL

All endpoints are relative to:

https://api.tardraw.com

GET/v1/packs

List packs

Returns all active packs with pricing, images, and metadata. Use the slug or id from this response when opening a pack.

bash

curl -s "https://api.tardraw.com/v1/packs" \
  -H "Authorization: Bearer td_live_YOUR_API_KEY"

Response 200

json

[
  {
    "id": "clx...",
    "slug": "luxury-watch-card",
    "name": "Luxury Watch Card",
    "image": "/uploads/packs/...",
    "price": "49.99",
    "category": "WATCHES",
    "rarityTheme": "GOLD",
    "maxItemValue": 12500,
    "spinCount": 4821
  }
]

GET/v1/packs/:idOrSlug

Get pack

Returns full details for a single pack including all items, drop chances, and ticket ranges.

bash

curl -s "https://api.tardraw.com/v1/packs/luxury-watch-card" \
  -H "Authorization: Bearer td_live_YOUR_API_KEY"

POST/v1/packs/:idOrSlug/open

Open pack

Opens a pack for the authenticated account. Debits wallet balance, creates an inventory item, and returns the winning item with provably-fair verification data.

bash

curl -s -X POST "https://api.tardraw.com/v1/packs/luxury-watch-card/open" \
  -H "Authorization: Bearer td_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response 200

json

{
  "spin": {
    "id": "clx...",
    "packId": "clx...",
    "itemId": "clx...",
    "nonce": 42,
    "result": 873421
  },
  "item": {
    "id": "clx...",
    "name": "Rolex Submariner",
    "rarity": "LEGENDARY",
    "value": "12500.00",
    "image": "/uploads/items/..."
  },
  "inventoryItem": {
    "id": "clx...",
    "itemId": "clx...",
    "value": "12500.00"
  },
  "balanceAfter": 950.01,
  "fairness": {
    "serverSeedHash": "a3f2...",
    "clientSeed": "user_seed_...",
    "nonce": 42,
    "hash": "9b1c..."
  }
}

Node.js example

javascript

const API_KEY = process.env.TARDRAW_API_KEY;
const BASE = 'https://api.tardraw.com';

async function openCard(slug) {
  const res = await fetch(`${BASE}/v1/packs/${slug}/open`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

Errors

Errors return JSON with a message field.

Status	Meaning
401	Missing or invalid API key
403	Account banned, deleted, or email not verified
404	Pack not found or inactive
400	Insufficient wallet balance
429	Rate limit exceeded (open endpoint)

Rate limits

The open endpoint is limited to 30 requests per minute per API key. List and get endpoints follow the global API limit. If you hit a limit, wait and retry — do not hammer the API on failures.