Getting started

Before you begin

You authenticate every request with either:

  • an API key, sent as a Bearer token (recommended for new integrations), or
  • your account's Username and Password, sent with Basic authentication.

Your Username and Password are generated when you start your free trial, and you use them for Basic authentication. You'll find them in the Basic Authentication card on the API page of your account, which is also where you create API keys: separate, revocable tokens used for Bearer authentication. See Manage your API keys for the steps. If you haven’t signed up yet, see Registration overview for the step-by-step process.

Base URL and versioning

All requests are made over HTTPS to:

https://xecdapi.xe.com/v1/

The version number (v1) is part of the path. You’ll always call a specific version, so your integration won’t change unexpectedly.

Authenticate your requests

XeCD accepts two authentication methods. Every endpoint accepts both, so pick whichever suits your integration:

  • API key (Bearer token): recommended for new integrations. You create and revoke these keys yourself. See Manage your API keys.
  • Basic authentication: your account's Username and Password. Existing integrations keep working with no change.

Whichever you use, your account's usage and limits are counted the same way. See How usage is counted.

Authenticate with an API key (Bearer token)

Send your key in the Authorization header as a Bearer token. A key is a single string of the form xecd_<env>_<id>.<secret>, and production keys begin xecd_prod_. Send the whole string, including the secret shown to you when the key was created.

curl -H 'Authorization: Bearer XE_API_KEY' "https://xecdapi.xe.com/v1/account_info"

Authenticate with Basic authentication

Send your account Username and Password as HTTP Basic credentials on every request, over HTTPS. Most HTTP libraries and tools handle the encoding for you.

curl -u USERNAME:PASSWORD "https://xecdapi.xe.com/v1/account_info"
  • In a browser, just paste a request URL and enter your Username and Password when prompted.

Both examples above call the account_info endpoint, which returns your account and plan details. It is the quickest way to check that your credentials work. It doesn’t count against your monthly usage, though it does use one of your 900 requests per 15 minutes. Invalid credentials return 401 Unauthorized. After 3 failed attempts with a bad key, the API temporarily returns 403 Forbidden even for valid keys, so wait 5 minutes before retrying.

Sample response

For valid credentials

{
    "id": "********",
    "organization": "Xe Team Thor Trial1",
    "package": "PRIME",
    "service_start_timestamp": "2025-08-29T00:00:00Z",
    "package_limit_duration": "1 month",
    "package_limit": 150000,
    "package_limit_remaining": 142356,
    "package_limit_reset": "2026-08-28T00:00:00Z"
}

For invalid credentials

{
    "code": 1,
    "message": "Bad credentials",
    "documentation_url": "https://developers.xe.com/docs/currency-data-api"
}

Manage your API keys

You manage API keys yourself from the API page of your Xe Currency Data account, so you don't need to contact support. The API Keys card on that page lists your keys and is where you create and revoke them. Every key authenticates as your account, so usage and limits are shared across all of them (see How usage is counted).

Create a key

  1. On the API page, go to the API Keys card and choose Create New.
  2. Optionally give the key a name (up to 50 characters, for example Production integration) so you can tell your keys apart, and an optional expiry date. Leave the expiry blank for a key that never expires.
  3. Choose Create key. The full key, including its secret, is shown once, immediately after creation.

Copy your key now

The secret is shown only at creation and can’t be retrieved afterwards. Copy the key and store it somewhere safe, such as a secrets manager. If you lose it, revoke the key and create a new one.

List your keys

The API Keys table shows every key on the account: its status (Active, Expired or Revoked), name, Key ID (the xecd_<env>_<id> prefix, without the secret), when it was created and by whom, and its expiry. For a revoked key, it also shows when it was revoked and by whom. The Key ID lets you identify a key without exposing its secret.

Revoke a key

Select the revoke action next to an active key and confirm. Revocation takes effect immediately and can’t be undone. Any application still using that key stops working at once. Revoked keys stay in the table for audit but can’t be reactivated, so create a new key instead.

Key limit

An account can have up to 10 active keys at a time. Expired and revoked keys don’t count towards the limit, so revoke a key you no longer use before creating another.

Make your first request

Convert 1 USD into EUR and GBP:

curl -H 'Authorization: Bearer XE_API_KEY' \
  "https://xecdapi.xe.com/v1/convert_from.json/?from=USD&to=EUR,GBP&amount=1"

You’re now retrieving live Xe rates. For every endpoint, its parameters, and full response fields, see the API Reference.

Response formats

JSON is returned by default. To choose a format, add .json, .csv, or .xml after the endpoint:

https://xecdapi.xe.com/v1/convert_from.csv/?from=USD&to=EUR,GBP&amount=1

The same convert_from response in each format:

JSON

{
    "terms": "https://www.xe.com/legal",
    "privacy": "https://www.xe.com/privacy",
    "from": "USD",
    "amount": 1.0,
    "timestamp": "2026-08-07T06:00:00Z",
    "to": [
        {
            "quotecurrency": "EUR",
            "mid": 0.8678400992
        },
        {
            "quotecurrency": "GBP",
            "mid": 0.7433236225
        }
    ]
}

CSV

Terms,https://www.xe.com/legal,Privacy,https://www.xe.com/privacy
from,amount,timestamp,quotecurrency,mid
USD,1.0,2026-08-07T06:00:00Z,EUR,0.8678400992
USD,1.0,2026-08-07T06:00:00Z,GBP,0.7433236225

XML

<?xml version="1.0" ?>
<convertFrom xmlns="http://xecdapi.xe.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://xecdapi.xe.com/schema/v1/convertFrom.xsd">
    <terms>https://www.xe.com/legal</terms>
    <privacy>https://www.xe.com/privacy</privacy>
    <from>USD</from>
    <amount>1</amount>
    <timestamp>2026-08-07T06:00:00Z</timestamp>
    <to>
        <rate>
            <currency>EUR</currency>
            <mid>0.8678400992</mid>
        </rate>
        <rate>
            <currency>GBP</currency>
            <mid>0.7433236225</mid>
        </rate>
    </to>
</convertFrom>

How usage is counted

  • Each rate returned counts as one request toward your monthly allowance. A single call for two counter currencies (e.g. to=EUR,GBP) counts as two.
  • Usage is counted per account, not per credential. Your monthly allowance and the 900-requests-per-15-minutes throttle are shared across every API key and your Basic credentials. Using more keys does not give you more capacity.
  • Conditional requests that return 304 Not Modified don’t count (see below).
  • Check your current usage any time with account_info (free), or read the X-RateRequest-Limit, X-RateRequest-Remaining and X-RateRequest-Reset headers on any response.
  • Monthly allowances, refresh frequency and add-ons depend on your plan - see Data plans.

Handle errors:

XeCD uses standard HTTP status codes: 2xx success, 4xx a problem with your request, 5xx a problem on Xe's side. Errors return a JSON body with a code, message and documentation_url:

{
    "code": 1,
    "message": "Bad credentials",
    "documentation_url": "https://developers.xe.com/docs/currency-data-api"
}

See the Errors & Exceptions for the full list of error codes.

Use rates efficiently (conditional requests)

Most responses include an ETag. Send it back on your next call with If-None-Match; if nothing has changed you'll get a 304 Not Modified. That doesn’t count towards your monthly usage, though it does count towards the 15-minute throttle.

curl -H 'Authorization: Bearer XE_API_KEY' \
  "https://xecdapi.xe.com/v1/convert_from/?from=USD&to=EUR" \
  -H 'If-None-Match: f47ac10b-58cc-4372-a567-0e02b2c3d479'

On this page

Get help