# Debugging CurrencyCore with curl

> Run convert, rates, and history requests from a terminal, read HTTP status and Retry-After, and filter JSON with jq.

Canonical: https://currency-core.com/docs/guides/curl/
Updated: 2026-11-11
Published: 2026-11-11

---
curl is the shortest path from a key to a response. With no page origin, preflight, or browser cache in the way, the status line and headers are the API's own. Reach for it first when a request fails inside an application.

Keep the key in an environment variable so it does not land in shell history or a screenshot:

```bash
export CURRENCYCORE_API_KEY="cc_test_your_key"
```

Free includes 1,000 requests per month at 60 per minute. Test keys share the same data and quota, capped at 60 per minute. One conversion, filtered with `jq`:

```bash
curl -sS "https://api.currency-core.com/v1/convert?from=USD&to=INR&amount=100" \
  -H "Authorization: Bearer $CURRENCYCORE_API_KEY" \
  | jq '{date, rate: .results[0].rate, result: .results[0].result}'
```

```json
{ "date": "2026-11-10", "rate": 83.45, "result": 8345.0 }
```

A rebased snapshot returns a map, with the base fixed at `1`:

```bash
curl -sS "https://api.currency-core.com/v1/rates/EUR" \
  -H "Authorization: Bearer $CURRENCYCORE_API_KEY" \
  | jq '.rates | {USD, INR}'
```

History needs a range. On the Free plan the window is the last 30 days; older dates return `403`:

```bash
curl -sS "https://api.currency-core.com/v1/history?currency=INR&base=USD&from=2026-11-03&to=2026-11-10" \
  -H "Authorization: Bearer $CURRENCYCORE_API_KEY" \
  | jq '.rates | to_entries | .[-3:]'
```

When a request fails, split the body from the metadata. `-D` writes headers to a file, `-o` writes the body, and `-w` prints the status:

```bash
curl -sS -o body.json -D headers.txt -w '%{http_code}\n' \
  "https://api.currency-core.com/v1/rates/USD?date=2026-10-01" \
  -H "Authorization: Bearer $CURRENCYCORE_API_KEY"
grep -i '^retry-after:' headers.txt || true
```

`-i` works for reading by eye, but it mixes headers into stdout, so do not pipe that output into `jq`. The API sends no `ETag`, `Last-Modified`, request ID, or quota headers; a time-based `429` may include `Retry-After` in seconds.

A browser is the wrong tool. A page on your origin cannot call the API directly because CORS allows CurrencyCore origins, not arbitrary customer sites. The console reports a blocked request that says nothing about the API. curl skips CORS, shows the raw `Retry-After`, and repeats the exact request in a bug report.

## Common mistakes

- Sending the key as a query parameter. Only `Authorization: Bearer` and `x-api-key` work.
- Pasting a key into a shared terminal or support ticket. Load it from the environment.
- Reading a CORS block as an API outage. Test the URL with curl first.
- Retrying a `403` history response. The date window will not widen.

## Next steps

- [API reference](/docs/api/) and [authentication](/docs/authentication/)
- [Error codes](/docs/errors/) and [rate limits](/docs/rate-limits/)
- [Retries guide](/docs/guides/retries/) for backoff and `Retry-After` handling
- [All developer guides](/docs/guides/)