# LiraScope API Reference

_Powered by OMARINO IT Services_

LiraScope provides live and historical Syrian Pound (SYP) exchange rates,
cryptocurrency prices and international gold prices over a free public JSON API.

- **Base URL:** `https://lirascope.syria-cloud.sy/api/v1`
- **HTML docs:** https://lirascope.syria-cloud.sy/api-docs
- **Agent skill guide:** https://lirascope.syria-cloud.sy/SKILLS.md

## Authentication

Public endpoints (`/rates/*`, `/crypto/*`, `/gold/*`, `/pricing`) require no
authentication. Private client endpoints (`/client/*`) require API key headers:

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

## Localization

All rate responses include a `disclaimer` field. Localize it with the `lang`
query parameter (`ar`, `en`, `de`, `tr`, `ku`, `kmr`) or an `Accept-Language`
header. Arabic (`ar`) is the default.

## Endpoints

### GET /rates/latest

Returns the latest official (Central Bank of Syria) and market SYP rates.

**Query parameters**

- `currencies` (optional): comma-separated currency codes, e.g. `USD,EUR`.
- `lang` (optional): disclaimer language.

**Example**

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

**Response**

```json
{
  "disclaimer": "...",
  "timestampUtc": "2026-01-29T02:00:00Z",
  "cbsRates": [
    {
      "currency": "USD",
      "buy": 110.00,
      "sell": 111.00,
      "mid": 110.50,
      "timestampUtc": "2026-01-29T01:59:47Z",
      "isManualOverride": false
    }
  ],
  "marketRates": [
    {
      "currency": "USD",
      "buy": 116.80,
      "sell": 117.50,
      "mid": 117.15,
      "timestampUtc": "2026-01-29T01:54:46Z",
      "isManualOverride": false
    }
  ],
  "effectiveRates": []
}
```

### GET /rates/usd-based

Returns 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 /rates/history

Returns a historical SYP rate series for a single currency and source.

**Query parameters**

- `currency` (required): currency code, e.g. `USD`.
- `source` (optional): `CBS` or `MARKET`.
- `days` (optional): look-back window in days.
- `startDate` / `endDate` (optional): explicit ISO date range.

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

### GET /crypto/latest

Returns current cryptocurrency prices in USD.

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

### GET /gold/latest

Returns current international gold prices in USD.

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

### GET /health

Returns the service health status.

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

## Response fields

- `disclaimer`: localized legal disclaimer.
- `timestampUtc`: response generation time (UTC, ISO-8601).
- `cbsRates`: official Central Bank of Syria rates.
- `marketRates`: parallel / black-market rates.
- `effectiveRates`: effective rates after any manual override.
- Per rate: `currency`, `buy`, `sell`, `mid`, `timestampUtc`, `isManualOverride`.

## Rate limits

The free tier is rate-limited per IP. Responses include `X-RateLimit-Limit`,
`X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. When the limit is
exceeded the API returns HTTP `429` with a `Retry-After` header. See
https://lirascope.syria-cloud.sy/pricing for higher tiers.

## Errors

| Status | Meaning |
|--------|---------|
| 400 | Invalid request parameters. |
| 401 | Missing or invalid API key (private endpoints). |
| 429 | Rate limit exceeded. |
| 5xx | Upstream source error; retry with backoff. |

## 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