auma.dev API

Base URL https://auma.dev. All responses are JSON; every GET is cacheable and CORS-enabled. Machine-readable contract at /openapi.json.

/fx

Fiat, crypto and metal rates for 340+ currencies from the open fawazahmed0/currency-api dataset (CC0). auma.dev pulls it on a schedule — every 30 minutes, 48 times a day at most — and serves a snapshot; client requests never reach the upstream. Every response says when the snapshot was taken and when the next refresh is due.

get/v1/fx/latest

Latest rates for a base currency

Rates to convert one unit of `base` into every other currency (or only `symbols`). Codes are uppercase; crypto codes such as BTC and ETH are included. Any base is derived from the EUR snapshot (`rate = eur[code] / eur[base]`, ten significant digits). `date` is the day the upstream published the dataset (it updates daily); `fetchedAt` is when auma.dev last pulled it, `nextRefreshAt` when the next pull is scheduled, and `stale` turns true only if a scheduled refresh was missed. Responses carry an `ETag`: send it back as `If-None-Match` to get a 304 until the next refresh.

ParameterInDescription
basequeryBase currency code. Default: EUR.
symbolsqueryComma-separated list of codes to return. Unknown codes yield 404.
request
curl 'https://auma.dev/v1/fx/latest?base=EUR&symbols=USD,GBP,BTC'
response 200
{
  "base": "EUR",
  "date": "2026-09-17",
  "fetchedAt": "2026-09-17T09:30:04.118Z",
  "nextRefreshAt": "2026-09-17T10:00:04.118Z",
  "stale": false,
  "count": 3,
  "rates": {
    "USD": 1.15425415,
    "GBP": 0.8562203,
    "BTC": 0.000015226607
  },
  "source": {
    "name": "fawazahmed0/currency-api",
    "url": "https://github.com/fawazahmed0/exchange-api",
    "license": "CC0-1.0"
  }
}
get/v1/fx/currencies

Supported currencies

Every code the rates endpoint understands, with its display name and a coarse `kind`: `fiat` (ISO 4217, active or withdrawn, plus a few local issues such as CNH), `metal` (XAU, XAG, XPT, XPD) or `crypto` (everything else, including stablecoins and tokenised gold). Unknown new codes are reported as `crypto`.

request
curl 'https://auma.dev/v1/fx/currencies'
response 200
{
  "date": "2026-09-17",
  "fetchedAt": "2026-09-17T09:30:04.118Z",
  "nextRefreshAt": "2026-09-17T10:00:04.118Z",
  "stale": false,
  "count": 340,
  "currencies": [
    {
      "code": "BTC",
      "name": "Bitcoin",
      "kind": "crypto"
    },
    {
      "code": "EUR",
      "name": "Euro",
      "kind": "fiat"
    },
    {
      "code": "XAU",
      "name": "Gold Ounce",
      "kind": "metal"
    }
  ],
  "source": {
    "name": "fawazahmed0/currency-api",
    "url": "https://github.com/fawazahmed0/exchange-api",
    "license": "CC0-1.0"
  }
}
get/v1/fx/currencies/{code}.json

Upstream-compatible rates document

The `@fawazahmed0/currency-api` wire format (`{ "date": ..., "eur": { "usd": 1.15 } }`, lowercase codes), rendered from the snapshot. Also available: `/v1/fx/currencies/{code}.min.json`, `/v1/fx/currencies.json` and `/v1/fx/currencies.min.json` (code → name). Clients already written against that dataset only need to change their base URL to `https://auma.dev/v1/fx/`.

ParameterInDescription
code*pathLowercase base currency code.
request
curl 'https://auma.dev/v1/fx/currencies/eur.json'
response 200
{
  "date": "2026-09-17",
  "eur": {
    "btc": 0.000015226607,
    "gbp": 0.8562203,
    "usd": 1.15425415
  }
}
get/v1/fx/status

Refresh policy and upstream contacts

The promise made to the upstream, and the evidence: the schedule, how many contacts happened today and remain, the current snapshot's freshness, and the most recent contacts with their outcome. `store` is `redis` in production; `memory` means the limits are enforced per instance only.

request
curl 'https://auma.dev/v1/fx/status'
response 200
{
  "policy": {
    "schedule": "*/30 * * * *",
    "intervalMinutes": 30,
    "maxContactsPerDay": 48,
    "onDemand": false
  },
  "store": "redis",
  "today": {
    "day": "2026-09-17",
    "contacts": 19,
    "remaining": 29
  },
  "snapshot": {
    "date": "2026-09-17",
    "fetchedAt": "2026-09-17T09:30:04.118Z",
    "nextRefreshAt": "2026-09-17T10:00:04.118Z",
    "stale": false,
    "currencies": 340,
    "namesFetchedAt": "2026-09-17T00:00:03.902Z"
  },
  "recentContacts": [
    {
      "at": "2026-09-17T09:30:03.911Z",
      "ok": true,
      "ms": 207,
      "names": false
    }
  ],
  "source": {
    "name": "fawazahmed0/currency-api",
    "url": "https://github.com/fawazahmed0/exchange-api",
    "license": "CC0-1.0"
  },
  "time": "2026-09-17T09:41:12.000Z"
}

/platform

Service metadata.

get/v1/health

Service health

Version, deployed commit and serving region.

request
curl 'https://auma.dev/v1/health'
response 200
{
  "status": "ok",
  "service": "auma.dev",
  "version": "1.1.0",
  "commit": "abc1234",
  "region": "fra1",
  "time": "2026-09-17T12:00:00.000Z"
}

Errors

Errors use the HTTP status and a stable code. Validation failures list the offending parameters in details.

response 400
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "details": [
      {
        "path": "base",
        "message": "base must be a currency code"
      }
    ]
  }
}
400 invalid_requestA query parameter failed validation.
404 unknown_currency / not_foundUnknown base currency, symbol or resource.
503 rates_unavailableNo snapshot yet (first minutes after a fresh deploy); retry shortly.