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

# Currency Conversion (/convert)

> Convert amounts between currencies, with optional historical date support (requires authentication)

## Overview

The conversion endpoint converts an amount between any two supported currencies using AUD as the intermediary. It requires authentication and is subject to your plan's monthly quota. Pass an optional `date` parameter to convert using historical rates.

<Note>
  This endpoint requires authentication. [Get your API key](/quickstart) to start making requests.
</Note>

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key: `Bearer your_api_key_here`
</ParamField>

## Query Parameters

<ParamField query="from" type="string" required>
  Source currency code. All supported currencies are available for conversion, including cross-currency pairs (e.g., USD to EUR, JPY to GBP).

  Examples: `AUD`, `USD`, `EUR`, `GBP`, `JPY`
</ParamField>

<ParamField query="to" type="string" required>
  Target currency code (case-insensitive). Must be one of the [supported currencies](/api-reference/public/symbols).

  Examples: `USD`, `EUR`, `GBP`, `JPY`

  <Note>TWI (Trade-Weighted Index) is not allowed for conversion and will return a 400 error.</Note>
</ParamField>

<ParamField query="amount" type="number" required>
  Amount to convert. Must be a positive number.

  Examples: `100`, `1500.50`, `0.01`
</ParamField>

<ParamField query="date" type="string" optional>
  Historical date for conversion in YYYY-MM-DD format. If omitted, uses latest available rates.

  Examples: `2025-08-31`, `2024-12-31`, `2023-06-15`

  <Note>Historical dates: Free plan has no historical access. Starter plan has 30 days access. Professional/Business plans have full historical access.</Note>
</ParamField>

## Request

