# Xchanger API — Full Reference

> Live currency and crypto exchange rates through a simple REST API.

Authenticate every request with an `x-api-key` header. Crypto supports any pair (rates derived from cached USD prices). Errors use the envelope `{ "error": { "code", "message", "details?" } }`.

- Docs: https://www.xchangerapi.com/docs
- OpenAPI spec: https://backend-ejsq.onrender.com/api/openapi.json
- Pricing: https://www.xchangerapi.com/#pricing

## General

### GET /api/general/convert

Convert an amount across asset types (currency or crypto)

Converts between any two assets regardless of type. Each side's asset type is given by `from_asset_type`/`to_asset_type` (`currency` or `crypto`), so fiat<->crypto pairs are supported.

Docs: https://www.xchangerapi.com/docs/general/convert

**Query parameters**

- `from_symbol` (string, required) — Currency or crypto symbol
- `from_asset_type` (string, required) — Asset type of the symbol
- `to_symbol` (string, required) — Currency or crypto symbol
- `to_asset_type` (string, required) — Asset type of the symbol
- `amount` (number, required) — Amount to convert. Must be a positive number up to 1e15.
- `precision` (integer, optional) — Decimal places to round the result to

**Response fields**

- `from` (string)
- `to` (string)
- `amount` (number)
- `rate` (number)
- `result` (number)
- `updated` (string<date-time>)

**Example response**

```json
{
  "data": {
    "from": "USD",
    "to": "EUR",
    "amount": 100,
    "rate": 0.92,
    "result": 92,
    "updated": "2026-06-09T12:00:00.000Z"
  }
}
```

**Errors**

- `400 VALIDATION_ERROR` — Invalid query parameters.
- `401 UNAUTHORIZED` — Missing or invalid API key.
- `404 UNKNOWN_ASSET` — Unknown currency or crypto.
- `429 USAGE_LIMIT_EXCEEDED` — Too many requests: per-key or per-IP burst rate limit exceeded (RATE_LIMIT_EXCEEDED) or monthly request quota reached (USAGE_LIMIT_EXCEEDED).
- `500 INTERNAL_ERROR` — Unexpected server error.
- `502 UPSTREAM_ERROR` — Exchange-rate provider failure.

## Currency

### GET /api/currency/currencies

List supported fiat currencies

Docs: https://www.xchangerapi.com/docs/currency/currencies

**Response fields**

- `id` (string)
- `name` (string)

**Example response**

```json
{
  "data": [
    {
      "id": "USD",
      "name": "United States Dollar"
    }
  ]
}
```

**Errors**

- `401 UNAUTHORIZED` — Missing or invalid API key.
- `429 USAGE_LIMIT_EXCEEDED` — Too many requests: per-key or per-IP burst rate limit exceeded (RATE_LIMIT_EXCEEDED) or monthly request quota reached (USAGE_LIMIT_EXCEEDED).
- `500 INTERNAL_ERROR` — Unexpected server error.

### GET /api/currency/exchange-rate

Get a fiat exchange rate

Docs: https://www.xchangerapi.com/docs/currency/exchange-rate

**Query parameters**

- `from` (string, required) — ISO 4217 currency code
- `to` (string, required) — ISO 4217 currency code

**Response fields**

- `from` (string)
- `to` (string)
- `rate` (number)
- `updated` (string<date-time>)

**Example response**

```json
{
  "data": {
    "from": "USD",
    "to": "EUR",
    "rate": 0.92,
    "updated": "2026-06-09T12:00:00.000Z"
  }
}
```

**Errors**

- `400 VALIDATION_ERROR` — Invalid query parameters.
- `401 UNAUTHORIZED` — Missing or invalid API key.
- `404 UNKNOWN_ASSET` — Unknown currency or crypto.
- `429 USAGE_LIMIT_EXCEEDED` — Too many requests: per-key or per-IP burst rate limit exceeded (RATE_LIMIT_EXCEEDED) or monthly request quota reached (USAGE_LIMIT_EXCEEDED).
- `500 INTERNAL_ERROR` — Unexpected server error.
- `502 UPSTREAM_ERROR` — Exchange-rate provider failure.

### GET /api/currency/convert

Convert an amount between fiat currencies

Docs: https://www.xchangerapi.com/docs/currency/convert

**Query parameters**

- `from` (string, required) — ISO 4217 currency code
- `to` (string, required) — ISO 4217 currency code
- `amount` (number, required) — Amount to convert. Must be a positive number up to 1e15.
- `precision` (integer, optional) — Decimal places to round the result to

**Response fields**

- `from` (string)
- `to` (string)
- `amount` (number)
- `rate` (number)
- `result` (number)
- `updated` (string<date-time>)

**Example response**

```json
{
  "data": {
    "from": "USD",
    "to": "EUR",
    "amount": 100,
    "rate": 0.92,
    "result": 92,
    "updated": "2026-06-09T12:00:00.000Z"
  }
}
```

