Static Data Service

Static Data Service

The Static Data Service is the central instrument directory and reference data provider of the Emporia Trading Platform. It owns all financial instrument metadata, ticker symbol mappings, exchange Market Identifier Codes (ISO MICs), price tick size constraints (tickSize), and lot size increments (sizeIncrement).

---

📌 Service Specifications

• Directory: static-data-service
• HTTP Port: 8081
• Database Boundary: emporia_static_data (PostgreSQL)
• Primary Roles:
  • Authoritative directory for financial instrument listings (InstrumentListing).
  • Enforce tick sizes (tickSize) and lot size increments (sizeIncrement) across trading services.
  • Expose REST API endpoints for React UI and internal microservices (order-command-service, execution-service).
  • Ingest active US equity reference data via AlpacaReferenceDataImporter and LegacyReferenceDataImporter.

---

🏗️ Architecture & Component Flow

flowchart TD
    subgraph Clients ["Authenticated Consumers"]
        Gateway["Spring Cloud Gateway (:8082)"] -->|GET /api/listings| Ctrl["InstrumentController (:8081)"]
        CmdSvc["Order Command Service (:8085)"] -->|Listing Snapshot Check| Ctrl
        ExecSvc["Execution Service (:8087)"] -->|Same-Instrument Listing Lookup| Ctrl
    end

    subgraph CoreStaticData ["Static Data Service Core"]
        Ctrl --> Repo["InstrumentListingRepository"]
        Repo --> DB[("PostgreSQL: emporia_static_data")]
    end

    subgraph Importers ["Reference Data Importers"]
        AlpacaImporter["AlpacaReferenceDataImporter (Opt-In)"] -->|Import US Assets & XOSR| Repo
        LegacyImporter["LegacyReferenceDataImporter (Flyway Seed)"] -->|Seed Local Listings| Repo
    end

Loading

---

🔑 REST API Endpoints

Method	Path	Description
GET	/listings	Query all active instrument listings (supports symbol and exchange filtering).
GET	/listings/{id}	Fetch a specific instrument listing snapshot by ID.
GET	/instruments/{id}/listings	Retrieve all venue listings (e.g. XNAS, XNYS, XOSR) for a given instrument symbol.

---

🏛️ Exchange MIC Mappings

The service maps primary trading venues using standard ISO Market Identifier Codes (MIC):

Exchange MIC	Venue Name
XNAS	Nasdaq Stock Market
XNYS	New York Stock Exchange (NYSE)
ARCX	NYSE Arca
XASE	NYSE American
BATS	Cboe BZX Exchange
XOSR	Emporia Composite Listing (Combines books across all venues)

---

📥 Reference Data Importers

1. AlpacaReferenceDataImporter (Opt-in)

Reads active US equity assets from Alpaca's REST asset master (/v2/assets?status=active&asset_class=us_equity):

• Generates a primary ISO-MIC listing (e.g. XNAS or XNYS) and an XOSR composite listing for every asset.
• Uses deterministic UUID generation based on Alpaca asset IDs, allowing safe importer restarts without duplicating database rows.
• Fractionable assets receive fractional size increments (e.g., 0.000001); standard assets receive round lot increments (1.0).

2. LegacyReferenceDataImporter

Runs on Flyway startup to seed local development listings if no external asset provider is configured.