StackerScan API & agent documentation

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, for the Goldback, or for one PCGS-numbered coin at one grade.
• You need to read a stack image or live image gallery a StackerScan user published behind a share link.

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.

Do not use StackerScan to buy or sell metal — it is not a dealer and sells no bullion — and do not expect a numismatic valuation for a coin you cannot supply a PCGS number for.

• Feature catalog — everything the product can do

What can I do with the API?

The API is grouped into 7 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.

• OpenAPI 3.1 document

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.

• OpenAPI 3.1 document
• Supported currencies
• llms.txt index

Connect via MCP

Five read-only tools: spot prices, observed premiums, price history, Goldback rate, and currencies. 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. Goldbacks use the Goldback reference rate instead of contained-gold spot and are excluded from ordinary gold statistics.
• get_price_history — Daily historical series for charting — one metal, the Goldback, or one PCGS-numbered coin at one grade.
• 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 BTC and the metal codes.

• MCP endpoint

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 400

missing-parameterMissing parameter · HTTP 400

unauthorizedUnauthorized · HTTP 401

not-foundNot found · HTTP 404

rate-limitedRate limited · HTTP 429

upstream-unavailableUpstream unavailable · HTTP 502

internal-errorInternal error · HTTP 500

• Error code index

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 price the AI-assisted parts of the product a person signs in for, and 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.

One receipt scan costs 5 credits, one coin photo scan costs 1 credit, and one imported spreadsheet row costs 1 credit.

• Credits are bought once and never expire; there is no subscription and no recurring charge.
• A scan that fails to process does not consume credits.
• Credits pay for AI-assisted entry only — receipt and coin scanning, photo identification and spreadsheet import. 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.

• Pricing, as markdown
• Pricing page