<CodeGroup>
  ```bash cURL - Latest Rates (AUD to USD) theme={null}
  curl "https://api.exchangeratesapi.com.au/convert?from=AUD&to=USD&amount=100" \
    -H "Authorization: Bearer your_api_key_here"
  ```

  ```bash cURL - Cross Currency (USD to EUR) theme={null}
  curl "https://api.exchangeratesapi.com.au/convert?from=USD&to=EUR&amount=100" \
    -H "Authorization: Bearer your_api_key_here"
  ```

  ```bash cURL - Historical Conversion theme={null}
  curl "https://api.exchangeratesapi.com.au/convert?from=EUR&to=GBP&amount=100&date=2025-08-31" \
    -H "Authorization: Bearer your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  // Latest conversion
  const params = new URLSearchParams({
    from: 'AUD',
    to: 'USD',
    amount: '100'
  });

  const response = await fetch(`https://api.exchangeratesapi.com.au/convert?${params}`, {
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    }
  });

  // Historical conversion
  const historicalParams = new URLSearchParams({
    from: 'AUD',
    to: 'USD',
    amount: '100',
    date: '2025-08-31'
  });

  const historicalResponse = await fetch(`https://api.exchangeratesapi.com.au/convert?${historicalParams}`, {
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  # Latest conversion
  url = "https://api.exchangeratesapi.com.au/convert"
  headers = {
      "Authorization": "Bearer your_api_key_here"
  }
  params = {
      "from": "AUD",
      "to": "USD",
      "amount": 100
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()

  # Historical conversion
  historical_params = {
      "from": "AUD",
      "to": "USD",
      "amount": 100,
      "date": "2025-08-31"
  }

  historical_response = requests.get(url, headers=headers, params=historical_params)
  historical_data = historical_response.json()
  ```

  ```php PHP theme={null}
  <?php
  // Latest conversion
  $params = http_build_query([
      'from' => 'AUD',
      'to' => 'USD',
      'amount' => 100
  ]);

  $curl = curl_init();
  curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.exchangeratesapi.com.au/convert?{$params}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer your_api_key_here'
    ),
  ));

  $response = curl_exec($curl);
  curl_close($curl);

  // Historical conversion
  $historical_params = http_build_query([
      'from' => 'AUD',
      'to' => 'USD',
      'amount' => 100,
      'date' => '2025-08-31'
  ]);

  $historical_curl = curl_init();
  curl_setopt_array($historical_curl, array(
    CURLOPT_URL => "https://api.exchangeratesapi.com.au/convert?{$historical_params}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer your_api_key_here'
    ),
  ));

  $historical_response = curl_exec($historical_curl);
  curl_close($historical_curl);
  ?>
  ```
</CodeGroup>

## Response

<ResponseExample>
  ```json 200 OK - Latest Conversion theme={null}
  {
    "success": true,
    "query": {
      "from": "AUD",
      "to": "USD", 
      "amount": 100
    },
    "info": {
      "timestamp": 1725148800,
      "rate": 0.643512
    },
    "date": "2025-09-01",
    "result": 64.3512
  }
  ```

  ```json 200 OK - Historical Conversion theme={null}
  {
    "success": true,
    "query": {
      "from": "AUD",
      "to": "USD",
      "amount": 100
    },
    "info": {
      "timestamp": 1725062400,
      "rate": 0.643512
    },
    "date": "2025-08-31",
    "result": 64.3512
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="query" type="object">
  Echo of the conversion parameters from the request

  <Expandable title="query object">
    <ResponseField name="from" type="string">
      Source currency code from request
    </ResponseField>

    <ResponseField name="to" type="string">
      Target currency code from request
    </ResponseField>

    <ResponseField name="amount" type="number">
      Amount to convert from request
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="info" type="object">
  Information about the exchange rate used

  <Expandable title="info object">
    <ResponseField name="timestamp" type="integer">
      Unix timestamp for the rate date (midnight UTC)
    </ResponseField>

    <ResponseField name="rate" type="number">
      Exchange rate used for conversion (AUD per unit of foreign currency) with up to 6 decimal places
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="date" type="string">
  Date of the exchange rate used in YYYY-MM-DD format
</ResponseField>

<ResponseField name="result" type="number">
  Conversion result with 4 decimal places
</ResponseField>

## Response Headers

* `Cache-Control: no-store` - Response should not be cached
* `X-Request-Id: <uuid>` - Unique request identifier for debugging
* `X-Data-Stale: true` - Present only when serving fallback data (latest rates only)
* `X-RBA-Source-Date: YYYY-MM-DD` - Present only when serving fallback data (latest rates only)

## Error Responses

<ResponseExample>
  ```json 400 Bad Request - Missing Parameters theme={null}
  {
    "success": false,
    "error": {
      "code": 400,
      "type": "bad_request",
      "info": "Missing required parameters: from, to, amount"
    }
  }
  ```

  ```json 400 Bad Request - Invalid Amount theme={null}
  {
    "success": false,
    "error": {
      "code": 400,
      "type": "bad_request",
      "info": "Invalid amount. Must be a positive number"
    }
  }
  ```

  ```json 400 Bad Request - Invalid Currency theme={null}
  {
    "success": false,
    "error": {
      "code": 400,
      "type": "bad_request",
      "info": "Unsupported currency 'XYZ'"
    }
  }
  ```

  ```json 400 Bad Request - TWI Not Allowed theme={null}
  {
    "success": false,
    "error": {
      "code": 400,
      "type": "bad_request",
      "info": "TWI is not allowed for conversion"
    }
  }
  ```

  ```json 400 Bad Request - Unsupported Currency theme={null}
  {
    "success": false,
    "error": {
      "code": 400,
      "type": "bad_request",
      "info": "Unsupported currency 'XYZ'"
    }
  }
  ```

  ```json 400 Bad Request - Invalid Date Format theme={null}
  {
    "success": false,
    "error": {
      "code": 400,
      "type": "bad_request",
      "info": "Invalid date format. Use YYYY-MM-DD"
    }
  }
  ```

  ```json 404 Not Found - Historical Data theme={null}
  {
    "success": false,
    "error": {
      "code": 404,
      "type": "not_found",
      "info": "No data available for date 2025-12-25"
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "code": 401,
      "type": "unauthorized",
      "info": "Invalid or missing API key"
    }
  }
  ```

  ```json 503 Service Unavailable theme={null}
  {
    "success": false,
    "error": {
      "code": 503,
      "type": "unavailable",
      "info": "Rates temporarily unavailable"
    }
  }
  ```
</ResponseExample>

## Rate Limits

This endpoint is subject to your plan's monthly request limits:

| Plan         | Monthly Requests | Historical Access    | Rate Limiting          |
| ------------ | ---------------- | -------------------- | ---------------------- |
| Free         | 300              | No historical data   | No per-endpoint limits |
| Starter      | 5,000            | Last 30 days         | No per-endpoint limits |
| Professional | 50,000           | Full history (2018+) | No per-endpoint limits |
| Business     | 500,000          | Full history (2018+) | No per-endpoint limits |

<Info>
  Conversion has no additional per-endpoint rate limiting beyond your plan's monthly quota.
</Info>

## Current Limitations

<Warning>
  **Current API limitations:**

  * **TWI restriction**: Trade-Weighted Index cannot be used for conversions
  * **Date format**: Historical dates must be in YYYY-MM-DD format
  * **Date availability**: Weekend and holiday dates (when RBA doesn't publish) will return 404
  * **Rate precision**: Some currencies (IDR, VND) are provided as whole numbers by the RBA source data
</Warning>

## Precision & Calculation

* **Rate precision**: Exchange rates provided with up to 6 decimal places (varies by currency)
* **Currency-specific precision**: IDR and VND are provided as whole numbers by the Reserve Bank of Australia
* **Result precision**: Conversion results rounded to 4 decimal places
* **Calculation method**: `result = amount × rate` using decimal-safe arithmetic
* **Storage format**: Rates stored as micro-units (rate × 1e6) for precision where applicable
* **Rounding**: Only applied at response boundary, not during calculations

### Currency Precision Table

| Currency         | Example Rate | Decimal Places    | Source |
| ---------------- | ------------ | ----------------- | ------ |
| USD, EUR, GBP    | 0.6566       | Up to 4           | RBA    |
| JPY, KRW         | 97.26        | Up to 2           | RBA    |
| IDR, VND         | 10739        | 0 (whole numbers) | RBA    |
| Other currencies | Varies       | Up to 6           | RBA    |

## Use Cases

* **Invoice Processing**: Convert AUD amounts to foreign currencies for international transactions
* **E-commerce**: Real-time price conversion for international customers
* **Financial Analysis**: Historical conversion analysis with exact dated rates
* **Accounting Integration**: Automated conversion with official RBA rates
* **Compliance Reporting**: ATO-compliant currency conversion using official rates
* **Contract Settlements**: Apply exact historical rates to dated agreements

## Historical Conversion by Plan

| Plan         | Monthly Requests | Historical Dates       |
| ------------ | ---------------- | ---------------------- |
| Free         | 300              | ❌ Not available        |
| Starter      | 5,000            | ✅ Last 30 days         |
| Professional | 50,000           | ✅ Full history (2018+) |
| Business     | 500,000          | ✅ Full history (2018+) |


## OpenAPI

````yaml GET /convert
openapi: 3.1.0
info:
  title: RBA Exchange Rates API
  description: >-
    Official Reserve Bank of Australia (RBA) exchange rate data through a modern
    REST API. Transforms publicly available RBA data into clean JSON endpoints
    for Australian businesses and developers who need reliable AUD exchange
    rates.
  version: 1.0.0
  license:
    name: MIT
  contact:
    url: https://www.exchangeratesapi.com.au
servers:
  - url: https://api.exchangeratesapi.com.au
    description: Production API
security: []
paths:
  /convert:
    get:
      summary: Currency Conversion
      description: >-
        Convert amounts between currencies. Requires authentication. Free tier:
        300, no historical data. Starter: 5,000/month, 30 days history.
        Professional: 50,000/month, full history. Business: 500,000/month, full
        history.
      operationId: convertCurrency
      parameters:
        - name: from
          in: query
          required: true
          description: Source currency code
          schema:
            $ref: '#/components/schemas/CurrencyCode'
          example: AUD
        - name: to
          in: query
          required: true
          description: Target currency code
          schema:
            $ref: '#/components/schemas/CurrencyCode'
          example: USD
        - name: amount
          in: query
          required: true
          description: Amount to convert
          schema:
            type: number
            minimum: 0
            exclusiveMinimum: true
          example: 100
        - name: date
          in: query
          required: false
          description: >-
            Historical date for conversion (YYYY-MM-DD). Requires
            authentication.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2025-08-31'
      responses:
        '200':
          description: Conversion result
          headers:
            X-RateLimit-Limit-Monthly:
              description: >-
                Monthly request limit based on plan (Free=300, Starter=5,000,
                Professional=50,000, Business=500,000)
              schema:
                type: integer
            X-RateLimit-Remaining-Monthly:
              description: Remaining requests in current monthly period
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertResponse'
              example:
                success: true
                query:
                  from: AUD
                  to: USD
                  amount: 100
                info:
                  timestamp: 1725148800
                  rate: 0.678234
                date: '2025-09-01'
                result: 67.8234
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerAuth: []
components:
  schemas:
    CurrencyCode:
      type: string
      enum:
        - AUD
        - USD
        - EUR
        - GBP
        - JPY
        - CNY
        - KRW
        - INR
        - SGD
        - NZD
        - THB
        - MYR
        - IDR
        - VND
        - HKD
        - PHP
        - CAD
        - CHF
        - TWD
        - TWI
        - SDR
      description: Three-letter currency code
    ConvertResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        query:
          type: object
          properties:
            from:
              type: string
            to:
              type: string
            amount:
              type: number
          required:
            - from
            - to
            - amount
        info:
          type: object
          properties:
            timestamp:
              type: integer
              description: Unix timestamp of the rate date
            rate:
              type: number
              description: >-
                Exchange rate used for conversion with precision varying by
                currency (up to 6 decimal places for most, whole numbers for
                IDR/VND as provided by RBA)
          required:
            - rate
        date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        result:
          type: number
          description: Conversion result
      required:
        - success
        - query
        - info
        - date
        - result
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP status code
            type:
              type: string
              description: Error type identifier
            info:
              type: string
              description: Human-readable error description
          required:
            - code
            - type
            - info
      required:
        - success
        - error
  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: 400
              type: bad_request
              info: Invalid currency format. Use 3-letter currency code (e.g., USD)
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: 429
              type: rate_limit
              info: >-
                Quota exceeded. Free=300 (one-time trial), Starter=5,000/month,
                Professional=50,000/month, Business=500,000/month.
    ServiceUnavailable:
      description: Service temporarily unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: 503
              type: unavailable
              info: Rates temporarily unavailable
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key authentication using Bearer token

````