Cryptocurrency Exchange Rate Setup

Category	Overview

Description

Overview

The Currency Rates Import app now supports automatic import of cryptocurrency exchange rates from three major providers. This enables businesses to track cryptocurrency holdings, payments, and transactions with accurate, real-time exchange rates.

Supported Cryptocurrency Services

CoinGecko (Free)

• 19,000+ cryptocurrencies supported

• Free API access (no key required)

• Manual asset mapping required

• Built-in lookup for coin IDs

• Best for: Small to medium businesses

CoinMarketCap (Professional)

• Professional-grade crypto data

• API key required (free tier available)

• Automatic currency code mapping

• No manual setup for standard coins

• Best for: Professional crypto trading

CryptoCompare (Flexible)

• Real-time cryptocurrency data

• API key optional (free tier)

• Automatic currency code mapping

• Enhanced features with API key

• Best for: General cryptocurrency tracking

Setup Process

1. Mark Currencies as Cryptocurrency

Before configuring crypto exchange services, you must mark which currencies in Business Central are cryptocurrencies:

1. Open Currencies page

2. Select or create a currency (e.g., BTC, ETH, LTC)

3. Check the "Crypto Currency" field

   

2. Configure Exchange Rate Service

1. Run Assisted Setup > Currencies Exchange Rate Services Setup

2. Select desired cryptocurrency service:

   • CoinGecko (Crypto)

   • CoinMarketCap (Crypto)

   • CryptoCompare (Crypto)

3. Complete the wizard

4. On the service card, configure:

   • Interface Type: Select crypto service

   • Currency Filter: Optionally filter specific cryptos (e.g., BTC|ETH)

   • PassKey (CoinMarketCap only): Enter API key

5. Set the base fiat currency for rate conversion (see Base Fiat Currency section below). By default this is your General Ledger LCY — no action needed unless you want a different base.

3. Service-Specific Setup

CoinGecko Setup

CoinGecko requires manual mapping because it uses full coin names (e.g., "bitcoin" for BTC):

1. On CoinGecko service card, click "Crypto Asset Mapping"

2. Create new mapping entries:

   • Service Code: Auto-filled

   • BC Currency Code: Your BC currency (e.g., BTC)

   • Provider Asset ID: Click lookup arrow to browse CoinGecko coins

   • Description: Optional description

   • Enabled: Check to activate

3. Using the Coin Lookup:

   • Click the dropdown arrow on Provider Asset ID field

   • System fetches all coins from CoinGecko (19,000+)

   • Search or browse for your cryptocurrency

   • Select coin (e.g., "Bitcoin (BTC)" → "bitcoin")

   • Value auto-fills in the field

     

Common CoinGecko Mappings:

BC Currency	Provider Asset ID	Description
BTC	bitcoin	Bitcoin
ETH	ethereum	Ethereum
USDT	tether	Tether
BNB	binancecoin	BNB
XRP	ripple	XRP
ADA	cardano	Cardano
SOL	solana	Solana
DOT	polkadot	Polkadot
LTC	litecoin	Litecoin
BCH	bitcoin-cash	Bitcoin Cash

CoinMarketCap Setup

1. Obtain API key from https://coinmarketcap.com/api/

2. On service card, enter API key in PassKey field

3. No manual mapping required - uses currency codes directly

   • BTC automatically maps to BTC

   • ETH automatically maps to ETH

   • Works for all standard cryptocurrency symbols

CryptoCompare Setup

1. Optional: Obtain API key from https://www.cryptocompare.com/

2. If using API key, enter in PassKey field

3. No manual mapping required - uses currency codes directly

   • BTC automatically maps to BTC

   • ETH automatically maps to ETH

   • Free tier works without API key

Configuration Options

Base Fiat Currency

The base fiat currency for crypto rate conversion is configured via the service's Data Exchange Definition, not on the service card itself. The same setting drives two things at once:

• The rate values fetched from the provider are quoted in this currency (e.g., CoinGecko receives ?vs_currencies=USD).

