(cd "$(git rev-parse --show-toplevel)" && git apply --3way <<'EOF' diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..c6fe7c13799eaf27c9af65a939ebe0ab1839e49b --- /dev/null +++ b/README.md @@ -0,0 +1,52 @@ +# USTH Crypto App + +## Overview +USTH Crypto App is an Android application that visualises cryptocurrency market data powered by the public CoinGecko API. The app presents three primary screens: + +- Home – Displays a ranked list of cryptocurrencies with live pricing and short-term performance metrics. +- Overview – Shows a price chart and metadata for a selected coin, allowing users to switch the time range between 1 day, 7 days, and 30 days. +- Exchange – Lists the most active crypto exchanges and provides quick links to their official websites. + +## API Usage +The app relies on three CoinGecko REST endpoints. All requests are performed with the Volley networking library and parse JSON responses into local model classes. + +### 1. Market Listings +- Endpoint: GET /api/v3/coins/markets +- Purpose: Populate the Home screen with the top 100 cryptocurrencies ordered by market capitalisation. +- Key Query Parameters:

• • vs_currency=usd – Prices are returned in USD.
• • order=market_cap_desc – Sort by descending market cap.
• • per_page=100 and page=1 – Limit the response to the first 100 coins.
• • sparkline=false – Exclude historical sparkline data for lighter payloads.
• • price_change_percentage=1h,24h,7d – Include percentage changes for multiple windows. +- Client Usage: Parsed inside the Home fragment into CoinData objects storing rank, name, symbol, price, 1h change, icon URL, and a reusable coin ID.

+### 2. Historical Market Chart +- Endpoint: GET /api/v3/coins/{id}/market_chart +- Purpose: Fetch time-series price data for the Overview chart when users switch between 1D, 7D, and 30D views. +- Dynamic Path Parameter:

• • {id} – Coin identifier derived from the Home list selection (defaults to bitcoin). +- Key Query Parameters:
• • vs_currency=usd – Price series in USD.
• • days={1|7|30} – Number of trailing days requested, based on the selected filter. +- Client Usage: Cached in-memory per time range to avoid redundant network calls, then rendered as a LineChart. The fragment adapts colours based on price movement and updates the textual price/percentage summary dynamically.

+### 3. Exchange Directory +- Endpoint: GET /api/v3/exchanges +- Purpose: Supply the Exchange screen with 50 major trading venues, including location, 24h volume, and website link. +- Key Query Parameters:

• • per_page=50 – Limit to the top 50 exchanges.
• • page=1 – First page of results. +- Client Usage: Parsed into ExchangeData objects and displayed via ExchangeAdapter. Selecting a row opens the exchange URL in the browser.

+## Data Models +- CoinData – Immutable data holder for coin list entries. Includes helper setters/getters for rank, name, symbol, price, hourly percentage change, icon URL, and ID for further API calls. +- ExchangeData – Immutable data holder for exchange metadata: rank, name, country, 24h trading volume (BTC), website URL, and logo image URL. + +## Running the App +1. Open the project in Android Studio (Giraffe or newer recommended). +2. Allow Gradle to download dependencies. +3. Connect an Android device or start an emulator. +4. Press Run to install and launch the application. + +> Note: CoinGecko enforces rate limiting on their free API; avoid spamming filter buttons to prevent temporary blocks. EOF )