📊 Market Data

Guide for reference data and instrument definitions in the MAF OA system.

---

Quick Overview

The system organizes market data into two layers:

• 🏷️ Market Data Products (MDP) — Master reference data (e.g., "LNG Futures", "HSBC Equity")
• 📍 Market Data Instruments (MDI) — Specific contract instances (e.g., "LNG Dec-2025", "HSBC Call 105.50")

Both can come from internal database or external sources (MAF, vendors)

1️⃣ Market Data Products (MDP)

What is an MDP?

A Market Data Product is a master record that defines a tradable instrument class:

• Immutable once created
• Uniquely identified by mdp_key (e.g., LNG_JKM)
• Includes static attributes: exchange, currency, asset class, type
• Can reference an external product ID for integration (e.g., MAF's 10123)

---

Key Fields

Field	Type	Example	Purpose
mdp_key	string	LNG_JKM	Stable, human-readable code
exchange	string	ICE, SGX	Primary trading venue
name	string	JKM LNG Futures	Display name
asset_class	enum	COMMODITY, EQUITY, FX, RATE, etc.	Asset category
market_data_type	enum	SPOT, FUTURE, FORWARD, OPTION, etc.	Instrument type
description	string	Front-month LNG	Optional notes
base_unit	enum	MMBTU, BBL, MT	Pricing unit
base_currency	enum	USD, EUR, SGD	Pricing currency
source	enum	MAF	Source system
source_market_data_product_id	string	JKM_FUT_001	External system ID
option_style	enum	EUROPEAN, AMERICAN	Option type (if applicable)
underlying_mdp_id	int	1	Parent product (for derivatives)

Examples

📈 LNG Futures

{
  "mdp_key": "LNG_JKM",
  "name": "JKM LNG Futures",
  "exchange": "ICE",
  "asset_class": "COMMODITY",
  "market_data_type": "FUTURE",
  "base_unit": "MMBTU",
  "base_currency": "USD",
  "source": "MAF",
  "source_market_data_product_id": "JKM_FUT_001"
}

📊 Equity Stock

{
  "mdp_key": "EQUITY_700",
  "name": "HSBC Holdings PLC",
  "exchange": "HKEX",
  "asset_class": "EQUITY",
  "market_data_type": "SPOT",
  "base_currency": "HKD"
}

📞 Call Option (with underlying)

{
  "mdp_key": "FUTURE_OPTION_LNG",
  "name": "LNG Futures Call Option",
  "exchange": "ICE",
  "asset_class": "COMMODITY",
  "market_data_type": "FUTURE_OPTION",
  "option_style": "EUROPEAN",
  "underlying_mdp_id": 1
}

---

2️⃣ Market Data Instruments (MDI)

What is an MDI?

A Market Data Instrument is a specific contract instance tied to an MDP:

• One MDP → Many MDIs (e.g., one "LNG Futures" product → contracts for 2512, 2601, 2602, etc.)
• For spot/index products, MDI is optional (1:1 with MDP)
• For derivatives, specifies contract term, strike, call/put

---

Key Fields

Field	Type	Example	Purpose
mdp_id	int	1	Link to parent Market Data Product
contract_term	string	2512, 241221	Contract expiry (YYMM or YYMMDD)
cp	enum	C, P	Call or Put (options only)
strike_price	string	105.50	Strike price (options only)

---

Examples

🔄 Futures Contract (Dec-2025)

{
  "mdp_id": 1,
  "contract_term": "2512"
}

📊 Option Contract (Call at 105.50)

{
  "mdp_id": 10,
  "contract_term": "2412",
  "cp": "C",
  "strike_price": "105.50"
}

Source & Refresh

• Authoritative sources:
  • Internal: market_data_products and market_data_instruments tables in the database.
  • External: MAF (Markit Attribution Finance) or other vendor feeds.
• Refresh cadence:
  • MDPs: Updated only on instrument changes (corporate actions, new listings, delistings). Typically monthly or quarterly.
  • MDIs: Updated as new contracts are introduced (e.g., monthly for rolling futures). Typically weekly or on-demand.
• Change tracking: All changes logged with created_at, updated_at, and created_by / updated_by (tenant and user context).

---

🔗 API Endpoints

Market Data Products

Method	Endpoint	Purpose
POST	/marketdata/product/insert	Create new products
POST	/marketdata/product/select	Query with filters
PUT	/marketdata/product/update	Update existing products
DELETE	/marketdata/product/delete	Remove products

Market Data Instruments

Method	Endpoint	Purpose
POST	/marketdata/instrument/insert	Create new instruments
POST	/marketdata/instrument/select	Query instruments
DELETE	/marketdata/instrument/delete	Remove instruments

Note: Instruments are validated against their linked product's market_data_type at insert time.

Ownership & Change Process

• Data Owner: Data Engineering team / Market Data Team
• Change Process:
  1. Submit insert/update/delete requests via the REST API (authentication required).
  2. Changes are logged with tenant_id, created_by, updated_by, and timestamps.
  3. For external source mappings, coordinate with MAF or vendor team.
  4. All changes are audit-logged for compliance tracking.

---

📋 Key Guidelines

For Data Consumers

1. Query by Key — Use mdp_key (e.g., LNG_JKM) for deterministic lookups
2. Resolve Instruments — For options/futures, specify contract_term, cp, strike_price
3. External Mapping — Match your product ID against source_market_data_product_id for MAF integration
4. Tenant Scoping — All queries are scoped to your authenticated tenant_id

For Data Maintainers

1. ✅ Check Uniqueness — Prevent duplicate mdp_key values before insert
2. ✅ Reference Validation — Ensure underlying_mdp_id points to valid MDPs (for derivatives)
3. ✅ Type Enforcement — Only set option_style for *_OPTION types
4. ✅ Source Coordination — Keep MAF mappings in sync with external vendor

---

📊 Data Lifecycle

Event	Cadence	Notes
Create MDP	On-demand	Immutable after creation
Update MDP	Rare	Only for master data corrections
Create MDI	Weekly / Monthly	New contract terms/strikes
Delete	Ad-hoc	Audit-logged for compliance

All changes tracked with: tenant_id, created_by, updated_by, created_at, updated_at

---

🔄 Source & Refresh

Source	Storage	Refresh	Use Case
Internal	Database	On-demand	Regulatory, audit trail
External (MAF)	Vendor feed	Daily/Weekly	Market comparison, reconciliation

---

📚 Related Documentation

• Market Data Price — EOD and real-time pricing queries
• Code: See app/model/market_models/ for Pydantic models
• ORM: See app/infra/orm/market_orms/ for database schemas

❓ Questions?

• Data Issues → Market Data Team
• API Issues → Backend Team
• Permissions → Tenant Admin