Exchange Rates API

Get current exchange rates between currencies with optional fee calculation.

Get Exchange Rate

GET

/rates/

Returns the exchange rate between two currencies, with optional fee and amount calculation.

Authentication

Requires OAuth 2.0 authentication with read scope.

Query Parameters

Parameter	Type	Required	Description
`currency_to`	string	Yes	Target currency code (e.g., "USDTERC20")
`currency_from`	string	No	Source currency code (default: "USD")
`amount`	decimal	No	Amount to convert (default: 1.0)
`fee_percentage`	decimal	No	Fee percentage to apply to the calculation
`is_fee_paid_by_user`	boolean	No	Whether the fee is paid by the user
`full`	boolean	No	Include additional rate details (fee info, timestamp)

Example Requests

Basic rate lookup

curl -X GET "{{BASE_URL}}/rates/?currency_to=USDTERC20" \
  -H "Authorization: Bearer your_access_token"

Rate with amount and fees

curl -X GET "{{BASE_URL}}/rates/?currency_from=USD&currency_to=USDTERC20&amount=100&fee_percentage=1.0&full=true" \
  -H "Authorization: Bearer your_access_token"

Response

Basic Response (default)

{
  "currency_from": "USD",
  "currency_to": "USDTERC20",
  "amount": 100.0,
  "estimated_amount": 100.01,
  "rate": 1.0001
}

Full Response (with full=true)

{
  "currency_from": "USD",
  "currency_to": "USDTERC20",
  "amount": 100.0,
  "estimated_amount": 100.01,
  "rate": 1.0001,
  "fee_percentage": 1.0,
  "fee_amount": 1.00,
  "timestamp": "2025-01-15T10:00:00Z"
}

Response with fee_percentage param

When fee_percentage is provided, the response includes additional fee-related fields:

{
  "currency_from": "USD",
  "currency_to": "USDTERC20",
  "amount": 100.0,
  "estimated_amount": 100.01,
  "rate": 1.0001,
  "fee_percentage": 1.0,
  "fee_amount": 1.00,
  "timestamp": "2025-01-15T10:00:00Z",
  "final_tenant_amount": 99.01,
  "is_fee_paid_by_user": false
}

Response Fields

Field	Type	Description	When Included
`currency_from`	string	Source currency code	Always
`currency_to`	string	Target currency code	Always
`amount`	float	Input amount	Always
`estimated_amount`	float	Estimated output amount after conversion	Always
`rate`	float	Exchange rate from source to target	Always
`fee_percentage`	float	Applied fee percentage	When full=true
`fee_amount`	float	Calculated fee amount	When full=true
`timestamp`	datetime	When the rate was retrieved	When full=true
`final_tenant_amount`	float	Final amount the tenant receives after fees	When fee_percentage param provided
`is_fee_paid_by_user`	boolean	Whether the fee is paid by the user	When fee_percentage param provided

Error Responses

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "currency_to is required",
    "details": {}
  }
}

401 Unauthorized

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or missing authentication token",
    "details": {}
  }
}

Usage Examples

Get Rate for Payment Display

async function getPaymentRate(amount, currency, accessToken) {
  const params = new URLSearchParams({
    currency_from: 'USD',
    currency_to: currency,
    amount: amount,
    full: true
  });

  const response = await fetch(
    `{{BASE_URL}}/rates/?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  const data = await response.json();

  console.log(`${data.amount} ${data.currency_from} = ${data.estimated_amount} ${data.currency_to}`);
  console.log(`Rate: ${data.rate}`);

  return data;
}

Rate with Fee Calculation

import requests

def get_rate_with_fees(amount, currency_to, fee_percentage, access_token):
    """Get exchange rate with fee calculation."""

    response = requests.get(
        '{{BASE_URL}}/rates/',
        params={
            'currency_from': 'USD',
            'currency_to': currency_to,
            'amount': amount,
            'fee_percentage': fee_percentage,
            'full': 'true'
        },
        headers={'Authorization': f'Bearer {access_token}'}
    )

    if response.status_code == 200:
        data = response.json()
        print(f"Amount: {data['amount']} {data['currency_from']}")
        print(f"Estimated: {data['estimated_amount']} {data['currency_to']}")
        print(f"Fee: {data['fee_amount']}")
        print(f"Tenant receives: {data['final_tenant_amount']}")
        return data

    return None

Important Notes

Rates are provided for informational purposes and may vary slightly at transaction time
The currency_to parameter is required; all other parameters are optional
Use full=true to get fee and timestamp information
Pass fee_percentage to see how fees affect the final amount
Rates are updated frequently based on market conditions

Get Exchange Rate​