REST API v1

TarDraw Developer API

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

Get API key Quick start

Box operations

List and open any active box

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 box 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/boxes 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/boxes

List boxes

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

bash

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

Response 200

json

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

GET/v1/boxes/:idOrSlug

Get box

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

bash

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

POST/v1/boxes/:idOrSlug/open

Open box

Opens a box 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/boxes/luxury-watch-box/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 openBox(slug) {
  const res = await fetch(`${BASE}/v1/boxes/${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	Box 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.