> ## 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.

# PHP SDK currency services

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

Use `$avraapi->currency()` for the four released Currency operations. Every
method returns an `ApiResponse`; read its operation result from `data` and keep
`requestId` for support and troubleshooting.

<Note>
  Every Currency operation can use the shared one-request privacy control:
  `$avraapi->currency()->withPrivacyMode()->getCodes()`. It sends
  `X-Privacy-Mode: 1` only for that next request, then clears automatically.
  Privacy Mode keeps normal routing, billing, and usage tracking while
  suppressing request and response payload storage.
</Note>

<Note>
  The SDK trims and uppercases the `base` and `target` arguments before sending
  a request. They must still be active Currency codes. Retrieve the current
  set with `getCodes()` instead of maintaining a hard-coded list.
</Note>

## Get supported currency codes

`getCodes(): ApiResponse` returns the active Currency codes, including CBSL
target codes when they are available.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = $avraapi->currency()->getCodes();
```

```php title="Read the active code list" theme={null}
<?php

// AvraAPI SDK call.
$response = $avraapi->currency()->getCodes();

// Your application code.
$count = $response->data['count'];
$codes = $response->data['codes'];
$firstCode = $codes[0]['code'];
$firstName = $codes[0]['name'];
$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 API returns every active code; the sample 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(string $base): ApiResponse` returns the available rate map for
one active base currency. The base currency is not repeated in `data.rates`.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = $avraapi->currency()->getLatestRates(
    base: 'BASE_CURRENCY',
);
```

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

```php title="Read a rate map" theme={null}
<?php

// AvraAPI SDK call.
$response = $avraapi->currency()->getLatestRates('usd');

// Your application code.
$base = $response->data['base'];
$eurRate = $response->data['rates']['EUR'];
$updatedAt = $response->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 as a binding financial quote.
Apply your own pricing, approval, and rounding rules before displaying a
customer-facing price.

## Get one currency-pair rate

`getPairRate(string $base, string $target): ApiResponse` returns one rate. For
a standard pair, both values are active currency codes. The target can also be
`LKR-SELL`, `LKR-BUY`, or `LKR-CBSL` for a CBSL rate type.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = $avraapi->currency()->getPairRate(
    base: 'BASE_CURRENCY',
    target: 'TARGET_CURRENCY',
);
```

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

```php title="Read one pair rate" theme={null}
<?php

// AvraAPI SDK call.
$response = $avraapi->currency()->getPairRate('USD', 'LKR');

// Your application code.
$rate = $response->data['rate'];
$pair = $response->data['base'].'/'.$response->data['target'];
$updatedAt = $response->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 and response details, read [CBSL Rates](/api-reference/cbsl-rates).

## Convert a currency amount

`convert(string $base, string $target, float $amount): ApiResponse` calculates
the current conversion for one positive amount. The `amount` argument must be
greater than zero.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = $avraapi->currency()->convert(
    base: 'BASE_CURRENCY',
    target: 'TARGET_CURRENCY',
    amount: 10.0,
);
```

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

```php title="Convert and use a positive amount" theme={null}
<?php

// AvraAPI SDK call.
$response = $avraapi->currency()->convert('USD', 'LKR', 10.0);

// Your application code.
$convertedAmount = $response->data['conversion_result'];
$rateUsed = $response->data['rate'];
$display = sprintf(
    '%s %s = %s %s',
    $response->data['amount'],
    $response->data['base'],
    $convertedAmount,
    $response->data['target'],
);
```

### 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 or a
binding rate. The [Currency REST API Reference](/api-reference/currency/convert-amount)
has the full validation and error contract.

## Handle Currency errors

Currency methods throw typed SDK exceptions instead of returning an error
`ApiResponse`. See [PHP Overview and setup](/sdk/php/overview-and-setup#handle-errors-safely)
for the common exception pattern, and use the linked REST pages for each
operation's error codes.


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