> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling Currencies

> Best practices for working with multi-currency operations

## Overview

The HopNow API supports multiple currencies for accounts, balances, payins, payouts, and FX operations. This guide covers best practices for handling currencies correctly.

## Supported Currencies

The API supports all major fiat currencies (ISO 4217) and popular cryptocurrencies:

### Fiat Currencies

* **USD** - US Dollar
* **EUR** - Euro
* **GBP** - British Pound
* **MXN** - Mexican Peso
* **BRL** - Brazilian Real
* And 150+ other ISO 4217 currencies

### Cryptocurrencies

* **BTC** - Bitcoin
* **ETH** - Ethereum
* **USDC\_ETHEREUM** - USD Coin on Ethereum
* **USDC\_POLYGON** - USD Coin on Polygon
* **USDT** - Tether

## Currency Codes

Always use standard currency codes:

```python theme={null}
# Good - ISO 4217 codes
amount_usd = "100.00"
currency = "USD"

# Good - Crypto with network
currency = "USDC_ETHEREUM"

# Bad - Do not use symbols
currency = "$"  # ❌ Invalid
```

## Decimal Precision

Different currencies have different decimal precision requirements:

### Standard Fiat (2 decimals)

```json theme={null}
{
  "amount": "100.50",
  "currency": "USD"
}
```

### Zero-Decimal Currencies

Some currencies don't use decimal places (e.g., JPY, KRW):

```json theme={null}
{
  "amount": "10000",
  "currency": "JPY"
}
```

### Cryptocurrencies (up to 8 decimals)

```json theme={null}
{
  "amount": "0.00123456",
  "currency": "BTC"
}
```

## Amount Formatting

Always use string format for amounts to avoid floating-point precision errors:

```python theme={null}
# Good - String format
payout_data = {
    "amount": "100.50",
    "currency": "USD"
}

# Bad - Float (can cause precision errors)
payout_data = {
    "amount": 100.5,  # ❌ May cause rounding errors
    "currency": "USD"
}
```

## Multi-Currency Accounts

Accounts can hold balances in multiple currencies simultaneously:

```python theme={null}
def get_balance_by_currency(account, currency):
    """Get balance for specific currency"""
    for balance in account["balances"]:
        if balance["currency"] == currency:
            return balance
    return None

# Usage
account = get_account("acc_123")
usd_balance = get_balance_by_currency(account, "USD")
eur_balance = get_balance_by_currency(account, "EUR")
```

## Currency Conversion (FX)

Use the FX endpoints for currency conversion:

```python theme={null}
# 1. Create a quote
quote = create_fx_quote(
    account_id="acct_123",
    source_currency="USD",
    target_currency="EUR",
    amount="1000.00",
    amount_type="source"
)

# 2. Review the rate
print(f"Rate: {quote['all_in_rate']}")
print(f"You'll receive: {quote['target_amount']} EUR")

# 3. Execute before expiration
trade = execute_fx_quote(account_id="acct_123", quote_id=quote['id'])
```

## Currency Matching

Always ensure currency matches across related operations:

### Payout Destinations

```python theme={null}
# Payout destination currency must match payout currency
destination = create_payout_destination(
    beneficiary_id="bene_123",
    currency="USD",  # Destination currency
    account_number="..."
)

# Later, payout must use same currency
payout = create_payout(
    beneficiary_id="bene_123",
    payout_destination_id=destination["id"],
    amount="100.00",
    currency="USD"  # Must match destination
)
```

### Virtual Accounts

Each virtual account supports one currency:

```python theme={null}
# Create separate virtual accounts for each currency
va_usd = create_virtual_account(
    account_id="acc_123",
    currency="USD",
    label="USD Collections"
)

va_eur = create_virtual_account(
    account_id="acc_123",
    currency="EUR",
    label="EUR Collections"
)
```

## Balance Checks

Always check sufficient balance before creating payouts:

```python theme={null}
def can_create_payout(account_id, currency, amount):
    """Check if account has sufficient balance"""
    account = get_account(account_id)
    balance = get_balance_by_currency(account, currency)

    if not balance:
        return False, f"No {currency} balance"

    available = Decimal(balance["available_balance"])
    required = Decimal(amount)

    if available < required:
        return False, f"Insufficient funds: {available} < {required}"

    return True, "Sufficient balance"

# Usage
can_pay, message = can_create_payout("acc_123", "USD", "100.00")
if not can_pay:
    print(f"Cannot create payout: {message}")
```

## Currency Display

Format currencies correctly for display:

```python theme={null}
def format_currency(amount, currency):
    """Format amount with proper currency symbol and precision"""
    amount_decimal = Decimal(amount)

    # Currency symbols
    symbols = {
        "USD": "$",
        "EUR": "€",
        "GBP": "£",
        "JPY": "¥"
    }

    # Precision by currency
    if currency in ["JPY", "KRW"]:
        # Zero-decimal currencies
        return f"{symbols.get(currency, currency)} {amount_decimal:,.0f}"
    else:
        # Standard 2-decimal currencies
        return f"{symbols.get(currency, currency)} {amount_decimal:,.2f}"

# Usage
print(format_currency("1000.50", "USD"))  # $ 1,000.50
print(format_currency("10000", "JPY"))     # ¥ 10,000
```

## Common Pitfalls

### 1. Floating Point Arithmetic

❌ **Never** use float for money calculations:

```python theme={null}
# Bad
total = 100.10 + 200.20  # May result in 300.2999999999

# Good
from decimal import Decimal
total = Decimal("100.10") + Decimal("200.20")  # Exactly 300.30
```

### 2. Currency Mismatch

❌ Don't create payouts with mismatched currencies:

```python theme={null}
# Bad - will fail
create_payout(
    beneficiary_id="bene_123",
    payout_destination_id="dest_usd",  # USD destination
    amount="100.00",
    currency="EUR"  # ❌ Currency mismatch
)
```

### 3. Ignoring Balance Currency

❌ Don't assume single currency:

```python theme={null}
# Bad - assumes single currency
balance = account["balances"][0]["available_balance"]

# Good - specify currency
usd_balance = get_balance_by_currency(account, "USD")
```

## Best Practices Summary

1. ✅ Always use string format for amounts
2. ✅ Use standard ISO 4217 currency codes
3. ✅ Check currency matches for related operations
4. ✅ Verify sufficient balance before payouts
5. ✅ Use Decimal for money calculations
6. ✅ Handle multi-currency accounts properly
7. ✅ Respect currency-specific decimal precision
8. ✅ Use FX endpoints for currency conversion

## Related Documentation

* [Create Payout](/fx/api-reference/transfers/payouts/create-payout) - Send money
* [Create FX Quote](/fx/api-reference/transfers/fx/create-fx-quote) - Convert currencies
* [Get Account Balances](/fx/api-reference/customers/accounts/get-balances) - Check balances