> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Precious metals integration

# Precious Metals Integration

This document outlines the new precious metals feature. Users can add holdings of Gold and Silver by specifying the quantity they own. The application automatically fetches current metal prices so the market value is tracked and included in daily snapshots and net worth calculations.

## API Options for Price Data

Below are a few APIs that can provide real-time or near real-time precious metals pricing.

### 1. MetalsAPI (metals-api.com)

* **Pros**
  * Free tier for basic usage with paid tiers for higher limits
  * Simple REST interface and supports multiple metals (Gold – `XAU`, Silver – `XAG`)
  * JSON responses and historical data available
* **Cons**
  * Rate limits on the free tier are fairly low
  * Requires an additional paid plan for minute-level updates

### 2. GoldAPI.io

* **Pros**
  * Offers spot prices for precious metals
  * Straightforward pricing and generous free tier
  * Provides multiple currency conversions
* **Cons**
  * Limited historical data compared to MetalsAPI
  * Smaller community and less documentation

### 3. AlphaVantage Commodities

* **Pros**
  * Unified with other AlphaVantage data sources (stocks, forex)
  * Free tier includes some commodity endpoints
* **Cons**
  * Data is updated daily rather than intraday
  * API responses are CSV-oriented and sometimes inconsistent

**Recommended Choice:** MetalsAPI provides a good balance between ease of use, pricing, and historical data support. It also has straightforward Node examples which makes it easy to integrate with our existing API routes.

## Data Model

`precious_metals` table

* `uuid` – primary key
* `clerk_id` – user identifier
* `metal` – `'gold'` or `'silver'`
* `quantity_oz` – number of ounces owned
* `cost_basis` – optional cost basis
* `notes` – optional text
* `is_active` – soft delete flag
* `created_at` / `updated_at`

## Price Fetching

The server side uses the `METALS_API_KEY` environment variable and fetches prices from MetalsAPI. A helper function `fetchMetalPrice(metal)` returns the current USD price per ounce for Gold (`XAU`) or Silver (`XAG`).

## Daily Snapshots

During the daily snapshot cron job the application

1. Queries all active records in `precious_metals` for the user.
2. Fetches the current price for each metal.
3. Multiplies quantity by price to derive market value.
4. Adds the total to assets, net worth, and market value in `daily_snapshots_summary`.

This keeps historical valuations aligned with other asset types in Silvia.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.