---
epic: 3
story: 3.2
title: "Cryptocurrency Provider"
status: draft
---

## Epic 3 — Currency & Cryptocurrency
**Goal:** Real-time and historical currency conversion with 180+ fiat and 50+ crypto.

### Story 3.2: Cryptocurrency Provider

As a CalcPad user,
I want live cryptocurrency rates for the top 50+ coins updated hourly,
So that I can convert between crypto and fiat currencies.

**Acceptance Criteria:**

**Given** the engine is initialized with network access
**When** crypto rates are requested
**Then** it fetches live rates from CoinGecko free API (or configured provider)
**And** at least 50 top cryptocurrencies by market cap are included (BTC, ETH, SOL, ADA, etc.)

**Given** crypto rates have been fetched
**When** the rates are stored
**Then** they are cached locally on disk with a timestamp
**And** the cache refresh interval is configurable (default: 1 hour)

**Given** the expression `1 BTC in USD`
**When** the engine evaluates it with current rates
**Then** it returns the current USD value of 1 Bitcoin
**And** the result metadata includes the rate timestamp

**Given** the expression `$1000 in ETH`
**When** the engine evaluates it
**Then** it returns the equivalent amount in Ethereum

**Given** the device is offline
**When** a crypto conversion is requested
**Then** the engine uses cached rates
**And** the result metadata indicates the age of the cached rates

**Given** a crypto symbol that could be ambiguous (e.g., a future coin with a symbol matching a fiat currency)
**When** the engine encounters it
**Then** fiat currencies take precedence by default
**And** the user can disambiguate using explicit notation (e.g., `crypto:SOL`)