Ticaro API — Documentation

Get a key →

Base URL

https://ticaro.ir

All endpoints are served over HTTPS. The API is versioned at /api/v1/. All endpoints require an API key or JWT — anonymous access is not permitted.

Authentication

All API endpoints require authentication. Send your API key in either of these headers on every request:

Option 1 — X-API-Key header (recommended)

Option 2 — Authorization header

API keys start with pa_. Keys are shown only once on creation — store them securely. Generate keys at /panel/api-keys.

Rate Limits

Client type	Default limit	Bucket
API key (global default)	60 req / min	Per user
API key (custom override)	configured by admin	Per API key

Every response includes rate-limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1748779260
X-RateLimit-Window: 1m0s

When exceeded, you receive 429 Too Many Requests with a Retry-After header.

Error Format

All errors follow a consistent JSON structure:

{
  "error": "error_code",
  "message": "Human-readable description"
}

HTTP Status	error code	Meaning
400	invalid_request	Malformed body or missing required fields
401	unauthorized	Missing or invalid API key / JWT
403	forbidden	Insufficient permissions (role check)
404	not_found	Resource does not exist
429	rate limit exceeded	Too many requests — check Retry-After header
500	internal_error	Server error — retry with back-off

Price & History Endpoints

GET /api/v1/prices All live prices

Returns the latest aggregated price for every asset visible in the API. Requires API key or JWT.

Request

curl https://ticaro.ir/api/v1/prices

Response — 200 OK

{
  "data": [
    {
      "symbol":         "BTC",
      "quote_currency": "USDT",
      "pair":           "BTC/USDT",
      "name":           "بیت‌کوین",
      "category":       "crypto",
      "price":          105230.5,
      "source":         "binance",
      "confidence":     0.95,
      "change_24h":     2.34,
      "volume_24h":     184200000,
      "fetched_at":     "2026-05-22T09:00:00Z"
    },
    {
      "symbol":         "USD",
      "quote_currency": "TMN",
      "pair":           "USD/TMN",
      "name":           "دلار آمریکا",
      "category":       "currency",
      "price":          122450.0,
      "source":         "tgju",
      "confidence":     0.92,
      "change_24h":     0.12,
      "fetched_at":     "2026-05-22T09:00:01Z"
    }
  ]
}

category — one of: currency, gold, crypto, oil, index, forex, precious_metal, base_metal, agriculture

confidence — 0–1 score; aggregated from multiple sources when available

change_24h — percentage change vs 24 h ago; null if unavailable

GET /api/v1/prices/{symbol}/{quote} Single pair

Latest price for a specific trading pair. Symbol and quote are case-insensitive.

symbol — e.g. BTC, USD, GOLD18, XAU

quote — e.g. USDT, TMN, USD, IRT

Request

curl https://ticaro.ir/api/v1/prices/USD/TMN

Response — 200 OK

{
  "data": {
    "symbol":         "USD",
    "quote_currency": "TMN",
    "pair":           "USD/TMN",
    "name":           "دلار آمریکا",
    "category":       "currency",
    "price":          122450.0,
    "source":         "tgju",
    "confidence":     0.92,
    "change_24h":     0.12,
    "fetched_at":     "2026-05-22T09:00:01Z"
  }
}

Returns 404 if the pair has no data or is not visible.

GET /api/v1/history/{symbol}/{quote}/candles OHLC candles

Returns OHLC candlestick data from ClickHouse. Useful for charting. Requires API key or JWT.

Param	Type	Default	Description
from	string (RFC3339)	24h ago	Start of range
to	string (RFC3339)	now	End of range
limit	integer	100	Max candles (max 1000)

Request — last 2 hours of USD/TMN

curl "https://ticaro.ir/api/v1/history/USD/TMN/candles?from=2026-05-22T07:00:00Z&to=2026-05-22T09:00:00Z&limit=120"

Response — 200 OK

{
  "data": [
    {
      "bucket": "2026-05-22T07:00:00Z",
      "open":   122100.0,
      "high":   122500.0,
      "low":    122050.0,
      "close":  122450.0,
      "count":  14
    }
  ]
}

count — number of raw ticks in that 1-minute bucket. bucket is always the start of the minute in UTC.

GET /api/v1/history/{symbol}/{quote}/ticks Raw ticks

Raw price ticks stored in ClickHouse. Maximum retention window: last 15 minutes. Use candles for longer ranges.

Param	Type	Default	Description
limit	integer	50	Max ticks returned (max 500)

Request

curl "https://ticaro.ir/api/v1/history/BTC/USDT/ticks?limit=20"

Response — 200 OK

{
  "data": [
    {
      "price":      105230.5,
      "source":     "binance",
      "confidence": 0.95,
      "fetched_at": "2026-05-22T09:09:30Z"
    }
  ]
}

