> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK currency services

> Use the AvraAPI Node.js SDK to retrieve active currency codes, rates, and conversions.

Use `avraapi.currency()` for the four released Currency operations. Every call
is asynchronous and resolves to an `ApiResponse`; retain `requestId` for
support and troubleshooting.

<Note>
  Every Currency operation supports the shared one-request privacy control:
  `avraapi.currency().withPrivacyMode().getCodes()`. It sends
  `X-Privacy-Mode: 1` for that request only, then clears automatically.
</Note>

The SDK trims and uppercases `base` and `target` before sending them. They must
still be active Currency codes, so retrieve the current set instead of keeping
a hard-coded list.

## Get supported currency codes

`getCodes(): Promise<ApiResponse>` returns the active code list, including
target-only CBSL codes when available.

**SDK function**

```ts title="Copy the SDK call" theme={null}
const response = await avraapi.currency().getCodes();
```

```ts title="Read the active code list" theme={null}
import type { CurrencyCodesData } from '@avraapi/node-sdk';

// AvraAPI SDK call.
const response = await avraapi.currency().getCodes();

// Your application code. The runtime response is an ApiResponse.
const data = response.data as CurrencyCodesData;
const count = data.count;
const firstCode = data.codes[0]?.code;
const firstName = data.codes[0]?.name;
const requestId = response.requestId;
```

### Response

```json theme={null}
{
  "success": true,
  "request_id": "d57a5f8b-69bc-4877-8da7-31bb9dbfa575",
  "data": {
    "count": 169,
    "codes": [
      {"code": "AED", "name": "UAE Dirham"},
      {"code": "AFN", "name": "Afghan Afghani"},
      {"code": "ALL", "name": "Albanian Lek"}
    ]
  }
}
```

The list is shortened only for readability. `LKR-SELL`, `LKR-BUY`, and
`LKR-CBSL` are target-only CBSL codes, not ordinary base currencies. See
[CBSL Rates](/api-reference/cbsl-rates) for their meanings.

## Get latest rates from one base currency

`getLatestRates(base: string): Promise<ApiResponse>` returns the available
rate map for one base currency. The base is not repeated in `data.rates`.

**SDK function**

```ts title="Copy the SDK call" theme={null}
const response = await avraapi.currency().getLatestRates('BASE_CURRENCY');
```

| Argument | Use |
| - | - |
| `base` | Active source currency, for example `USD`. |

```ts title="Read a rate map" theme={null}
import type { CurrencyLatestRatesData } from '@avraapi/node-sdk';

// AvraAPI SDK call.
const response = await avraapi.currency().getLatestRates('usd');

// Your application code.
const data = response.data as CurrencyLatestRatesData;
const base = data.base;
const eurRate = data.rates.EUR;
const updatedAt = data.last_updated;
```

### Response

```json theme={null}
{
  "success": true,
  "request_id": "882bc900-bd42-4286-a828-2594636245e6",
  "data": {
    "base": "USD",
    "last_updated": "2026-05-06T00:00:01.000000Z",
    "rates": {"AED": 3.6725, "AFN": 63.9347, "ALL": 82.0532}
  }
}
```

Treat `last_updated` as a freshness value, not a binding financial quote. Apply
your own pricing, approval, and rounding rules before displaying a price.

## Get one currency-pair rate

`getPairRate(base: string, target: string): Promise<ApiResponse>` returns one
rate. A target can be a standard active currency or `LKR-SELL`, `LKR-BUY`, or
`LKR-CBSL` for the applicable CBSL rate type.

**SDK function**

```ts title="Copy the SDK call" theme={null}
const response = await avraapi.currency().getPairRate(
  'BASE_CURRENCY',
  'TARGET_CURRENCY',
);
```

| Argument | Use |
| - | - |
| `base` | Active source currency, for example `USD`. |
| `target` | Active target currency, for example `LKR`. |

```ts title="Read one pair rate" theme={null}
import type { CurrencyPairRateData } from '@avraapi/node-sdk';

// AvraAPI SDK call.
const response = await avraapi.currency().getPairRate('USD', 'LKR');

// Your application code.
const data = response.data as CurrencyPairRateData;
const pair = `${data.base}/${data.target}`;
const rate = data.rate;
const updatedAt = data.last_updated;
```

### Response

```json theme={null}
{
  "success": true,
  "request_id": "57ce6c72-5a8b-42c2-aa24-27f811c883ed",
  "data": {
    "base": "USD",
    "target": "LKR",
    "rate": 319.752,
    "last_updated": "2026-05-06 00:00:01"
  }
}
```

For CBSL target behaviour, read [CBSL Rates](/api-reference/cbsl-rates).

## Convert a currency amount

`convert(base: string, target: string, amount: number): Promise<ApiResponse>`
calculates a current conversion for one positive amount.

**SDK function**

```ts title="Copy the SDK call" theme={null}
const response = await avraapi.currency().convert(
  'BASE_CURRENCY',
  'TARGET_CURRENCY',
  10,
);
```

| Argument | Use |
| - | - |
| `base` | Active source currency, for example `USD`. |
| `target` | Active target currency, for example `LKR`. |
| `amount` | Positive amount to convert. |

```ts title="Convert and use a positive amount" theme={null}
import type { CurrencyConvertData } from '@avraapi/node-sdk';

// AvraAPI SDK call.
const response = await avraapi.currency().convert('USD', 'LKR', 10);

// Your application code.
const data = response.data as CurrencyConvertData;
const display = `${data.amount} ${data.base} = ${data.conversion_result} ${data.target}`;
const rateUsed = data.rate;
```

### Response

```json theme={null}
{
  "success": true,
  "request_id": "f6bd3df0-c642-446c-ba2b-345bbb3fd0e9",
  "data": {
    "base": "USD",
    "target": "LKR",
    "rate": 319.752,
    "amount": 10,
    "conversion_result": 3197.52,
    "last_updated": "2026-05-06 00:00:01"
  }
}
```

The result is an application calculation, not a settlement instruction. See
the [Currency REST API Reference](/api-reference/currency/convert-amount) for
the full validation and error contract.

## Handle Currency errors

Currency calls reject with typed SDK errors rather than resolving to an error
`ApiResponse`. Use the common pattern in [Node.js Overview and setup](/sdk/nodejs/overview-and-setup#handle-errors-safely), and retain an error's
`requestId` only in backend support records.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.