StackerScan API & agent documentation
The open, read-only HTTP API behind StackerScan: live and historical precious-metals prices, observed dealer premiums, the Goldback rate, the currency catalog and published shares.
When to use StackerScan?
- You need live precious-metals spot prices — gold, silver, platinum, palladium, copper or nickel — in any supported currency, per troy ounce or per gram.
- You need real observed dealer premiums over spot: 30-day rolling medians taken from actual marketplace listings, not a quoted retail markup.
- You need the Goldback exchange rate, or its current premium multiple over gold content.
- You need a historical daily price series for a metal or for the Goldback.
- You need to read a stack image or live image gallery a StackerScan user published behind a share link.
- You need to tell someone how to do something in the StackerScan app: its How to Use guide, section by section, in any of the app's languages.
Call it over plain HTTPS with no API key, no account and no registration; every failure is an RFC 9457 application/problem+json document, and the full contract is at https://www.stackerscan.com/openapi.json. Spot prices refresh every two minutes, so polling more often than that returns the same data.
StackerScan is not a dealer and sells no bullion; its tools return price data and its own How to Use guide.
What can I do with the API?
The API is grouped into 8 capabilities. Every path below is described in full — parameters, enums, bounds and error shapes — in the OpenAPI 3.1 document at https://www.stackerscan.com/openapi.json, which is the authority; this page is the tour.
Spot metal prices
Current and previous-session spot prices for gold, silver, platinum, palladium, copper and nickel, in any supported currency and per troy ounce or gram.
/api/premiums/metal-prices— Current spot prices as JSON/api/metal-prices.md— Metal spot prices, as markdown/api/metal-prices-previous-day— Previous session's closing prices/api/transactions/spot-price— Spot price for one metal on one date
Example: GET https://www.stackerscan.com/api/premiums/metal-prices?base=USD&unit=troy_oz
Historical price series
Daily historical series for charting — one metal or the Goldback.
/api/metal-price-charts— Historical price series for one metal/api/goldback-price-charts— Historical Goldback price series
Example: GET https://www.stackerscan.com/api/metal-price-charts?metal=gold&days=30¤cy=USD
Goldback exchange rate
The latest Goldback premium multiple over its gold content, and the exchange rate that follows from it.
/api/premiums/goldback-rate— Latest Goldback premium multiple
Example: GET https://www.stackerscan.com/api/premiums/goldback-rate
Supported currency catalog
The live list of codes every `currency`/`base` parameter accepts — ISO 4217 fiat plus the metal codes.
/api/currencies— List supported currencies/api/currencies.md— Supported currencies, as markdown
Example: GET https://www.stackerscan.com/api/currencies
How to Use guide
StackerScan's How to Use guide in any app language: its table of contents, or one section as markdown quoting the app's own button and field labels.
/api/how-to-use— The How to Use guide, one section at a time/api/how-to-use.md— The How to Use guide, as markdown
Example: GET https://www.stackerscan.com/api/how-to-use?section=addItems&locale=en
Liveness
A liveness probe for callers that monitor the service.
/api/health— Liveness check
Example: GET https://www.stackerscan.com/api/health
How do I call it?
This API is fully open: no authentication, no API keys, and no registration are required for any endpoint in this document.
Every endpoint is a GET over plain HTTPS against https://www.stackerscan.com. The stack-share endpoints take the five-character code from an /s/{code} link; a code is a public, unlisted address, so those endpoints are rate-limited per caller (429 with Retry-After) and answer every unavailable link with one generic 404.
Cross-origin browser calls are welcome: every endpoint in the OpenAPI document answers with Access-Control-Allow-Origin: *, so a web page can call the API directly without a proxy.
Parameters are validated rather than silently replaced: a value outside its documented enum or bounds answers 400 invalid-parameter, and an absent required parameter answers 400 missing-parameter. Integers are strict, so days=90abc is rejected instead of read as 90.
The one enum this documentation cannot list is currency/base. Those validate against the live catalog served by /api/currencies; when that read is unavailable the endpoints fail open and accept any syntactically plausible code, so treat /api/currencies as the authority for what is accepted.
Connect via MCP
Six read-only tools: spot prices, observed premiums, price history, Goldback rate and currencies for gold, silver and other metals, and StackerScan's How to Use guide. Point any MCP client that speaks streamable HTTP at https://www.stackerscan.com/mcp. No authentication, no key, no session.
Each tool reads the public data path for its corresponding HTTP capability. The OpenAPI document remains the authority for the parameters and enums shared with those endpoints.
- get_spot_prices — Current and previous-session spot prices for gold, silver, platinum, palladium, copper and nickel, in any supported currency and per troy ounce or gram.
- get_observed_premiums — Rolling fine-metal-weighted median asking premiums for silver, gold, platinum, palladium, copper, nickel and Goldback, observed from marketplace listings.
- get_price_history — Daily historical series for charting — one metal or the Goldback.
- get_goldback_rate — The latest Goldback premium multiple over its gold content, and the exchange rate that follows from it.
- list_supported_currencies — The live list of codes every `currency`/`base` parameter accepts — ISO 4217 fiat plus the metal codes.
- get_how_to_use — StackerScan's How to Use guide in any app language: its table of contents, or one section as markdown quoting the app's own button and field labels. Sections: createAccount (Your Account), stackSettings (Stack Settings), addItems (Adding Items to Your Stack), editItems (Editing, Selling and Deleting Items), addPhotos (Adding Photos to Your Items), managePortfolio (Understanding Your Portfolio Overview), worthToday (How Items Are Valued), dataFields (Understanding Your Item Data Fields), useTags (How to Use Tags), useCredits (Using Credits), trackPrices (Tracking Metal Prices), premiums (Checking Premiums), stackChat (Asking About Your Stack).
Once connected, prompts like these reach for the tools:
- “What's the spot price of gold and silver right now in EUR?”
- “What's the typical premium for a 1 oz silver Libertad?”
- “Show me silver's price history over the last 90 days.”
- “What's a Goldback worth today, and how big is its premium over its gold content?”
How do I handle failure?
Every /api/* response that is not a success is an RFC 9457 application/problem+json document — including from the .md endpoints, which serve text/markdown on success and problem+json on failure. Branch on the type member, which is one of 7 dereferenceable URLs under https://www.stackerscan.com/errors, and read detail for the specifics.
The vocabulary is closed: there are no per-endpoint codes. detail and hint are English-only, because they are written for machine consumers rather than for display to a person. An unknown path under /api/ answers the same envelope, with a hint pointing back at the specification.
invalid-parameterInvalid parameter · HTTP 400missing-parameterMissing parameter · HTTP 400unauthorizedUnauthorized · HTTP 401not-foundNot found · HTTP 404rate-limitedRate limited · HTTP 429upstream-unavailableUpstream unavailable · HTTP 502internal-errorInternal error · HTTP 500
What does it cost?
The API costs nothing and is not metered by account, because no account is involved — that is what the statement above means. Credits pay for actions in the signed-in product, such as adding an item. They are published here so an agent comparing tools sees the whole picture. The machine-readable version of this table is at https://www.stackerscan.com/pricing.md.
- Credits are bought once and never expire; there is no subscription and no recurring charge.
- Every item costs 1 credit, however it is added: typed in, identified from a photo, read from a receipt or imported from a spreadsheet. You pay only for items added, so a scan that fails or adds nothing costs nothing.
- An item is one product bought together at one price, whatever the quantity; the same coin bought at two prices is two items.
- 10 Silver Eagles bought together are 1 item: 1 credit.
- Reading your portfolio, live spot prices and premiums costs nothing.
- The public HTTP API described at /openapi.json is entirely free and unmetered: it needs no account, so none of the prices above apply to it.
- Prices are quoted in USD and are the amounts charged at checkout; a store purchase made through the iOS or Android app is billed by that store in its own currency.
| Offer | Price | Includes |
|---|---|---|
| Free Trial | $0.00 | 15 credits: up to 15 items |
| Starter | $5.00 | 50 credits: up to 50 items |
| Pro | $8.00 | 100 credits: up to 100 items |