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

# Laravel SDK currency services

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

Use `AvraAPI::currency()` for the four released Currency operations. Every
method returns `ApiResponse`; read the operation result from `data` and 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` only for the 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 `base` and `target` before sending a request.
  They must still be active Currency codes. Call `getCodes()` rather than
  maintaining a hard-coded currency list.
</Note>

## Get supported currency codes

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

**SDK function**

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

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

use Avraapi\Laravel\Facades\AvraAPI;

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

// Your application code.
$count = $response->data['count'];
$codes = $response->data['codes'];
$firstCode = $codes[0]['code'];
$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 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).

## Get latest rates from one base currency

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

**SDK function**

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

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

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

use Avraapi\Laravel\Facades\AvraAPI;

// 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 a binding financial quote.
Apply your own pricing, approval, and rounding rules before displaying a price.

## Get one currency-pair rate

`getPairRate(string $base, string $target): ApiResponse` returns one rate. The
target can 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_CURRENCY',
    '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

use Avraapi\Laravel\Facades\AvraAPI;

// 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, 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.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = AvraAPI::currency()->convert(
    'BASE_CURRENCY',
    'TARGET_CURRENCY',
    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

use Avraapi\Laravel\Facades\AvraAPI;

// 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
binding rate. See [Convert a currency amount](/api-reference/currency/convert-amount).

## Handle Currency errors

Currency methods throw typed SDK exceptions instead of returning an error
`ApiResponse`. Use the Laravel-safe exception pattern in
[Laravel Overview and setup](/sdk/laravel/overview-and-setup#handle-errors-safely)
and the linked REST pages for operation-specific error codes.


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