• The imported Currency Exchange Rate records get this code in their Relational Currency Code field.

This guarantees the stored rates and their relational currency are always consistent.

How to change the base fiat currency

1. Open the Currency Exchange Rate Service card for your crypto service.

2. Open the linked Data Exchange Definition (via Navigation → Data Exch. Def. or the related action).

3. Drill into the Line Definitions → Field Mapping for line CURREXCHANGE.

4. Locate the Relational Currency Code row.

5. Set its Default Value to the desired ISO currency code (e.g., USD, GBP, EUR).

Fallback behavior

If the Default Value is blank, or references a currency that does not exist in the Currencies list, the system falls back in this order:

1. General Ledger Setup → LCY Code is used.

2. If LCY is also blank, EUR is used as the final fallback.

The Default Value must reference an existing entry in the Currencies list. If you enter a code that doesn't exist (typo or unregistered currency), the system silently falls back to LCY for the URL request — but BC's standard Data Exchange engine will still try to store the invalid code on the imported rate, which then fails its foreign-key check during import. Always pick a currency that already exists.

For most companies, leaving the Default Value blank is correct — rates will be denominated in your LCY, which matches how all other rate providers (ECB, Open Exchange Rates, etc.) behave.

Exchange rates are imported as: 1 Crypto = X Base Fiat Currency

Currency Filter

Use filters to limit which cryptocurrencies to import:

• Empty: Import all mapped/marked cryptos

• BTC: Import only Bitcoin

• BTC|ETH: Import Bitcoin and Ethereum

• BTC..ETH: Import range of currencies

Testing the Setup

1. On Currency Exchange Rate Service card, click "Preview"

2. System fetches current rates from the crypto service

3. Review the exchange rates before importing

4. If rates look correct, proceed with import

Importing Cryptocurrency Rates

Manual Import

1. Open Currencies page

2. Click "Update Exchange Rates"

3. Select the crypto service

4. Rates are imported and applied

Automatic Import

1. On service card, click "Job Queue Entry"

2. Set frequency (hourly, daily, etc.)

3. Set start date/time

4. Enable the job queue entry

Crypto markets operate 24/7. Consider setting up more frequent updates (hourly or every 4 hours) compared to fiat currency updates.

Troubleshooting

"No crypto asset mappings configured" Error

Service: CoinGecko only

Solution: You must create asset mappings for CoinGecko:

1. Go to service card

2. Click "Crypto Asset Mapping"

3. Add mappings using the lookup feature

Empty Result Set

Possible causes:

1. No currencies marked as "Crypto Currency"

2. Currency Filter excludes all crypto currencies

3. API key missing (CoinMarketCap)

4. Network/connectivity issues

Solution:

1. Check currencies are marked as crypto

2. Review currency filter

3. Verify API key if required

4. Test internet connectivity

Rate Not Updating

Possible causes:

1. Mapping disabled in CoinGecko

2. Currency not supported by service

3. API rate limits exceeded

Solution:

1. Check "Enabled" flag in mappings

2. Verify currency exists on the service website

3. Consider upgrading API plan if hitting limits

Best Practices

1. Use Multiple Services: Configure multiple crypto services for redundancy

2. Regular Updates: Set up automatic updates for 24/7 crypto markets

3. Filter Appropriately: Only import cryptos you actively use

4. Monitor API Limits: Track usage if using free API tiers

5. Validate Rates: Always preview before first import

6. Document Mappings: Keep track of which service provides which crypto

7. Backup Configuration: Export/document your mappings

Supported Cryptocurrencies

The number of supported cryptocurrencies depends on the service:

• CoinGecko: 19,000+ coins (any with CoinGecko ID)

• CoinMarketCap: 9,000+ coins (standard symbols)

• CryptoCompare: 6,000+ coins (standard symbols)

All major cryptocurrencies (Bitcoin, Ethereum, Litecoin, XRP, etc.) are supported by all three services.