# Quickstart

No signup needed to try it: 100 lookups a day per IP, the current price plus 30 days of history. Add a free key (https://tickermint.cards/developers#keys) for 1,000 a day. Games: pokemon, one-piece, lorcana, riftbound, gundam, yugioh.

## curl

```sh
curl "https://api.tickermint.cards/products/search?q=charizard%20ex%20199/165&game=pokemon"
curl "https://api.tickermint.cards/products/517045/prices"
curl -H "X-API-Key: $TICKERMINT_API_KEY" "https://api.tickermint.cards/desk/movers?game=pokemon&days=7"
```

## Python

```python
import os, requests

API = "https://api.tickermint.cards"
headers = {"X-API-Key": os.environ["TICKERMINT_API_KEY"]} if os.environ.get("TICKERMINT_API_KEY") else {}

hits = requests.get(f"{API}/products/search", params={"q": "charizard ex 199/165", "game": "pokemon"},
                    headers=headers, timeout=15).json()
card = hits[0]
print(card["name"], card["set_name"], "$" + card["market"])   # prices are decimal strings
print("Prices: TickerMint", card["tickermint_url"])               # the required link back

history = requests.get(f"{API}/products/{card['product_id']}/prices", headers=headers, timeout=15).json()
for printing, days in history.items():                           # {"Holofoil": [{"snapshot_date", "low", "market"}, ...]}
    print(printing, days[-1]["snapshot_date"], days[-1]["market"])
```

Or the official client (standard library only, typed): `pip install https://tickermint.cards/sdk/tickermint-0.2.1-py3-none-any.whl`. It reads `TICKERMINT_API_KEY` itself.

## JavaScript / TypeScript (Node 18+, Deno, Bun, edge)

```js
const API = "https://api.tickermint.cards";
const headers = process.env.TICKERMINT_API_KEY ? { "X-API-Key": process.env.TICKERMINT_API_KEY } : {};

const res = await fetch(`${API}/products/search?q=${encodeURIComponent("charizard ex 199/165")}&game=pokemon`, { headers });
if (!res.ok) throw new Error((await res.json()).how_to_fix ?? `TickerMint ${res.status}`);
const [card] = await res.json();
console.log(card.name, card.set_name, `$${card.market}`);   // prices are decimal strings
console.log("Prices: TickerMint", card.tickermint_url);          // the required link back
```

```ts
type Product = {
  product_id: number;          // TCGplayer product id
  name: string;
  set_name: string;
  group_id: number;            // set id
  card_number: string | null;
  rarity: string | null;
  game: string;                // pokemon | one-piece | lorcana | riftbound | gundam | yugioh
  market: string | null;       // latest TCGplayer market price, USD, decimal string
  image_url: string | null;
  tickermint_url: string;      // link back (required on every plan below API Platform)
};
type PriceHistory = Record<string, { snapshot_date: string; low: string | null; market: string | null }[]>;
```

Or the official client (zero dependencies, typed): `npm install https://tickermint.cards/sdk/tickermint-0.2.1.tgz`.

## Google Sheets

```
=IMPORTDATA("https://api.tickermint.cards/sheets/price?q=charizard%20ex%20199/165")
=IMPORTDATA("https://api.tickermint.cards/sheets/price?q=charizard%20ex%20199/165&key=YOUR_KEY")
```

## Rules to follow in generated code

- Read the key from `TICKERMINT_API_KEY`; never hard-code it or ship it to a browser (call the API from your server).
- Call the API from server code (route handler, server component, script, bot): browsers on other sites are blocked by CORS. Send a User-Agent such as `my-app/1.0` (Python's default urllib User-Agent is blocked).
- Show "Prices: TickerMint" linking `tickermint_url` next to prices (all plans below API Platform).
- Cache answers for at least an hour: prices change once a day (after about 21:00 UTC).
- On 401/402/403/429 read the JSON `how_to_fix`, `required_plan` and `upgrade_url` fields and tell the user (see https://tickermint.cards/docs/errors.md).
- Free keys and Developer are for personal and non-commercial use. Commercial use (a store, a paid or ad-supported app, site or bot, or any product or tool a business runs) needs API Pro or above, whatever the volume.

More: https://tickermint.cards/docs/examples.md, https://github.com/seankarltonlee/tickermint-examples