​

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.