___                                     ___           ___     
     /  /\          ___                      /  /\         /  /\    
    /  /::\        /  /\                    /  /::\       /  /:/_   
   /  /:/\:\      /  /:/    ___     ___    /  /:/\:\     /  /:/ /\  
  /  /:/~/::\    /  /:/    /__/\   /  /\  /  /:/~/::\   /  /:/ /::\ 
 /__/:/ /:/\:\  /  /::\    \  \:\ /  /:/ /__/:/ /:/\:\ /__/:/ /:/\:\
 \  \:\/:/__\/ /__/:/\:\    \  \:\  /:/  \  \:\/:/__\/ \  \:\/:/~/:/
  \  \::/      \__\/  \:\    \  \:\/:/    \  \::/       \  \::/ /:/ 
   \  \:\           \  \:\    \  \::/      \  \:\        \__\/ /:/  
    \  \:\           \__\/     \__\/        \  \:\         /__/:/   
     \__\/                                   \__\/         \__\/    
     

Atlas - Crypto Security Master

Atlas - Crypto Security Master is a Python securities master for crypto venues. It normalizes exchange-native instrument IDs into a consistent Contract model and builds a fast lookup map (internal_id) from precomputed JSON snapshots.

Daily updates: snapshot JSONs are refreshed automatically every day via GitHub Actions, and committed back to this repository.

What It Does

• Normalizes instrument metadata across exchanges into:
  • symbol (base)
  • denominator (quote / settlement)
  • margin (for derivatives)
  • type (spot, perpetual, future, option, unknown)
  • underlying (crypto, commodity, equity, index, pre_market, unknown), when supplied by the venue
  • contract_size (when available from source metadata)
  • delivery_date (for dated contracts)
  • internal_id string
• Loads local securities-master snapshots and supports:
  • lookup by (exchange, original_id) -> internal_id
  • active-symbol filtering by date window
• Refreshes snapshot data from:
  • exchange APIs (where supported)
  • Tardis
  • hybrid mode (exchange API first, Tardis fallback)

Symbology

Atlas uses a normalized internal_id format:

<type>-<symbol>-<denominator>[:<margin>][-<delivery_yyyymmdd>]

• Spot omits margin and delivery date.
• Perpetual includes margin, but no delivery date.
• Dated futures include both margin and delivery date.

Examples:

• Spot: btcusdt (Binance spot) -> spot-BTC-USDT
• Perpetual: btcusdt (Binance futures) -> perpetual-BTC-USDT:USDT
• Future: BTCUSDT-27MAR26 (Bybit futures) -> future-BTC-USDT:USDT-20260327

Installation

Python 3.12+ is required.

pip install -e .

Quick Start

Parse a single symbol

from atlas.parsers import parse_contract

symbol_data = {"id": "BTCUSDT", "type": "spot"}
contract = parse_contract("binance-spot", symbol_data)

print(contract.internal_id)  # spot-BTC-USDT

Load the local securities master

from datetime import datetime
from atlas import SecurityMaster

sm = SecurityMaster.load()

iid = sm.by_exchange_and_original_id("binance-spot", "BTCUSDT")
print(iid)

exchanges = sm.exchanges_for_original_id("BTCUSDT")
print(exchanges)

exchanges = sm.exchanges_for_contract("BTC", "USDT", "USDT")
print(exchanges)

active = sm.symbol_ids(
    exchange="binance-spot",
    first_capture=datetime(2024, 1, 1),
    end_date=datetime(2024, 1, 31),
)
print(len(active))

Update local snapshots

# Hybrid mode (default): Binance/OKX direct API + Tardis fallback
python3 atlas/update.py --source hybrid

# Tardis only
python3 atlas/update.py --source tardis

# Exchange API only (supported exchanges only)
python3 atlas/update.py --source exchange

# Restrict to selected exchanges
python3 atlas/update.py --exchanges binance-spot,okx-spot

Supported Exchanges

Atlas - Crypto Security Master currently contains parsers for the following exchange IDs.

Stability warning: any row marked UNSTABLE (BETA) is treated as beta by the codebase and is skipped by update.py in default runs.

