Exchange Rate

Returns the USD → ETB rate the platform is currently working with, so you can quote an ETB amount to a sender before submitting an airtime topup, package topup, or gift voucher purchase.

The rate is the Commercial Bank of Ethiopia (CBE) daily USD buying rate, the rate at which the bank buys USD and pays out ETB. It is refreshed from CBE at most once per hour, so repeated calls within that window return the same value.

Endpoint

> GET ${BASE_URL}/exchange-rate

Payloads

No request body or query parameters.

Sample Request

Curl

$  curl -H 'x-api-token: ACCESS_TOKEN' \
        "BASE_URL/exchange-rate"

Typescript

import * as axios from "axios";

axios
  .get("BASE_URL/exchange-rate", {
    headers: {
      "x-api-token": "ACCESS_TOKEN"
    },
  })
  .then((response) => {
    console.log("Success:", response.data);
  })
  .catch((error) => {
    console.error(
      "Error:",
      error.response ? error.response.data : error.message,
    );
  });

Response Schema

Success Schema

{
  success: boolean;
  message: string;
  statusCode: number;
  data: {
    baseCurrency: "USD";
    quoteCurrency: "ETB";
    rate: number;
    source: "CBE" | "CONFIG";
    fetchedAt: string;
  }
}

Error Schema

{
  statusCode: number;
  success: boolean;
  message: string;
  data: any;
}

• baseCurrency (string): Always USD.
• quoteCurrency (string): Always ETB.
• rate (number): How many ETB one USD buys: 1 USD = rate ETB.
• source (string): CBE when the rate came from the Commercial Bank of Ethiopia. CONFIG when CBE was unreachable and the platform's configured fallback rate was returned.
• fetchedAt (string): ISO timestamp of when the rate was obtained from its source. On a cached response this is when CBE was last called, not when you made the request.

Response Codes

Code	Meaning
200	Rate returned.
401	Missing or invalid x-api-token.
502	The rate provider is unavailable or returned no usable rate. Retry after a short delay.
503	Exchange rate lookup is not configured on this environment. Contact support.

Sample Response

{
  "success": true,
  "message": "Successful",
  "statusCode": 200,
  "data": {
    "baseCurrency": "USD",
    "quoteCurrency": "ETB",
    "rate": 156.4321,
    "source": "CBE",
    "fetchedAt": "2026-09-08T06:00:12.000Z"
  }
}

Sample Error Response

{
  "success": false,
  "message": "ODM exchange rate is unavailable",
  "statusCode": 502,
  "data": null
}

Indicative rate

The rate is indicative. Topups and vouchers are processed at the exchangeRate you submit with each request, and deposit orders are settled at the rate current when the order is reviewed. Treat source: "CONFIG" as a signal that the live CBE rate was unavailable, and cache the response on your side rather than polling more often than every minute.