✨ feat(README): Document Iranian market data endpoints and response f…

README.md

@@ -1,12 +1,13 @@
 # rest-api.ir
 
 ## Introduction
-This project is a small web service developed primarily for learning and experimentation, and is still evolving. The goal is to provide a simple executable that can launch a local REST API with minimal setup. If you have ideas or suggestions, I'd be happy to receive pull requests.
+This project is a small web service developed primarily for learning and experimentation, and is still evolving. The goal is to provide a simple executable that can launch a local REST API with minimal setup. Beyond the utility endpoints for time, IP, and countries, the service now streams Iranian market data (currency, crypto, and gold) from [tgju.org](https://tgju.org) on a schedule. If you have ideas or suggestions, I'd be happy to receive pull requests.
 
 ## Features
 - **Single Binary Execution**: Simply run `cargo run` or execute the output binary to start all Axum routes with default configurations—no additional tools required. The application listens on `APP_HOST:APP_PORT` and displays the configured domain in the output if set.
 - **Automatic Configuration Generation**: If no `.env` file exists, the application automatically creates one with default values including network settings and SQLite database configuration, allowing you to run immediately without hassle.
 - **Ready-to-Use Utility Routes**: A collection of `/api/v1` endpoints including time, IP detection, and country lists with flags, alongside a health check endpoint—suitable for testing or building widgets.
+- **Live Iranian Market Data**: Automated background jobs fetch retail gold coin, bullion, currency exchange, and cryptocurrency rates in Iranian Rial from tgju.org and expose them under dedicated `/api/v1` namespaces.
 - **Structured Responses**: All responses follow the `ApiResponse` structure, providing JSON data with predictable error messages.
 - **Request Statistics**: An in-memory counter tracks requests and persists them to the database every 60 seconds, showing usage metrics for each route.
 
@@ -22,6 +23,8 @@ This project is a small web service developed primarily for learning and experim
    ```
 3. The service will be available at `http://127.0.0.1:8080` (or values specified in `.env`)
 
+> ℹ️ **Network access**: The financial endpoints depend on reaching `https://call3.tgju.org`. Ensure outbound HTTPS access is allowed; otherwise the related responses will serve the most recent cached snapshot.
+
 On first run, a `.env` file is created with the following default values, which you can modify as needed:
 ```env
 APP_DOMAIN=localhost
@@ -46,8 +49,38 @@ DATABASE_URL=sqlite://stats.db?mode=rwc
 | `/api/v1/ip` | Client IP detection from common headers | `GET /api/v1/ip` |
 | `/api/v1/country` | List of country codes and names | `GET /api/v1/country` |
 | `/api/v1/country/full` | Complete country information including currency, language, and flag | `GET /api/v1/country/full` |
+| `/api/v1/coin/ir` | Retail prices for common Iranian gold coins with historical highs/lows | `GET /api/v1/coin/ir` |
+| `/api/v1/gold/ir` | Retail bullion prices (18K, 24K, Mesghal, used gold) in Iran | `GET /api/v1/gold/ir` |
+| `/api/v1/currency/ir` | Exchange rates for USD, EUR, AED, GBP, and TRY vs Iranian Rial | `GET /api/v1/currency/ir` |
+| `/api/v1/crypto/ir` | Cryptocurrency prices in Iranian Rial for major assets | `GET /api/v1/crypto/ir` |
 | `/api/v1/flags/{code}` | Retrieve flag SVG file by two-letter country code | `GET /api/v1/flags/ir.svg` |
 
+## Financial Data Responses
+All financial endpoints (`/coin/ir`, `/gold/ir`, `/currency/ir`, and `/crypto/ir`) return the shared `ApiResponse` envelope used by the rest of the service. The `data` payload contains keyed objects with the following fields:
+
+```json
+{
+  "current": 157500000,
+  "highest": 158200000,
+  "lowest": 156900000,
+  "updated_at": "2024-03-10T14:35:00+03:30"
+}
+```
+
+- **current**: Latest price reported by tgju.org (values are in Iranian Rial).
+- **highest / lowest**: Session high and low values published by the source.
+- **updated_at**: ISO-8601 timestamp (Asia/Tehran timezone) indicating when the quote was last refreshed.
+- **sync_at**: Present at the root of each payload, showing when the service last fetched data from tgju.org.
+
+Each endpoint focuses on a dedicated asset set:
+
+- `/coin/ir`: Emami, Bahar, Half (Nim), Quarter (Rob), and Gerami Iranian gold coins.
+- `/gold/ir`: 18K (750), 18K (740), 24K bullion, Mesghal weight, and used gold prices.
+- `/currency/ir`: USD (Dollar), EUR, AED (Dirham), GBP (Pound Sterling), and TRY (Turkish Lira).
+- `/crypto/ir`: Bitcoin, Ethereum, Binance Coin, Ripple (XRP), USD Coin, Dogecoin, and Tron.
+
+Background jobs continuously refresh the cached dataset, ensuring quick responses even if the upstream service is temporarily unreachable.
+
 ## Build and Deployment
 - To build a production-ready release:
   ```bash