# 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, for the Goldback, or for one PCGS-numbered coin at one grade.
- You need to read a stack, scan or receipt 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.

## 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`

### Observed premiums over spot

Rolling fine-metal-weighted median asking premiums over spot, observed from real marketplace listings rather than quoted by a dealer.

- `/api/metal-premiums.md` — Observed premiums over spot, as markdown

Example: `GET https://www.stackerscan.com/api/metal-premiums.md?metal=silver`

### Historical price series

Daily historical series for charting — one metal, the Goldback, or one PCGS-numbered coin at one grade.

- `/api/metal-price-charts` — Historical price series for one metal
- `/api/goldback-price-charts` — Historical Goldback price series
- `/api/pcgs-price-charts` — PCGS price-guide history for one coin and grade

Example: `GET https://www.stackerscan.com/api/metal-price-charts?metal=gold&days=30&currency=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 BTC and the metal codes.

- `/api/currencies` — List supported currencies
- `/api/currencies.md` — Supported currencies, as markdown

Example: `GET https://www.stackerscan.com/api/currencies`

### Community activity counts

Aggregate counts of community activity over a trailing window. Aggregates only — no individual account is identifiable from them.

- `/api/community/counts` — Aggregate community activity counts

Example: `GET https://www.stackerscan.com/api/community/counts?days=30`

### Shared stacks and scans

Read access to a stack, scan, receipt or image a StackerScan user published behind a share token. The token in the path is the whole authorization.

- `/api/public/share/{token}` — Read a shared scan
- `/api/public/share/{token}/receipt` — Read a shared scan's receipt
- `/api/public/share/{token}/image/{imageId}` — Read one image from a shared scan
- `/api/public/share/stack/{token}` — Read a shared stack
- `/api/public/share/stack/{token}/gallery` — List a shared stack's images
- `/api/public/share/stack/{token}/image/{imageId}` — Read one image from a shared stack

Example, with the braced segment replaced by a real token: `GET https://www.stackerscan.com/api/public/share/stack/{token}`

### Product guide and liveness

A step-by-step guide to what the product does, and a liveness probe for callers that monitor it.

- `/api/how-to-use.md` — Product guide, as markdown
- `/api/health` — Liveness check

Example: `GET https://www.stackerscan.com/api/how-to-use.md`

- [OpenAPI 3.1 document](https://www.stackerscan.com/openapi.json)

## 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 share endpoints take a token in the path, which is a capability URL rather than a credential: possession of the link is the whole of the authorization, exactly as it is for the browser link the user shared.

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](https://www.stackerscan.com/openapi.json)
- [Supported currencies](https://www.stackerscan.com/api/currencies)
- [llms.txt index](https://www.stackerscan.com/llms.txt)

## 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.

| Code | Title | HTTP | `type` URL |
| --- | --- | --- | --- |
| `invalid-parameter` | Invalid parameter | 400 | https://www.stackerscan.com/errors/invalid-parameter |
| `missing-parameter` | Missing parameter | 400 | https://www.stackerscan.com/errors/missing-parameter |
| `unauthorized` | Unauthorized | 401 | https://www.stackerscan.com/errors/unauthorized |
| `not-found` | Not found | 404 | https://www.stackerscan.com/errors/not-found |
| `rate-limited` | Rate limited | 429 | https://www.stackerscan.com/errors/rate-limited |
| `upstream-unavailable` | Upstream unavailable | 502 | https://www.stackerscan.com/errors/upstream-unavailable |
| `internal-error` | Internal error | 500 | https://www.stackerscan.com/errors/internal-error |

- [Error code index](https://www.stackerscan.com/errors)

## 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 or coin scan costs 10 credits; one imported spreadsheet row costs 2.

- 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.

| Offer | Price | Includes |
| --- | --- | --- |
| Free Trial | $0.00 | 20 credits: up to 2 receipt scans, 20 items, or 10 spreadsheet rows |
| Starter | $2.00 | 80 credits: up to 8 receipt scans, 80 items, or 40 spreadsheet rows |
| Pro | $8.00 | 400 credits: up to 40 receipt scans, 400 items, or 200 spreadsheet rows |

- [Pricing, as markdown](https://www.stackerscan.com/pricing.md)
- [Pricing page](https://www.stackerscan.com/pricing)