GET /api/v1/history/{symbol}/{quote}/indicators Technical indicators

Server-side calculation of technical indicators from OHLCV candle history. Requires API key or JWT.

Parameter	Type	Default	Description
interval	string	1h	1m, 5m, 15m, 1h, 4h, 1d
from / to	string	24h ago / now	RFC3339 time range
indicators	string	rsi,macd,bb,ema20,ema50	Comma-separated: rsi, rsi7, rsi21, macd, ema9, ema20, ema50, ema200, sma20, sma50, sma200, bb, atr, stoch, cci, williamsr, obv

Example

curl "https://ticaro.ir/api/v1/history/BTC/USDT/indicators?interval=1h&indicators=rsi,macd,bb,ema20,stoch,atr"

Response

{
  "symbol": "BTC", "quote": "USDT", "interval": "1h",
  "data": [
    {
      "time": "2024-01-01T01:00:00Z",
      "value": {
        "rsi_14": 58.34,
        "macd_line": 124.5, "signal": 118.2, "histogram": 6.3,
        "bb_upper": 42800.0, "bb_middle": 42500.0, "bb_lower": 42200.0,
        "ema_20": 42480.5,
        "stoch_k": 72.4, "stoch_d": 68.1,
        "atr_14": 350.2
      }
    }
  ]
}

Authenticated Endpoints

GET /api/v1/assets List assets

Returns all active assets with metadata. Requires API key.

Request

Response — 200 OK

{
  "data": [
    {
      "id":               1,
      "symbol":           "BTC",
      "quote_currency":   "USDT",
      "pair":             "BTC/USDT",
      "name":             "Bitcoin",
      "display_name":     "بیت‌کوین",
      "asset_type":       "crypto",
      "category":         "crypto",
      "decimal_precision": 2,
      "is_active":        true,
      "is_visible":       true,
      "created_at":       "2026-01-01T00:00:00Z"
    }
  ]
}

GET /api/v1/assets/{id} Single asset + sources

Returns a single asset by numeric ID.

Request

GET /api/v1/users/me Current user

Returns the authenticated user's profile.

Request

Response — 200 OK

{
  "data": {
    "id":         42,
    "email":      "you@example.com",
    "role":       "user",
    "is_active":  true,
    "created_at": "2026-01-15T10:00:00Z"
  }
}

GET /api/v1/api-keys List your API keys

Returns all API keys belonging to the authenticated user. JWT required — cannot use an API key to list keys.

Request

Response — 200 OK

{
  "data": [
    {
      "id":                   7,
      "name":                 "production",
      "prefix":               "pa_a1b2c3d4e5f6",
      "rate_limit_override":  0,
      "expires_at":           null,
      "last_used_at":         "2026-05-22T08:50:00Z",
      "created_at":           "2026-03-01T12:00:00Z"
    }
  ]
}

POST /api/v1/api-keys Create API key

Creates a new API key. The raw key is returned only once — store it immediately. JWT required.

Field	Type	Required	Description
name	string	Yes	Label for this key (max 100 chars)
expires_at	string (RFC3339)	No	Expiry date; omit for no expiry

Request

Response — 201 Created

{
  "data": {
    "id":         8,
    "name":       "my-app",
    "prefix":     "pa_a1b2c3d4e5f6",
    "key":        "pa_a1b2c3d4e5f6...(full key shown once)",
    "expires_at": "2027-01-01T00:00:00Z",
    "created_at": "2026-05-22T09:00:00Z"
  },
  "message": "Store this key securely — it will not be shown again."
}

DELETE /api/v1/api-keys/{id} Revoke API key

Permanently revokes an API key. JWT required. Users can only delete their own keys.

Request

Response — 200 OK

{ "message": "api key revoked" }

Real-time WebSocket

WS wss://ticaro.ir/ws/prices Real-time stream

Connect once, receive live price updates pushed from crawlers as they arrive. No polling needed. Pass your API key as ?token=pa_... query parameter.

Connect (authenticated)

JavaScript — browser / Node.js

Python

Message format

{
  "BTC/USDT": {
    "symbol":         "BTC",
    "quote_currency": "USDT",
    "price":          105230.5,
    "source":         "binance",
    "confidence":     0.95,
    "change_24h":     2.34,
    "fetched_at":     "2026-05-22T09:10:00Z"
  },
  "USD/TMN": {
    "symbol":         "USD",
    "quote_currency": "TMN",
    "price":          122450.0,
    "source":         "tgju",
    "confidence":     0.92,
    "fetched_at":     "2026-05-22T09:10:01Z"
  }
}

Rate limit: connections use the API key/user rate limit.

Reconnect: use exponential back-off (start at 1s, cap at 30s) — the server may disconnect on idle or restart.

Live WebSocket Test

Press Connect to start receiving live price updates…

Ticaro Price API — Health status