Usare l'API di PkmnPrices con Claude Code, Cursor e Codex

Gli strumenti di programmazione con l'AI scrivono integrazioni in fretta quando possono leggere la tua API. Indica a Claude Code, Cursor o Codex gli URL della documentazione di PkmnPrices e sapranno collegare la ricerca delle carte e i prezzi di mercato aggiornati senza che tu debba guidarli endpoint per endpoint.

Questa guida mostra le due risorse leggibili dall'AI che pubblichiamo, come collegarle in ciascuno strumento e la stessa ricerca in entrambi gli SDK ufficiali: Python (pkmnprices) e TypeScript (@pkmnprices/sdk).

Cosa imparerai

• Quando usare /llm.md e quando /openapi.json
• Come dare il contesto dell'API a Claude Code, Cursor e Codex
• Lo schema «prima l'elenco, poi il dettaglio» per i prezzi, comune a entrambi gli SDK
• Come tenere le chiavi API lontane dal client e rispettare i crediti

Documentazione leggibile dall'AI

Riferimento rapido: /llm.md

https://pkmnprices.com/llm.md

Disponibile anche sull'host dell'API come https://api.pkmnprices.com/llm.md. Markdown sintetico pensato per le finestre di contesto degli LLM: autenticazione, piani, endpoint e struttura delle risposte.

Schema completo: OpenAPI

https://pkmnprices.com/openapi.json

Lo stesso documento si trova su https://api.pkmnprices.com/openapi.json. È generato automaticamente dall'API: percorsi, parametri, schemi e lo schema di sicurezza x-api-key.

