# LiraScope API — Skill Guide

_Powered by OMARINO IT Services_

## Overview

LiraScope is a Syrian Pound (SYP) exchange-rate observatory. This skill lets an
agent fetch live and historical exchange rates for the Syrian Pound against the
US Dollar, Euro and other currencies, plus cryptocurrency and international gold
prices. Data is aggregated from the Central Bank of Syria (official rates) and
market (parallel) sources.

Use this skill when a user asks about:

- The Syrian Pound exchange rate today (سعر صرف الليرة السورية اليوم)
- The US Dollar price in Syria (سعر الدولار في سوريا)
- Foreign currency rates in Syria (سعر صرف العملات في سوريا)
- Gold prices in Syria (أسعار الذهب في سوريا)
- Cryptocurrency prices in USD

## Base URL

```
https://lirascope.syria-cloud.sy/api/v1
```

## Authentication

Public read endpoints (`/rates/*`, `/crypto/*`, `/gold/*`, `/pricing`) require
**no authentication** and are free to use within fair-use rate limits.

Private client endpoints (`/client/*`) require API key headers:

```
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>
```

## Conventions

- All responses are JSON unless otherwise noted.
- Rates use `SYP` as the internal base currency.
- Timestamps are UTC ISO-8601 (`timestampUtc`).
- Every rate response includes a localized `disclaimer` field.
- Pass `lang=ar|en|de|tr|ku|kmr` (or send an `Accept-Language` header) to
  localize the disclaimer. Arabic (`ar`) is the default.

## Endpoints

### GET /rates/latest
Latest official (CBS) and market SYP rates.

| Parameter   | Required | Description |
|-------------|----------|-------------|
| currencies  | optional | Comma-separated codes, e.g. `USD,EUR`. Omit for all. |
| lang        | optional | Disclaimer language. |

Example:

```bash
curl "https://lirascope.syria-cloud.sy/api/v1/rates/latest?currencies=USD,EUR&lang=ar"
```

Response (truncated):

```json
{
  "disclaimer": "...",
  "timestampUtc": "2026-01-29T02:00:00Z",
  "cbsRates": [
    {"currency": "USD", "buy": 110.0, "sell": 111.0, "mid": 110.5, "isManualOverride": false}
  ],
  "marketRates": [
    {"currency": "USD", "buy": 116.8, "sell": 117.5, "mid": 117.15, "isManualOverride": false}
  ],
  "effectiveRates": []
}
```

### GET /rates/history
Historical SYP rate series for one currency and source.

| Parameter | Required | Description |
|-----------|----------|-------------|
| currency  | required | Currency code, e.g. `USD`. |
| source    | optional | `CBS` or `MARKET`. |
| days      | optional | Look-back window in days (e.g. `30`). |

```bash
curl "https://lirascope.syria-cloud.sy/api/v1/rates/history?currency=USD&source=CBS&days=30"
```

### GET /rates/usd-based
Cross rates derived from USD (USD as the base currency).

```bash
curl "https://lirascope.syria-cloud.sy/api/v1/rates/usd-based?lang=en"
```

### GET /crypto/latest
Current cryptocurrency prices in USD.

```bash
curl "https://lirascope.syria-cloud.sy/api/v1/crypto/latest"
```

### GET /gold/latest
Current international gold prices in USD.

```bash
curl "https://lirascope.syria-cloud.sy/api/v1/gold/latest"
```

### GET /health
Service health probe.

```bash
curl "https://lirascope.syria-cloud.sy/api/v1/health"
```

## Error handling

| Status | Meaning | Action |
|--------|---------|--------|
| 400 | Bad request / invalid parameter | Fix the query parameters. |
| 401 | Missing or invalid API key | Send valid `X-Api-Key`/`X-Api-Secret`. |
| 429 | Rate limit exceeded | Back off; honor `Retry-After` and `X-RateLimit-*` headers. |
| 5xx | Upstream/source error | Retry with exponential backoff. |

## Discovery

- Full markdown reference: https://lirascope.syria-cloud.sy/api-docs.md
- HTML docs: https://lirascope.syria-cloud.sy/api-docs
- Agent index: https://lirascope.syria-cloud.sy/llms.txt
- API catalog: https://lirascope.syria-cloud.sy/.well-known/api-catalog
- MCP server card: https://lirascope.syria-cloud.sy/.well-known/mcp/server-card.json

## Disclaimer

LiraScope displays exchange rates "as is" from external sources (Central Bank of
Syria and market sources). OMARINO IT Services assumes no responsibility for
accuracy or completeness and provides no guarantees. Use at your own risk.

## Support

Questions: info@omarino.de