Exchange ID	Stability
binance-spot	✅ STABLE
binance-futures	✅ STABLE
binance-futures-cm	✅ STABLE
bitmex	UNSTABLE (BETA)
bitfinex	UNSTABLE (BETA)
bitfinex-derivatives	UNSTABLE (BETA)
bitget	UNSTABLE (BETA)
bitget-futures	UNSTABLE (BETA)
bitstamp	UNSTABLE (BETA)
bybit-spot	✅ STABLE
bybit-perps	✅ STABLE
bybit-futures	✅ STABLE
coinbase	UNSTABLE (BETA)
crypto-com	UNSTABLE (BETA)
cryptofacilities	UNSTABLE (BETA)
deribit	UNSTABLE (BETA)
ftx	UNSTABLE (BETA)
gate-io	UNSTABLE (BETA)
gate-io-futures	UNSTABLE (BETA)
gemini	UNSTABLE (BETA)
huobi	UNSTABLE (BETA)
huobi-dm	UNSTABLE (BETA)
huobi-dm-swap	UNSTABLE (BETA)
huobi-dm-linear-swap	UNSTABLE (BETA)
hyperliquid-spot	✅ STABLE
hyperliquid-perps	✅ STABLE
kraken	UNSTABLE (BETA)
kucoin	UNSTABLE (BETA)
okx-spot	✅ STABLE
okx-perps	✅ STABLE
okx-futures	✅ STABLE
phemex	UNSTABLE (BETA)
poloniex	UNSTABLE (BETA)
upbit	UNSTABLE (BETA)

Bundled Snapshot Coverage

The repository currently ships precomputed JSON snapshots for:

• binance-spot
• binance-futures
• binance-futures-cm
• bybit-spot
• bybit-perps
• bybit-futures
• hyperliquid-spot
• hyperliquid-perps
• okx-spot
• okx-perps
• okx-futures

Features

• Unified parser layer with exchange-specific symbol rules.
• Stable-vs-beta exchange classification (beta exchanges are skipped in update.py by default).
• Exchange ID mapping to Tardis IDs (to_tardis_exchange_id).
• Metadata merge logic that preserves previously-known fields when the current source omits them.
• Date-window filtering over locally stored symbol availability intervals.
• CoinMarketCap ID enrichment for newly listed Binance assets, with confident matches written to snapshots and ambiguous ones raised for review.

CoinMarketCap IDs

Snapshot rows carry a cmc_id identifying the underlying asset, plus selected CMC category tags. Many exchange instruments may share one cmc_id — it names an asset, not a contract — and atlas/update.py treats the field as locally owned, so a snapshot refresh never overwrites it.

New binance-futures listings are resolved automatically by the cmc-new-symbol-mapping workflow, which runs daily after the snapshot update:

# Resolve symbols first listed in the last 60 days
python integrations/cmc_new_symbol_mapping.py --new-within-days 60

# Offline staleness check: coverage only, no network, no writes
python integrations/cmc_new_symbol_mapping.py --coverage-only --new-within-days 60

# Check the LLM endpoint is usable, in seconds
python integrations/cmc_new_symbol_mapping.py --check-llm

# Deterministic evidence only, no LLM adjudication
python integrations/cmc_new_symbol_mapping.py --no-llm

# Resolve only these tickers, ignoring age and any prior decision
python integrations/cmc_new_symbol_mapping.py --symbols PEPE,CHEEMS

The workflow exposes these as one mode input (resolve, preview, coverage, check-llm) and one days window.

Only crypto assets are in scope: rows whose underlying is equity, index, commodity or pre_market are skipped, since a tokenized equity's CMC ID would name the wrapper rather than the asset. Rows with no underlying (legacy crypto) and unknown are still resolved.

A ticker and an agreeing price never approve a mapping on their own. Approval needs identity evidence — an exact match between the Binance asset name and the CMC project name or slug — or an existing mapping on a same-ticker instrument that was listed at the same time. An LLM disambiguates between candidates that already carry name evidence, choosing among the fetched candidates only. Confident matches are written to the snapshots; everything else is reported for review. Every decision — candidates, price evidence and rationale — is recorded per instrument instance in atlas/data/cmc_mappings.json, and each run opens its own pull request covering both the confident and the uncertain matches. See docs/cmc-id-mapping.md for the decision ladder, configuration and review process.

Limitations

• No options mapping in the securities master map:
  • update.py ingests only spot, perpetual, and future from source metadata.
  • Option contracts may parse for some exchanges (for example, Deribit), but they are not included in the precomputed internal_id map.
• Instruments without a derived internal_id (for example options, combos, or unrecognized formats) are intentionally absent from SecurityMaster lookups.
• --source exchange only works for exchanges that have direct API fetchers implemented (currently Binance/OKX variants).
• The bundled data is limited to the snapshot files present in atlas/data; all other exchange coverage depends on running updates with an available upstream source.

Project Layout

• atlas/contracts.py: normalized Contract model.
• atlas/exchanges.py: exchange registry (parser + source metadata).
• atlas/parsers.py: parse entrypoint (parse_contract).
• atlas/database.py: load/query local securities master snapshots.
• atlas/update.py: snapshot updater CLI.
• atlas/data/*.json: generated per-exchange snapshot files.
• integrations/cmc_new_symbol_mapping.py: CMC ID resolution for new Binance symbols.
• integrations/cmc_mappings.py: versioned per-instrument CMC decision store.

Testing

pytest tests/

License

MIT (see LICENSE).