Ayden Panhuyzen

currency.ayden.tech API Documentation

Heads up! These docs are incomplete, and may be missing important information!

Introduction

currency.ayden.tech is a lightweight, public API for getting currency exchange rates, meant for personal projects. You’re free to use it (within reason), if you want.

It is a side project of mine for reference purposes, and should not be trusted at scale or for any use where actual money is involved, such as determining the rate to send for a transaction. By using this API, you agree that it is at your own risk and I am not liable for any inaccuracies, downtime, etc. relating to use of this API.

If you plan to release a project making use of it past yourself, please discuss with me in advance so we can ensure it is suitable for your needs.

Data will not be updated more frequently than 15 minutes. Rate-limiting may be applied if you request the same or excess data within a period where it would not have changed.

Definitions

Currency: An active monetary currency, as defined by ISO 4217, excluding X-currencies (silver, etc.).
Major unit: The standard denomination of a currency represented by the currency code . For USD (U.S. Dollars), this is a dollar. For GBP (British Pound Sterling), this is a pound.
Minor unit: The minor denomination a currency may be divided into in use, as again defined by ISO 4217. For USD, this is a cent, which is 0.01 USD. For GBP, this is a penny or pence (plural), which is 0.01 GBP. Most currencies are 1 to 100, but not all: some currencies (such as JPY) have no minor unit, and some currencies divide into 100 or 1000. In practice, if you’re dealing with an exact amount of one currency, this will be a whole number – you can’t physically hold 1.5 cents. For this reason, it is recommended you use minor units when storing and calculating with values.
Minor unit exponent: The exponent that to the power of 10 would be multiplied by to convert between major and minor units of currencies where appliable. In simpler words, the number of digits the decimal moves between major and minor representations of the same value (e.g. 1.23 USD = 123 cents, so the decimal moved 2 places to the end – the exponent is 2, as in 1.23 * 10^2 = 123). If you are converting between major and minor yourself, please take care to use a base 10 representation rather than floating point.
Rate: The operand to multiply between two currencies in their major denomination. If you request USD to CAD, the provided rate can be multiplied by your USD value by to get its CAD value.

Get all conversion rates for a currency

https://currency.ayden.tech/USD

{
  "USD": {
    "minorUnitExponent": 2,
    "to": {
      "CAD": {
        "rate": 1.3377,
        "minorUnitExponent": 2
      },
      "GBP": {
        "rate": 0.82709,
        "minorUnitExponent": 2
      },
      // etc...
    }
  }
}

Minor unit exponents

See Definitions above for an introduction to major/minor units.

Warning: Rates are between major denominations. The minor unit exponent is present to assist you in converting values where your target currency has a different minor unit division than your source currency. For example, the rate from USD to JPY as of writing is 139.1. To convert 1.23 USD to JPY, simply do 1.23 * 139.1 = 171.093 (which can be rounded to 171 JPY). This gets tricky if the source amount is in the minor unit, such as if you have 123 cents of USD, i.e. 1.23 USD (minorUnitExponent = 2) – you can’t just multiply the rate by this, because JPY has no minor unit (minorUnitExponent is 0). You can use minorUnitExponent to assist in converting between major and minor units when converting yourself.

If this all sounds scary or like too much work, use the conversion API that handles it for you.

Get conversion rate between currencies

https://currency.ayden.tech/USD/CAD

{
  "USD": {
    "minorUnitExponent": 2,
    "to": {
      "CAD": {
        "rate": 1.3377,
        "minorUnitExponent": 2
      }
    }
  }
}

Multiple output currencies

For more than one output currency, you may specify multiple with a plus sign (+), like so:

https://currency.ayden.tech/USD/CAD+GBP

Convert amount between currencies

By default, this converts using the minor units of a currency (e.g. cents, pence, centavos), if one exists.

https://currency.ayden.tech/500/USD/CAD

{
  "input": {
    "major": 5,
    "minor": 500,
    "of": "USD"
  },
  "to": {
    "CAD": {
      "major": 6.6885,
      "minor": 668.85
    }
  }
}

Multiple output currencies

For more than one output currency, you may specify multiple with a plus sign (+), like so:

https://currency.ayden.tech/5/USD/CAD+GBP

Inputting major units

If you need to specify your input in its major unit (e.g. dollars, pounds, pesos), add /major after the amount:

https://currency.ayden.tech/5/major/USD/CAD

{
  "input": {
    "major": 5,
    "minor": 500,
    "of": "USD"
  },
  "to": {
    "CAD": {
      "major": 6.6885,
      "minor": 668.85
    },
  }
}

Rounding outputs

By default, amounts of output currencies are not rounded to minor units. If you prefer round numbers, add ?round in front of the URL.

For example, converting 5 Canadian Dollars could give you 3.73775 U.S. Dollars (373.775 cents) and 520.18310 Japanese Yen, which may not be suitable for all applications and rounding (minor units) can differ by currency.

https://currency.ayden.tech/5/CAD/USD+JPY?round

This will return 3.74 U.S. Dollars (374 cents) and 520 Japanese Yen instead.