مستندات API — تیکارو

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" }

Financial Statements — Codal

The Codal subsystem crawls financial disclosures from the Iranian Codal portal (codal.ir) and extracts structured financial statement data. All endpoints require an API key or JWT.

Pipeline: discovered → fetched → completed. Only completed versions have statement data.

GET /api/v1/codal/announcements List announcements

Returns a paginated list of financial disclosures discovered from Codal.

Param	Type	Description
symbol	string	Filter by company symbol (e.g. `خمهر`)
report_type	string	Letter category code from Codal
fiscal_year	integer	Iranian fiscal year (e.g. `1403`)
page	integer	Page number (default 1)
limit	integer	Results per page (default 20, max 100)

Request

Response — 200 OK

{
  "data": [
    {
      "id":                1,
      "tracing_no":        "12345678",
      "symbol":            "خمهر",
      "company_name":      "گروه صنعتی مهرام",
      "letter_code":       "ن-30",
      "report_type":       "annual",
      "fiscal_year":       1403,
      "period":            12,
      "latest_version_id": 16,
      "first_published_at":"2025-04-01T08:00:00Z",
      "last_published_at": "2025-04-05T10:00:00Z"
    }
  ],
  "page": 1,
  "limit": 10,
  "total": 847
}

GET /api/v1/codal/announcements/{tracingNo} Announcement detail + versions

Returns an announcement and all its versions. A letter may have multiple versions if the company filed corrections.

Request

Response — 200 OK

{
  "data": {
    "id":           1,
    "tracing_no":   "12345678",
    "symbol":       "خمهر",
    "company_name": "گروه صنعتی مهرام",
    "fiscal_year":  1403,
    "period":       12,
    "versions": [
      {
        "id":             16,
        "version_number": 1,
        "letter_serial":  "7GfSK5CN3bkM7v8Qzs6aKw==",
        "status":         "completed",
        "is_correction":  false,
        "publish_datetime":"2025-04-01T08:00:00Z",
        "title":          "صورت‌های مالی سال مالی منتهی به 1403/12/29"
      }
    ]
  }
}

GET /api/v1/codal/announcements/{tracingNo}/statements Parsed statements

Returns all financial statement tables extracted from the announcement (all versions). Each statement corresponds to one financial table (e.g. balance sheet, income statement, cash flow).

Request

Response — 200 OK

{
  "data": [
    {
      "id":              101,
      "version_id":      16,
      "page_id":         503,
      "statement_type":  "codal_datasource",
      "period_months":   12,
      "is_audited":      true,
      "is_consolidated": false,
      "scale_factor":    1000000,
      "column_headers":  ["1404/12/29", "1403/12/30", "1403/01/01"],
      "parser_name":     "codal_datasource",
      "parser_version":  "1",
      "raw_table_index": 0,
      "created_at":      "2026-06-01T10:00:00Z"
    }
  ]
}

scale_factor — multiply raw values in rows by this number to get actual amounts (e.g. 1000000 = values are in millions)

column_headers — period end dates corresponding to each column in the rows

statement_type — codal_datasource (ASPX JSON embed) or generic_table (HTML table fallback)

GET /api/v1/codal/statements/{id}/rows Statement rows

Returns the individual rows of a financial statement table, ordered by row_order. Each row has one column_values entry per period column.

Request

Response — 200 OK

{
  "data": [
    {
      "id":               5001,
      "statement_id":     101,
      "row_order":        1,
      "title_raw":        "دارایی‌های جاری",
      "title_normalized": "current_assets",
      "is_header":        true,
      "column_values": [
        { "col_index": 0, "value_raw": "12500", "value_scaled": 12500000000, "is_numeric": true },
        { "col_index": 1, "value_raw": "10800", "value_scaled": 10800000000, "is_numeric": true },
        { "col_index": 2, "value_raw": "",      "value_scaled": 0,           "is_numeric": false }
      ]
    },
    {
      "id":               5002,
      "row_order":        2,
      "title_raw":        "موجودی نقد و معادل نقد",
      "is_header":        false,
      "column_values": [
        { "col_index": 0, "value_raw": "3200", "value_scaled": 3200000000, "is_numeric": true },
        { "col_index": 1, "value_raw": "2750", "value_scaled": 2750000000, "is_numeric": true }
      ]
    }
  ]
}

value_scaled = value_raw × scale_factor from the parent statement (pre-computed)

is_header — true for section headings; use to render bolded/grouped rows

GET /api/v1/codal/versions/{id}/pages Version pages

Lists all ASPX pages fetched for a version. Each page maps to one tab of the Codal letter (e.g. balance sheet, income statement, notes).

Request

Response — 200 OK

{
  "data": [
    {
      "id":             503,
      "version_id":     16,
      "url":            "/Publisher/Capital/ASPX/FairValue.aspx?LetterSerial=7GfS...",
      "title":          "صورت وضعیت مالی",
      "status":         "parsed",
      "parser_name":    "codal_datasource",
      "parser_version": "1"
    }
  ]
}

GET /api/v1/codal/trend Time-series trend

Returns a time-series for a specific financial line item across all fiscal periods of a company. Useful for charting multi-year trends (revenue growth, asset changes, etc.).

Param	Type	Required	Description
symbol	string	Yes	Company symbol (e.g. `خمهر`)
statement_type	string	Yes	`codal_datasource` or `generic_table`
title	string	Yes	Normalized row title to track (e.g. `جمع دارایی‌ها`)
limit	integer	No	Max data points returned (default 60, max 120)

Request

Response — 200 OK

{
  "data": [
    {
      "fiscal_year":       1402,
      "period":            12,
      "publish_datetime":  "2024-04-10T08:00:00Z",
      "column_values": [
        { "col_index": 0, "value_scaled": 9800000000, "is_numeric": true }
      ]
    },
    {
      "fiscal_year":       1403,
      "period":            12,
      "publish_datetime":  "2025-04-01T08:00:00Z",
      "column_values": [
        { "col_index": 0, "value_scaled": 12500000000, "is_numeric": true }
      ]
    }
  ]
}

Only the latest version per announcement is included. Results are ordered by fiscal_year ASC then period ASC.

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