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

# Get one currency-pair rate

> Retrieve one standard pair or request a CBSL LKR rate type.

<Info>
  **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.
</Info>

Use this route when a single rate is enough. `base` and `target` are active three-letter currency codes for a normal conversion. The `target` can also be `LKR-SELL`, `LKR-BUY`, or `LKR-CBSL` to request the appropriate CBSL rate type.

## API endpoint

```text title="GET" theme={null}
https://avraapi.com/api/v1/utility/currency/pair/{base}/{target}
```

## Standard pair request

```bash curl theme={null} theme={null}
curl "https://avraapi.com/api/v1/utility/currency/pair/USD/EUR" \
  -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": "57ce6c72-5a8b-42c2-aa24-27f811c883ed",
  "data": {
    "base": "USD",
    "target": "LKR",
    "rate": 319.752,
    "last_updated": "2026-05-06 00:00:01"
  }
}
```

## Error codes

| HTTP | `error.code` | When it happens |
| - | - | - |
| `400` | <span style={{ whiteSpace: 'nowrap' }}><code>invalid\_currency\_code</code></span> | `{base}` or `{target}` is unknown, inactive, or invalid. Retrieve the active list from [List supported currency codes](/api-reference/currency/list-codes). |
| `401` | <span style={{ whiteSpace: 'nowrap' }}><code>unauthorized</code></span> | The Project Client ID or Client Secret is missing, invalid, inactive, or does not match the selected environment. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>provider\_selection\_failed</code></span> | The Currency provider cannot be selected for the project environment. |
| `429` | <span style={{ whiteSpace: 'nowrap' }}><code>rate\_limit\_exceeded</code></span> | The project has exceeded the Currency service request limit. Wait for `Retry-After` before retrying. |
| `503` | <span style={{ whiteSpace: 'nowrap' }}><code>project\_paused</code></span> | 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.

## CBSL target request

For `LKR-SELL`, `LKR-BUY`, and `LKR-CBSL`, use this same endpoint and replace `{target}` with the required CBSL target code. The response structure is documented in [CBSL Rates](/api-reference/cbsl-rates), including the direct-data fallback rule.

Use [Convert a currency amount](/api-reference/currency/convert-amount) when you need AvraAPI to multiply the rate by a positive amount.

## 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}
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}:
    get:
      tags:
        - Currency
      summary: Get one currency-pair rate
      description: >-
        Returns one conversion rate. For standard currency pairs, AvraAPI
        calculates the available cross rate. A target of `LKR-SELL`, `LKR-BUY`,
        or `LKR-CBSL` requests the corresponding CBSL rate when a direct CBSL
        record is available for the base currency. See the CBSL Rates guide for
        the supported bases and fallback behaviour.
      operationId: getCurrencyPairRate
      parameters:
        - $ref: '#/components/parameters/BaseCurrencyPath'
        - $ref: '#/components/parameters/TargetCurrencyPath'
        - $ref: '#/components/parameters/XEnvironmentHeader'
        - $ref: '#/components/parameters/AcceptJsonHeader'
        - $ref: '#/components/parameters/XPrivacyModeHeader'
      responses:
        '200':
          description: Current rate for the requested pair.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyPairResponse'
              examples:
                standard_pair:
                  summary: Illustrative standard pair
                  value:
                    success: true
                    request_id: 01f00000-0000-4000-8000-000000000003
                    data:
                      base: USD
                      target: EUR
                      rate: 0.9
                      last_updated: '2026-01-15 09:30:00'
                cbsl_target:
                  summary: Illustrative CBSL target request
                  value:
                    success: true
                    request_id: 01f00000-0000-4000-8000-000000000004
                    data:
                      base: USD
                      target: LKR-SELL
                      rate: 305
                      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: <string>
                      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: <string>
                      details: {}
                    meta: {}
        '422':
          description: >-
            The Currency provider cannot be selected for the project
            environment.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CurrencyProviderSelectionFailedErrorEnvelope
              examples:
                provider_selection_failed:
                  value:
                    success: false
                    request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                    error:
                      code: provider_selection_failed
                      message: <string>
                      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: <string>
                      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: <string>
                      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
    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:
    CurrencyPairResponse:
      allOf:
        - $ref: '#/components/schemas/ApiSuccessEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/CurrencyPairData'
    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
    CurrencyProviderSelectionFailedErrorEnvelope:
      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:
                - provider_selection_failed
              example: provider_selection_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
    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.