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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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:

```typescript
// 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:

```typescript
// In your custom code
currencyService.clearCache()
```

### Check Cache Status

```typescript
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](Configuration.md) - All options
- [Troubleshooting](Troubleshooting.md) - Common issues
- [Contributing](Contributing.md) - Add new sources