TL Trading Lab

Symbol Categories

Use this guide when you want to generate a local category mapping for symbols already present in DuckDB. The mapping is intended for scanner heatmaps, sector filters, category indexes, and manual review.

Quick Start

  1. Download and insert candles into file.db.
  2. Generate configs/symbol-categories.yaml.
  3. Review the needs_review symbols manually.
  4. Use category indexes and category ratios from the backend or Chart UI.

The generated file is:

configs/symbol-categories.yaml

Generate Categories

Run:

uv run python examples/generate_symbol_categories.py \
  --db-path file.db \
  --output configs/symbol-categories.yaml

The command:

  1. Reads distinct symbols from binance_candles.
  2. Splits each symbol into base and quote assets.
  3. Applies conservative local category rules.
  4. Writes symbols, categories, and needs_review sections.
  5. Prints a summary.

Example output:

symbols: 438
categorized: 169
uncategorized: 269
categories: 17
output: configs/symbol-categories.yaml

File Shape

The YAML file includes both symbol-first and category-first views:

symbols:
  BTCUSDT:
    base_asset: BTC
    quote_asset: USDT
    categories:
      - Layer 1
      - Store of Value

categories:
  Layer 1:
    - BTCUSDT
    - ETHUSDT

needs_review:
  - NEWTOKENUSDT

Symbols can belong to multiple categories. This is intentional because crypto assets often span more than one theme.

Review Workflow

The generator is intentionally conservative. Many symbols will be placed under Uncategorized and listed in needs_review.

Recommended workflow:

  1. Run the generator.
  2. Open configs/symbol-categories.yaml.
  3. Review needs_review.
  4. Add categories manually for important symbols.
  5. Keep uncertain symbols under Uncategorized.

Do not overfit categories. Wrong categories are usually worse than missing categories for heatmaps.

Current Rule Categories

The first generator includes local rules for categories such as:

  • AI
  • DeFi
  • DePIN
  • Exchange Token
  • Gaming Metaverse
  • Infrastructure
  • Layer 1
  • Layer 2
  • Meme
  • Oracle
  • Payments
  • Privacy
  • RWA
  • Stablecoin
  • Storage
  • Store of Value

These rules are not authoritative. They are a starting point for local research.

Use In Future Heatmaps

The intended heatmap workflow is:

symbol categories + scanner scores -> category aggregates -> heatmap

Useful aggregate metrics:

  • category symbol count,
  • count and percentage of symbols in uptrend,
  • average trend score,
  • median 30D return,
  • median 90D return,
  • top symbols per category.

Category Index

The backend can also turn a category into a sector-style index series:

GET /api/v1/categories
GET /api/v1/categories/{category}/index

Example:

curl 'http://127.0.0.1:8000/api/v1/categories/Layer%201/index?interval=1d&quote_asset=USDT'

The index calculation is:

  1. Select symbols in the requested category.
  2. Optionally filter by quote asset, usually USDT.
  3. Normalize each symbol’s close to 100 at its first visible candle.
  4. Average the normalized values at each timestamp.

This is an equal-weighted category performance line. It is not market-cap weighted and it does not rebalance by liquidity. It is meant for local research and visual comparison inside the chart UI.

Category Ratio

You can compare two category indexes directly:

curl 'http://127.0.0.1:8000/api/v1/category-ratios?numerator_category=AI&denominator_category=Layer%201&interval=1d&quote_asset=USDT'

The ratio calculation is:

category ratio = numerator category index / denominator category index

A rising ratio means the numerator category is outperforming the denominator category across the selected range. The UI exposes this through Category mode by changing View from Index to Ratio.

Borrow APR Filter

For long-short usage, the denominator category is the synthetic short side. You can exclude denominator components with expensive Binance margin borrow rates:

curl 'http://127.0.0.1:8000/api/v1/category-ratios?numerator_category=AI&denominator_category=Layer%201&interval=1d&quote_asset=USDT&max_short_borrow_apr_pct=10'

When max_short_borrow_apr_pct is set, the backend calls Binance’s signed margin next-hourly interest-rate endpoint, annualizes the hourly rate, and removes denominator symbols whose base asset is above the APR limit. This needs:

BINANCE_API_KEY
BINANCE_API_SECRET

If the filter is omitted, no Binance borrow-rate request is made.

Troubleshooting

Many symbols are uncategorized

That is expected. The generator is intentionally conservative, and important symbols should be reviewed manually before using category heatmaps or indexes.

Category index returns too few symbols

Confirm configs/symbol-categories.yaml exists, the category name matches the YAML file, and the selected quote asset is present in your local candle data.

Borrow APR filter fails

The borrow APR filter calls a signed Binance margin endpoint. Set BINANCE_API_KEY and BINANCE_API_SECRET, or omit max_short_borrow_apr_pct to avoid the signed request.