Per leggere uno dei due URL non serve una chiave API. Per chiamare /v1/cards (e il resto dell'API dei dati) sì:

x-api-key: pk_your_key_here

Prendi una chiave gratis dalla dashboard.

Claude Code

Incolla un URL della documentazione nel prompt, oppure fissalo in CLAUDE.md:

## External APIs

PkmnPrices API:
- Quick ref: https://pkmnprices.com/llm.md
- OpenAPI: https://pkmnprices.com/openapi.json
- Auth: x-api-key header
- Prefer official SDKs: pkmnprices (Python), @pkmnprices/sdk (TypeScript)

Prompt di esempio:

Read https://pkmnprices.com/llm.md and use the pkmnprices Python SDK to
search for a card by name, then fetch its USD market prices.

Cursor

Recupera il riferimento rapido con @web, oppure aggiungi una regola di progetto:

When working with Pokemon card prices, use the PkmnPrices API.
Quick ref: https://pkmnprices.com/llm.md
OpenAPI: https://pkmnprices.com/openapi.json
Auth: x-api-key. Prefer @pkmnprices/sdk in TypeScript.

Esempio:

@web https://pkmnprices.com/llm.md

Create a small TypeScript script with @pkmnprices/sdk that searches for
"charizard" and prints the first card's market prices.

Codex

Metti gli stessi riferimenti in AGENTS.md (o nelle istruzioni del progetto), così Codex li carica a ogni sessione:

## PkmnPrices

- https://pkmnprices.com/llm.md
- https://pkmnprices.com/openapi.json
- Auth header: x-api-key
- SDKs: pkmnprices (Python), @pkmnprices/sdk (JS/TS)
- List endpoints do not include prices — always GET by id for prices

Esempio completo: prima la ricerca, poi il prezzo

Le chiamate di elenco restituiscono riepiloghi senza prezzi. Per avere prices devi recuperare una singola carta (o un prodotto sigillato) tramite id. Questa separazione confonde molti: scrivilo nel prompt.

Prompt

Using https://pkmnprices.com/llm.md, write a short program that:
1. Searches cards named "charizard" (per_page 5)
2. Fetches the first result by id with currency=usd
3. Prints name, set, and each market_price with the right $ or € symbol
Use the official SDK. Store the key in an env var. Never hardcode it.

Python (pkmnprices)

pip install pkmnprices
export PKMNPRICES_API_KEY=pk_your_key_here

import os
from pkmnprices import PkmnPrices

client = PkmnPrices(os.environ["PKMNPRICES_API_KEY"])

page = client.cards.list(name="charizard", per_page=5)
card = client.cards.get(page.data[0].id, currency="usd")

print(f"{card.name} — {card.set.name}")
for price in card.prices:
    symbol = "€" if price.currency == "EUR" else "$"
    print(f"  {price.source}: {symbol}{price.market_price}")

client.close()

TypeScript (@pkmnprices/sdk)

npm install @pkmnprices/sdk
export PKMNPRICES_API_KEY=pk_your_key_here

import { PkmnPrices } from "@pkmnprices/sdk";

const client = new PkmnPrices({ apiKey: process.env.PKMNPRICES_API_KEY! });

const { data } = await client.cards.list({ name: "charizard", per_page: 5 });
const card = await client.cards.get(data[0].id, { currency: "usd" });

console.log(`${card.name} — ${card.set.name}`);
for (const price of card.prices) {
  const symbol = price.currency === "EUR" ? "€" : "$";
  console.log(`  ${price.source}: ${symbol}${price.market_price}`);
}

Per andare oltre

Ti serve un comando /price su Discord? Lo abbiamo già spiegato passo per passo con l'SDK Python: Creare un bot Discord per i prezzi Pokémon.

Lo stesso schema «prima l'elenco, poi il dettaglio» vale per i prodotti sigillati, lo storico dei prezzi e le inserzioni eBay / TCGplayer: trovi tutto nella documentazione dell'API e nella sezione LLM Integration.

Consigli per generazioni migliori

Sii specifico. «Fammi un'app per i prezzi Pokémon» è troppo vago. Indica l'URL della documentazione, l'SDK, la variabile d'ambiente, come gestire la valuta e i passaggi «prima l'elenco, poi il dettaglio».

Tieni le chiavi sul server. Il codice nel browser deve chiamare il tuo backend; è il tuo backend a chiamare PkmnPrices con x-api-key.

Aspettati dei 429. Il piano gratuito prevede 100 crediti al giorno e 60 richieste al minuto. Gli SDK ritentano i 429 dovuti al limite di richieste; con i 429 dovuti al limite di crediti bisogna aspettare il giorno dopo, quindi gestiscili nell'interfaccia.

Leggi currency su ogni prezzo. Mostra $ / € in base al campo; non convertire tra USD ed EUR.

Domande frequenti

Devo dare al modello /llm.md o OpenAPI?

Usa /llm.md per i compiti rapidi e le finestre di contesto piccole. Usa /openapi.json quando l'agente ha bisogno degli schemi esatti, di tutti i parametri di query o deve generare un client tipizzato. In molti flussi di lavoro si carica prima /llm.md e OpenAPI solo se qualcosa non è chiaro.

Perché usare un SDK invece di fetch diretto?

Gli SDK ufficiali inviano x-api-key al posto tuo, tipizzano le risposte, gestiscono la paginazione e ritentano i 429 dovuti al limite di richieste. Spendi token sulla logica del prodotto invece che sull'infrastruttura HTTP.

Mi serve una chiave API per leggere la documentazione?

No. /llm.md e /openapi.json sono pubblici. La chiave (dalla dashboard, il piano gratuito va benissimo) ti serve solo per chiamare gli endpoint dei dati /v1.

Perché cards.list non restituisce i prezzi?

Le risposte di elenco restano leggere per le interfacce di ricerca. Chiama cards.get(id) (o sealed.get) per avere l'array prices. Scrivilo esplicitamente nel prompt, così il modello non si inventa un campo prices negli elementi dell'elenco.

Per iniziare

1. Crea una chiave gratuita nella dashboard
2. Dai un'occhiata a LLM Integration e copia il prompt di sistema
3. Indica al tuo agente di programmazione /llm.md (e OpenAPI quando ti serve lo schema completo)

Questo contesto basta a Claude Code, Cursor o Codex per consegnarti un'integrazione funzionante in una sola sessione.