**Errors**

- `400 VALIDATION_ERROR` — Invalid query parameters.
- `401 UNAUTHORIZED` — Missing or invalid API key.
- `404 UNKNOWN_ASSET` — Unknown currency or crypto.
- `429 USAGE_LIMIT_EXCEEDED` — Too many requests: per-key or per-IP burst rate limit exceeded (RATE_LIMIT_EXCEEDED) or monthly request quota reached (USAGE_LIMIT_EXCEEDED).
- `500 INTERNAL_ERROR` — Unexpected server error.
- `502 UPSTREAM_ERROR` — Exchange-rate provider failure.

## Crypto

### GET /api/crypto/currencies

List supported cryptocurrencies

Docs: https://www.xchangerapi.com/docs/crypto/currencies

**Response fields**

- `id` (string)
- `name` (string)

**Example response**

```json
{
  "data": [
    {
      "id": "USD",
      "name": "United States Dollar"
    }
  ]
}
```

**Errors**

- `401 UNAUTHORIZED` — Missing or invalid API key.
- `429 USAGE_LIMIT_EXCEEDED` — Too many requests: per-key or per-IP burst rate limit exceeded (RATE_LIMIT_EXCEEDED) or monthly request quota reached (USAGE_LIMIT_EXCEEDED).
- `500 INTERNAL_ERROR` — Unexpected server error.

### GET /api/crypto/exchange-rate

Get a crypto exchange rate (any pair)

Docs: https://www.xchangerapi.com/docs/crypto/exchange-rate

**Query parameters**

- `from` (string, required) — Crypto symbol
- `to` (string, required) — Crypto symbol

**Response fields**

- `from` (string)
- `to` (string)
- `rate` (number)
- `updated` (string<date-time>)

**Example response**

```json
{
  "data": {
    "from": "USD",
    "to": "EUR",
    "rate": 0.92,
    "updated": "2026-06-09T12:00:00.000Z"
  }
}
```

**Errors**

- `400 VALIDATION_ERROR` — Invalid query parameters.
- `401 UNAUTHORIZED` — Missing or invalid API key.
- `404 UNKNOWN_ASSET` — Unknown currency or crypto.
- `429 USAGE_LIMIT_EXCEEDED` — Too many requests: per-key or per-IP burst rate limit exceeded (RATE_LIMIT_EXCEEDED) or monthly request quota reached (USAGE_LIMIT_EXCEEDED).
- `500 INTERNAL_ERROR` — Unexpected server error.
- `502 UPSTREAM_ERROR` — Exchange-rate provider failure.

### GET /api/crypto/convert

Convert an amount between cryptos (any pair)

Docs: https://www.xchangerapi.com/docs/crypto/convert

**Query parameters**

- `from` (string, required) — Crypto symbol
- `to` (string, required) — Crypto symbol
- `amount` (number, required) — Amount to convert. Must be a positive number up to 1e15.
- `precision` (integer, optional) — Decimal places to round the result to

**Response fields**

- `from` (string)
- `to` (string)
- `amount` (number)
- `rate` (number)
- `result` (number)
- `updated` (string<date-time>)

**Example response**

```json
{
  "data": {
    "from": "USD",
    "to": "EUR",
    "amount": 100,
    "rate": 0.92,
    "result": 92,
    "updated": "2026-06-09T12:00:00.000Z"
  }
}
```

**Errors**

- `400 VALIDATION_ERROR` — Invalid query parameters.
- `401 UNAUTHORIZED` — Missing or invalid API key.
- `404 UNKNOWN_ASSET` — Unknown currency or crypto.
- `429 USAGE_LIMIT_EXCEEDED` — Too many requests: per-key or per-IP burst rate limit exceeded (RATE_LIMIT_EXCEEDED) or monthly request quota reached (USAGE_LIMIT_EXCEEDED).
- `500 INTERNAL_ERROR` — Unexpected server error.
- `502 UPSTREAM_ERROR` — Exchange-rate provider failure.

## Admin

### GET /api/admin/usage

Get your current API usage

Returns the calling key owner's request usage for the current calendar month. This endpoint does not count against your quota.

Docs: https://www.xchangerapi.com/docs/admin/usage

**Response fields**

- `limit` (number)
- `this_month` (object)

**Example response**

```json
{
  "limit": 1000000,
  "this_month": {
    "start": "2026-06-01",
    "end": "2026-06-30",
    "remaining": 995453,
    "usage": 4547
  }
}
```

**Errors**

- `401 UNAUTHORIZED` — Missing or invalid API key.
- `429 USAGE_LIMIT_EXCEEDED` — Too many requests: per-key or per-IP burst rate limit exceeded (RATE_LIMIT_EXCEEDED) or monthly request quota reached (USAGE_LIMIT_EXCEEDED).
- `500 INTERNAL_ERROR` — Unexpected server error.