> ## 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.
# Convert a currency amount
> Calculate a conversion for one positive amount using the current pair rate.
**Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
This route returns the current pair rate, the parsed numeric `amount`, and `conversion_result`. AvraAPI calculates `rate × amount` and rounds the result to six decimal places.
## API endpoint
```text title="GET" theme={null}
https://avraapi.com/api/v1/utility/currency/pair/{base}/{target}/{amount}
```
## Request
```bash curl theme={null} theme={null}
curl "https://avraapi.com/api/v1/utility/currency/pair/USD/LKR/100.50" \
-H "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
-H "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
-H "X-ENV: development" \
-H "Accept: application/json"
```
## 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"
}
}
```
## Error codes
| HTTP | `error.code` | When it happens |
| - | - | - |
| `400` | invalid\_currency\_code | `{base}` or `{target}` is unknown, inactive, or invalid. Retrieve the active list from [List supported currency codes](/api-reference/currency/list-codes). |
| `401` | unauthorized | The Project Client ID or Client Secret is missing, invalid, inactive, or does not match the selected environment. |
| `422` | validation\_failed | `{amount}` is not numeric or is less than or equal to zero. The response includes `error.details.amount`. |
| `422` | provider\_selection\_failed | The Currency provider cannot be selected for the project environment. |
| `429` | rate\_limit\_exceeded | The project has exceeded the Currency service request limit. Wait for `Retry-After` before retrying. |
| `503` | project\_paused | The project is paused and cannot make API requests. |
All failures use the standard AvraAPI error envelope. Keep the `request_id` when contacting support; see the [REST API guide](/api-reference/rest-api#common-response-behaviour) for the shared response format.
`amount` is a path value, not a JSON body. It must be numeric and greater than zero. Invalid values, including `0` and negative numbers, return `422` with `error.code: validation_failed` and an `error.details.amount` message.
To apply a CBSL rate type, replace `{target}` with `LKR-SELL`, `LKR-BUY`, or `LKR-CBSL`. See [CBSL Rates](/api-reference/cbsl-rates) for the three rate types, full request examples, and their response structure.
The response is an application calculation, not a binding financial quote. Apply your own rounding, tax, pricing, and approval rules before using it in a customer-facing transaction.
## Playground resources
The generated reference below lists this endpoint's API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.
## OpenAPI
````yaml api-reference/provider-api.openapi.yaml GET /utility/currency/pair/{base}/{target}/{amount}
openapi: 3.0.3
info:
title: AvraAPI Provider API
version: 1.0.0
description: >-
The reviewed public contract for AvraAPI provider services. Operations are
added to this document only after their route, validation, response,
privacy, usage, and public-safety contracts have been verified.
servers:
- url: https://avraapi.com/api/v1
description: AvraAPI REST API v1
security:
- ApiKeyHeader: []
ApiSecretHeader: []
tags:
- name: Currency
description: Currency codes, exchange rates, and conversion.
- name: SMS
description: Messaging operations through configured AvraAPI providers.
- name: Security
description: IP and email security checks.
- name: Location
description: IP geolocation and intelligence.
- name: Utilities
description: QR code, barcode, and PDF generation.
paths:
/utility/currency/pair/{base}/{target}/{amount}:
get:
tags:
- Currency
summary: Convert a positive amount with one currency-pair rate
description: >-
Returns the selected pair rate and an amount conversion rounded to six
decimal places. `amount` must be numeric and greater than zero. Use the
pair route when you only need the rate.
operationId: convertCurrencyPairAmount
parameters:
- $ref: '#/components/parameters/BaseCurrencyPath'
- $ref: '#/components/parameters/TargetCurrencyPath'
- $ref: '#/components/parameters/PositiveAmountPath'
- $ref: '#/components/parameters/XEnvironmentHeader'
- $ref: '#/components/parameters/AcceptJsonHeader'
- $ref: '#/components/parameters/XPrivacyModeHeader'
responses:
'200':
description: Current pair rate and calculated amount.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/CurrencyConversionResponse'
examples:
illustrative:
summary: Illustrative response shape, not current market data
value:
success: true
request_id: 01f00000-0000-4000-8000-000000000005
data:
base: USD
target: LKR-SELL
rate: 305
amount: 100
conversion_result: 30500
last_updated: '2026-01-15 09:30:00'
'400':
description: One or more currency codes are unknown or inactive.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/CurrencyInvalidCurrencyCodeErrorEnvelope'
examples:
invalid_currency_code:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: invalid_currency_code
message:
details: {}
meta: {}
'401':
description: >-
Missing, invalid, inactive, or environment-mismatched project
credentials.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/CurrencyUnauthorizedErrorEnvelope'
examples:
unauthorized:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: unauthorized
message:
details: {}
meta: {}
'422':
description: The amount is not a positive numeric value.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/CurrencyValidationErrorEnvelope'
examples:
validation_failed:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: validation_failed
message:
details: {}
meta: {}
'429':
description: The configured Currency request limit has been reached.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
Retry-After:
$ref: '#/components/headers/RetryAfterHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/CurrencyRateLimitedErrorEnvelope'
examples:
rate_limit_exceeded:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: rate_limit_exceeded
message:
details: {}
meta: {}
'503':
description: The project is paused and cannot make API requests.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/CurrencyProjectPausedErrorEnvelope'
examples:
project_paused:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: project_paused
message:
details: {}
meta: {}
components:
parameters:
BaseCurrencyPath:
name: base
in: path
required: true
description: >-
An active three-letter currency code. Input is normalised to uppercase
before it is checked against the active Currency code list.
schema:
type: string
pattern: ^[A-Za-z]{3}$
example: USD
TargetCurrencyPath:
name: target
in: path
required: true
description: >-
An active three-letter currency code, or one of `LKR-SELL`, `LKR-BUY`,
and `LKR-CBSL` for a CBSL request.
schema:
type: string
pattern: ^(?:[A-Za-z]{3}|LKR-(?:SELL|BUY|CBSL))$
example: LKR
PositiveAmountPath:
name: amount
in: path
required: true
description: Numeric amount greater than zero.
schema:
type: string
example: '100.50'
XEnvironmentHeader:
name: X-ENV
in: header
required: false
description: >-
Selects the Development credential environment. The Documentation
Playground exposes Development values only; normal backend integrations
may use their documented Production credentials outside this tool.
schema:
type: string
enum:
- dev
- development
default: development
AcceptJsonHeader:
name: Accept
in: header
required: false
description: Requests a JSON response where the selected operation supports JSON.
schema:
type: string
example: application/json
XPrivacyModeHeader:
name: X-Privacy-Mode
in: header
required: false
description: >-
Optional privacy override. Turn this on to request that AvraAPI suppress
request-payload storage in observability logs for this request.
schema:
type: boolean
default: false
example: true
headers:
RequestIdHeader:
description: AvraAPI request identifier for support and troubleshooting.
schema:
type: string
format: uuid
RetryAfterHeader:
description: Seconds to wait before retrying a rate-limited request.
schema:
type: integer
minimum: 0
schemas:
CurrencyConversionResponse:
allOf:
- $ref: '#/components/schemas/ApiSuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/CurrencyConversionData'
CurrencyInvalidCurrencyCodeErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- invalid_currency_code
example: invalid_currency_code
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
CurrencyUnauthorizedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- unauthorized
example: unauthorized
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
CurrencyValidationErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- validation_failed
example: validation_failed
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
CurrencyRateLimitedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- rate_limit_exceeded
example: rate_limit_exceeded
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
CurrencyProjectPausedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- project_paused
example: project_paused
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
ApiSuccessEnvelope:
type: object
required:
- success
- request_id
- data
properties:
success:
type: boolean
enum:
- true
request_id:
type: string
format: uuid
description: Include this value when contacting AvraAPI support.
data:
description: Operation-specific result data.
nullable: true
CurrencyConversionData:
allOf:
- $ref: '#/components/schemas/CurrencyPairData'
- type: object
required:
- amount
- conversion_result
properties:
amount:
type: number
format: double
description: Parsed numeric input amount.
conversion_result:
type: number
format: double
description: rate × amount, rounded to six decimal places.
CurrencyPairData:
type: object
required:
- base
- target
- rate
- last_updated
properties:
base:
type: string
example: USD
target:
type: string
example: LKR
rate:
type: number
format: double
description: The rate for one unit of `base` in `target`.
last_updated:
type: string
nullable: true
description: >-
Source-update value held by AvraAPI. Its format is not a versioned
API guarantee.
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: X-API-KEY
description: >-
Your Development project's Client ID. Enter your own value in the
Documentation Playground.
ApiSecretHeader:
type: apiKey
in: header
name: X-API-SECRET
description: >-
Your Development project's Client Secret. Mintlify does not proxy these
requests; the browser sends them directly to AvraAPI. Never enter a
Production secret in the Documentation Playground.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.