Convert

Converts an amount from one currency to another using current exchange rates. Returns both the original and converted amounts.

Endpoint

POST/v2/currency

Link

Gateway APIstagep.tst-apidmndelss.com

Request

Headers

Key	Value	Required
Authorization	Bearer <JWT>	Yes
Content-Type	application/json	Yes
Accept	application/json	Yes

Request Body (JSON)

Field	Type	Description	Required	Example
amount	object	Source amount to convert (see Money Object below).	Yes	-
toCurrencyIso	string	Target currency (ISO 4217 code).	Yes	"EUR"

Money Object

Field	Type	Description	Example
currencyCode	string	Source currency (ISO 4217 code).	"USD"
units	string	Whole units (e.g., dollars).	"100"
nanos	integer	Fractional units (nanos = 10^-9).	500000000 (= $0.50)

Example Request Body:

json

{
  "amount": {
    "currencyCode": "USD",
    "units": "100",
    "nanos": 500000000
  },
  "toCurrencyIso": "EUR"
}

---

Response (200 OK)

Returns both the original and converted amounts.

Response Fields

Field	Type	Description	Example
sourceAmount	object	Original amount (matches request).	-
convertedAmount	object	Converted amount (see Money Object).	-

Money Object (for both amounts)

Field	Type	Description	Example
currencyCode	string	Currency code.	"EUR"
units	string	Whole units.	"93"
nanos	integer	Fractional units.	250000000 (= €0.25)

Example Response:

json

{
  "sourceAmount": {
    "currencyCode": "USD",
    "units": "100",
    "nanos": 500000000
  },
  "convertedAmount": {
    "currencyCode": "EUR",
    "units": "93",
    "nanos": 250000000
  }
}

*Translation: $100.50 USD = €93.25 EUR*

---

Examples

Request

bash

curl -X POST 'https://stagep.tst-apidmndelss.com/v2/currency' \
  -H 'Authorization: Bearer eyJhbGci...wNLGA' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": {
      "currencyCode": "USD",
      "units": "50",
      "nanos": 0
    },
    "toCurrencyIso": "JPY"
  }'

Response

json

{
  "sourceAmount": {
    "currencyCode": "USD",
    "units": "50",
    "nanos": 0
  },
  "convertedAmount": {
    "currencyCode": "JPY",
    "units": "5500",
    "nanos": 0
  }
}

---

Error Cases

1. Invalid Currency:

   json

   { "error": "Unsupported currency code: XYZ" }

2. Missing Parameters:

   json

   { "error": "amount and toCurrencyIso are required" }

3. Rate Unavailable:

   json

   { "error": "Exchange rate not available for USD to BTC" }

---

Notes

• Rate Source: Uses real-time exchange rates (updated frequently).
• Precision: Conversion maintains high precision (nanos = 10^-9).
• Fees: Conversion may include applicable fees (check system configuration).

Real request example

  {
  "amount": {
    "currencyCode": "EUR",
    "units": "10",
    "nanos": 0
  },
  "currencyCodeTo": "USD"
}
{
  "amount": {
    "currencyCode": "EUR",
    "units": "10",
    "nanos": 0
  },
  "currencyCodeTo": "USD"
}

Real response example

200 OK

{
  "sourceAmount": {
    "currencyCode": "EUR",
    "units": "10",
    "nanos": 0
  },
  "convertedAmount": {
    "currencyCode": "USD",
    "units": "11",
    "nanos": 606401205
  }
}