iran-finance-markets-monitor

Use whenever a user asks to monitor, collect, validate, compare, summarize, or report Iranian financial markets, including USD/IRR or USD/Toman, EUR, AED, gold, Emami coin, Nima, USDT/Toman, crypto prices, Fear & Greed, TGJU, Nobitex, Wallex, Bitpin, or a Persian market report. Collect provenance-rich partial data, never invent missing values, and report source failures explicitly.

Iranian Finance Markets Monitor

Use this skill to produce neutral, auditable snapshots and Persian-language market reports. It is a data-collection and explanation workflow, not investment advice or a trading signal.

Safety and integrity rules

• Never provide personalized investment advice, guaranteed predictions, or fabricated prices.
• Preserve the original unit in provenance. TGJU values are commonly Rial; display Iranian retail values in Toman only after explicit division by 10.
• Every populated numeric field needs a source identifier. A missing value must remain null and its failure must appear in errors or warnings.
• Treat each source independently: a TGJU outage must not erase CoinGecko data, and a crypto outage must not erase FX/gold data.
• Clearly distinguish observed data, calculated values, validation failures, and neutral interpretation.

Workflow

1. Confirm the requested time window, market scope, currency unit, and desired output language. If unspecified, use the latest available snapshot and Persian for the report.
2. Read references/market-data-sources.md before changing selectors or interpreting TGJU tables. Table positions are operational hints, not proof that a page has not changed.
3. For live collection, install requirements.txt and run the bundled watcher with --stdout-only for inspection or --output-dir for a dated JSON artifact.
4. Normalize Persian and Arabic digits, parse numbers conservatively, convert Rial to Toman exactly once, and apply range/freshness/reconciliation gates.
5. Return partial data when a source fails. Never substitute a guessed value, stale value, or unrelated source.
6. Generate the Persian report from templates/market-report-fa.txt; use — for null values and include the source/failure note when useful.
7. Add a short neutral summary describing direction, dispersion, and data quality—not a buy/sell recommendation.

Data contract

The watcher emits JSON with:

• schema_version, date_gregorian, date_jalali, and an ISO-8601 timestamp_tehran.
• status: ok only when no errors were recorded; otherwise partial.
• crypto: BTC, ETH, USDT/Toman, selected alts, Fear & Greed, and total market cap.
• iran_fx_gold: free USD, EUR, AED, 18K gold, Emami coin, and Nima placeholder.
• news: at most three links, with source and URL; RSS is fallback-only when TGJU news is empty.
• errors: structured source, type, and detail records; warnings: non-fatal omissions.

Use the pure helpers in scripts/iran_market_watcher.py for tests and integrations: normalize_digits, parse_number, rial_to_toman, validate_range, validate_freshness, and parse_table_row.

Validation gates

• Localized numeric parsing must support Persian/Arabic digits and separators.
• Price ranges are broad sanity bounds, not forecasts; rejected values stay null.
• TGJU date fields are accepted only for today through two days old unless the user explicitly requests historical data.
• USDT exchange quotes require valid buy/sell prices, each quote spread no greater than 0.5%, and cross-exchange dispersion no greater than 0.5%.
• CoinGecko and Fear & Greed responses require successful HTTP status and basic numeric sanity checks.
• Use Tehran’s IANA timezone (Asia/Tehran), not a permanently hard-coded UTC offset.

Commands

From the repository root:

bash

python3 -m pip install -r skills/iran-finance-markets-monitor/requirements.txt
python3 skills/iran-finance-markets-monitor/scripts/iran_market_watcher.py --stdout-only
python3 skills/iran-finance-markets-monitor/scripts/iran_market_watcher.py --output-dir ./data/market
python3 -m pytest skills/iran-finance-markets-monitor/tests -q

For restricted/offline environments, run the tests and pure helpers only. Do not claim that live prices were collected when network access or dependencies are unavailable.

Reporting template

Use the bundled Persian template and fill missing values with —. Include:

• Jalali date and Tehran preparation time.
• BTC, ETH, USDT/Toman, and Fear & Greed where available.
• Free USD, EUR, AED, Emami coin, and 18K gold where available.
• One to three dated/source-linked headlines, with RSS marked as fallback.
• A two- or three-sentence neutral market summary and a data-quality note.

Troubleshooting

• jdatetime is required: install the bundled requirements; Jalali dates must not be approximated.
• Few or changed TGJU tables: record a scrape/schema error and inspect the source reference; do not silently shift indices.
• Rate limiting or timeout: retry is bounded, then preserve partial output and record the failure.
• Persian values parse as null: test normalize_digits and parse_number with the exact source text before changing selectors.