Currency Sources

Guide to exchange rate providers for fiat-to-satoshi conversion.

Overview

The plugin converts fiat prices (USD, EUR, etc.) to Bitcoin satoshis using exchange rate APIs.

Available Sources

1. CoinGecko (Default)

Best for: Most merchants

Property	Value
API Key Required	No
Rate Limit	10-50 requests/minute
Update Frequency	5 minutes (cached)
Currencies	50+
Cost	Free

Configuration:

{
  currencySource: "coingecko"
}

Pros:

• No setup required
• Wide currency support
• Reliable

Cons:

• Rate limits on high traffic
• Slightly delayed rates

---

2. Kraken

Best for: High-volume stores

Property	Value
API Key Required	Optional
Rate Limit	15 requests/minute
Update Frequency	5 minutes (cached)
Currencies	20+
Cost	Free (higher limits with key)

Configuration:

{
  currencySource: "kraken"
}

Pros:

• More accurate rates
• Professional exchange
• Higher limits with API key

Cons:

• Fewer currencies
• API key recommended for production

---

3. Fixed Rate

Best for: Stable pricing

Property	Value
API Key Required	No
Rate Limit	None
Update Frequency	Manual
Currencies	1 (set by you)
Cost	Free

Configuration:

{
  currencySource: "fixed",
  fixedBtcRate: 65000  // 1 BTC = 65,000 USD
}

Pros:

• Predictable pricing
• No API calls
• Stable for customers

Cons:

• Manual updates needed
• Can become outdated

Use Cases:

• Products with fixed BTC prices
• Promotional pricing
• Stablecoins integration

---

4. Manual

Best for: Direct satoshi pricing

Property	Value
API Key Required	No
Rate Limit	None
Update Frequency	N/A
Currencies	N/A
Cost	Free

Configuration:

{
  currencySource: "manual"
}

How it works:

• Enter prices directly in satoshis
• No conversion needed
• Customer sees sats amount

Use Cases:

• Bitcoin-native stores
• Micropayments
• Fixed sats pricing

---

Comparison Table

Feature	CoinGecko	Kraken	Fixed	Manual
Setup Required	No	Optional	Yes	No
Real-time Rates	Yes	Yes	No	N/A
Cost	Free	Free	Free	Free
Accuracy	Good	Best	Manual	Exact
Maintenance	None	None	High	None
Best For	Most	High-volume	Stable	BTC-native

---

Caching

All sources use a 5-minute cache:

// Cache behavior
- First request: Fetches from API
- Next 5 minutes: Uses cached rate
- After 5 minutes: Fetches fresh rate

Clear Cache

Programmatically clear the cache:

// In your custom code
currencyService.clearCache()

Check Cache Status

const status = currencyService.getCacheStatus()
// { "usd": { rate: 66165, age: 120000 } }

---

Error Handling

API Errors

If the exchange rate API fails:

1. CoinGecko down

   • Falls back to cache (if available)
   • Throws error if no cache

2. Kraken down

   • Falls back to cache
   • Throws error if no cache

3. Fixed rate

   • No API calls
   • Always succeeds

Rate Limiting

Source	Limit	Handling
CoinGecko	10-50/min	Caching reduces calls
Kraken	15/min	Caching reduces calls
Fixed	None	No API calls
Manual	None	No API calls

---

Best Practices

Production

1. Use CoinGecko or Kraken

   • Reliable, well-maintained
   • Good for most stores

2. Enable caching

   • Default 5-minute cache is good
   • Reduces API calls

3. Monitor usage

   • Check logs for API errors
   • Consider Kraken API key for high traffic

High Traffic

1. Consider Kraken with API key

   • Higher rate limits
   • More accurate

2. Increase cache TTL

   • Modify CACHE_TTL in utils.ts
   • Trade freshness for reliability

3. Use fixed rate as fallback

   • Set during high-traffic events
   • Prevents API failures

---

Custom Sources

Need a different exchange? The architecture supports adding new sources:

1. Edit src/modules/clink/utils.ts
2. Add new case in getRate() method
3. Implement fetch logic
4. Add tests

---

Next Steps

• Configuration - All options
• Troubleshooting - Common issues
• Contributing - Add new sources