Skip to main content

​
Overview

The Currencies API allows you to manage available currencies in your Firefly III instance. You can create custom currencies, enable/disable them, and set your default currency.

​
List All Currencies

curl -X GET "https://demo.firefly-iii.org/api/v1/currencies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/currencies

​
Query Parameters

​
page
integer
Page number for pagination

​
Response Fields

​
id
integer
Currency ID
​
created_at
string
ISO 8601 timestamp of creation
​
updated_at
string
ISO 8601 timestamp of last update
​
native
boolean
Whether this is the user group’s native/default currency
​
default
boolean
Alias for native (same value)
​
primary
boolean
Alias for native (same value)
​
enabled
boolean
Whether the currency is enabled for use
​
name
string
Currency name (e.g., “US Dollar”)
​
code
string
ISO 4217 currency code (e.g., “USD”)
​
symbol
string
Currency symbol (e.g., ”$”)
​
decimal_places
integer
Number of decimal places for this currency

​
Create Currency

curl -X POST "https://demo.firefly-iii.org/api/v1/currencies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bitcoin",
    "code": "BTC",
    "symbol": "₿",
    "decimal_places": 8,
    "enabled": true,
    "default": false
  }'
Endpoint: POST /v1/currencies

​
Request Body

​
name
string
required
Currency name (1-255 characters, must be unique)
​
code
string
required
Currency code (3-32 characters, must be unique)
​
symbol
string
required
Currency symbol (1-32 characters, must be unique)
​
decimal_places
integer
default:"2"
Number of decimal places (0-12)
​
enabled
boolean
default:"true"
Whether the currency is enabled
​
default
boolean
default:"false"
Set as default currency for the user group
Firefly III comes with most world currencies pre-installed. You typically only need to create custom currencies for:
  • Cryptocurrencies
  • Loyalty points
  • Virtual currencies
  • Historical or discontinued currencies

​
Get Currency by Code

curl -X GET "https://demo.firefly-iii.org/api/v1/currencies/USD" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/currencies/{currency_code} Returns the same response fields as the List endpoint.

​
Get Primary Currency

curl -X GET "https://demo.firefly-iii.org/api/v1/currencies/primary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/currencies/primary Returns the user group’s primary/default currency. Alias: GET /v1/currencies/default

​
Update Currency

curl -X PUT "https://demo.firefly-iii.org/api/v1/currencies/BTC" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bitcoin (Updated)",
    "enabled": true
  }'
Endpoint: PUT /v1/currencies/{currency_code} Accepts the same parameters as Create Currency. All fields are optional.
You can also use PUT /v1/currencies without a code parameter to update multiple currency properties.

​
Delete Currency

curl -X DELETE "https://demo.firefly-iii.org/api/v1/currencies/BTC" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: DELETE /v1/currencies/{currency_code} Deletes the currency if it’s not in use.
You cannot delete a currency that is:
  • Used by any accounts
  • Used by any transactions
  • Set as the default currency
  • A system currency

​
Enable Currency

curl -X POST "https://demo.firefly-iii.org/api/v1/currencies/EUR/enable" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: POST /v1/currencies/{currency_code}/enable Enables the currency for use in accounts and transactions.

​
Disable Currency

curl -X POST "https://demo.firefly-iii.org/api/v1/currencies/EUR/disable" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: POST /v1/currencies/{currency_code}/disable Disables the currency (it will no longer appear in dropdowns).
You cannot disable a currency that is currently set as the default/primary currency.

​
Set Primary Currency

curl -X POST "https://demo.firefly-iii.org/api/v1/currencies/EUR/primary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: POST /v1/currencies/{currency_code}/primary Sets this currency as the primary/default currency for your user group.

​
Get Currency Accounts

curl -X GET "https://demo.firefly-iii.org/api/v1/currencies/USD/accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Endpoint: GET /v1/currencies/{currency_code}/accounts Returns all accounts using this currency.

​
Get Currency Available Budgets

Endpoint: GET /v1/currencies/{currency_code}/available-budgets Returns available budgets using this currency.

​
Get Currency Bills

Endpoint: GET /v1/currencies/{currency_code}/bills Returns all bills using this currency.

​
Get Currency Budget Limits

Endpoint: GET /v1/currencies/{currency_code}/budget-limits Returns all budget limits using this currency.

​
Get Currency Exchange Rates

Endpoint: GET /v1/currencies/{currency_code}/cer Returns currency exchange rates for this currency.

​
Get Currency Recurrences

Endpoint: GET /v1/currencies/{currency_code}/recurrences Returns recurring transactions using this currency.

​
Get Currency Rules

Endpoint: GET /v1/currencies/{currency_code}/rules Returns rules that reference this currency.

​
Get Currency Transactions

Endpoint: GET /v1/currencies/{currency_code}/transactions Returns all transactions using this currency.

​
Query Parameters

​
page
integer
Page number for pagination
​
start
string
Start date (YYYY-MM-DD)
​
end
string
End date (YYYY-MM-DD)
​
type
string
Transaction type filter

​
Currency Exchange Rates

Firefly III also provides exchange rate management through the /v1/exchange-rates endpoints:

​
List Exchange Rates

Endpoint: GET /v1/exchange-rates Returns all configured exchange rates.

​
Get Exchange Rate

Endpoint: GET /v1/exchange-rates/{fromCurrencyCode}/{toCurrencyCode} Returns the exchange rate between two currencies.

​
Get Exchange Rate by Date

Endpoint: GET /v1/exchange-rates/{fromCurrencyCode}/{toCurrencyCode}/{date} Returns the exchange rate for a specific date.

​
Create Exchange Rate

Endpoint: POST /v1/exchange-rates Creates a new exchange rate entry.

​
Update Exchange Rate

Endpoint: PUT /v1/exchange-rates/{userGroupExchangeRate} Updates an existing exchange rate.

​
Delete Exchange Rate

Endpoint: DELETE /v1/exchange-rates/{fromCurrencyCode}/{toCurrencyCode} Deletes all exchange rates between two currencies.

​
Best Practices

​
Currency Setup

  1. Set your primary currency first: This should be your main operating currency
  2. Enable only needed currencies: Keep the list manageable
  3. Use standard codes: Stick to ISO 4217 codes when possible
  4. Configure exchange rates: Set up rates for currencies you use regularly

​
Multi-Currency Management

When to use multiple currencies:
  • International transactions
  • Foreign bank accounts
  • Investment accounts in different currencies
  • Cryptocurrency holdings
  • Travel expenses
Best practices:
  • Keep exchange rates updated
  • Use the primary currency for reporting
  • Enable auto-conversion for better insights
  • Track foreign transaction fees separately

​
Decimal Places

Choose appropriate decimal places:
  • Fiat currencies: Usually 2 (USD, EUR, GBP)
  • Some currencies: 0 (JPY, KRW)
  • Cryptocurrencies: 8 (BTC, ETH)
  • Precious metals: 4 (Gold, Silver ounces)
  • Loyalty points: 0

​
Common Currency Codes

Major Fiat:
  • USD - US Dollar
  • EUR - Euro
  • GBP - British Pound
  • JPY - Japanese Yen
  • CNY - Chinese Yuan
  • INR - Indian Rupee
Cryptocurrencies:
  • BTC - Bitcoin (8 decimals)
  • ETH - Ethereum (8 decimals)
  • USDT - Tether (2 decimals)
Commodities:
  • XAU - Gold (troy ounce)
  • XAG - Silver (troy ounce)