sviluppatori

L’API di Aurum Feed

Ogni prezzo che la mappa mostra, in JSON: il feed, lo storico, i cambi, e il grafo della conoscenza di monete e lingotti, delle loro famiglie, dei rivenditori e di chi li rifornisce. Una chiave, tre piani, nessun SDK da installare.

URL di base

https://aurumfeed.live/api

autenticazione

Manda la chiave nell’header X-Api-Key. Solo quello: l’header Authorization è della piattaforma di hosting all’ingresso, e non arriva all’API come l’hai mandato. Senza chiave il feed, lo storico e i cambi rispondono comunque — è quello che legge questa stessa pagina — ma senza un budget tuo, e senza le risorse che un piano compra.

Le chiavi iniziano con af_live_ sul sito vero e con af_test_ nella sandbox, e ognuna funziona solo dove è stata emessa. Ruota una chiave dalla dashboard nel momento in cui finisce dove non doveva: quella vecchia smette entro dieci secondi.

endpoint

prezzi e storico

percorso	cosa risponde	serve
GET /v1/feed	Ogni moneta e ogni lingotto con la quotazione attuale di ogni rivenditore, i rivenditori con la loro posizione, e lo spot dell’oro in euro al grammo. ?form=coin o ?form=bar serve un compartimento solo e i rivenditori che lo quotano.	aperto
GET /v1/history	Il prezzo tipico delle monete e dei lingotti chiesti (?coins=a,b) su una finestra: ?range=min (un’ora al minuto), hour (un giorno al quarto d’ora), day (un mese a sei ore). ?by=source divide per rivenditore; ?form=coin o bar senza ?coins= è ogni riga di quel compartimento.	aperto
GET /v1/fx	I tassi di riferimento BCE con cui l’hub converte: base euro, uno per valuta, datati.	aperto

monete

percorso	cosa risponde	serve
GET /v1/coins	Il catalogo delle monete, ogni disegno in ogni taglio: oro fino, titolo, valore facciale, zecca e paese, valore del metallo, mediana e quanti rivenditori la quotano.	aperto
GET /v1/coins/{id}	Una moneta con i suoi tagli, le quotazioni dalla più bassa, e i titoli che i negozi le danno. ?format=jsonld per schema.org.	aperto
GET /v1/coins/{id}/quotes	Le quotazioni di una moneta adesso, o com’erano a un istante passato con ?asOf= (ISO 8601 o millisecondi epoch).	Pro o Business
GET /v1/families	Le famiglie delle monete: ogni disegno con la moneta guida, i tagli, la zecca e il paese, e i nomi che usano i negozi.	aperto
GET /v1/families/{id}	Una famiglia con le sue monete, la moneta intera per prima.	aperto

lingotti

I lingotti hanno un compartimento tutto loro. Il lingotto di un produttore è lingotto-pamp-100-g, quello di una marca fuori dall’elenco lingotto-altre-marche-100-g, e lingotto-100-g è il 100 g di qualsiasi marca: ogni negozio al suo 100 g più conveniente, chiunque l’abbia fatto. Un lingotto non è mai elencato sotto /v1/coins né una moneta sotto /v1/bars; chiesto nel compartimento sbagliato, il 404 indica l’indirizzo che risponde.

percorso	cosa risponde	serve
GET /v1/bars	Il catalogo dei lingotti: ogni peso dal grammo al chilo di qualsiasi marca, poi i lingotti di ogni produttore e delle altre marche che i negozi vendono — marca, oro fino, valore del metallo, mediana e quanti rivenditori lo quotano.	aperto
GET /v1/bars/{id}	Un lingotto con i suoi pesi, lo stesso peso di ogni marca quotata (sameWeight) e le quotazioni dalla più bassa. Sul lingotto di qualsiasi marca ogni quotazione è il lingotto più conveniente di quel peso in un negozio, e barId dice di chi. ?format=jsonld per schema.org.	aperto
GET /v1/bars/{id}/quotes	Le quotazioni di un lingotto adesso, o com’erano a un istante passato con ?asOf=; il lingotto di qualsiasi marca si legge dalle righe dei produttori, con barId.	Pro o Business
GET /v1/bars/brands	I tredici produttori i cui lingotti sono quotati per nome — Argor-Heraeus, C.Hafner, Heraeus, PAMP, Valcambi e gli altri — con la sede e i loro lingotti in vendita.	aperto
GET /v1/bars/brands/{id}	Un produttore con i suoi lingotti, dal più leggero, ciascuno con la mediana e quanti rivenditori lo quotano.	aperto

rivenditori

percorso	cosa risponde	serve
GET /v1/dealers	I rivenditori in vista: host, paese, dove stanno e se è una misura, affidabilità su trenta giorni, chi li rifornisce.	aperto
GET /v1/dealers/{id}	Un rivenditore con il suo profilo (valutazioni datate, contatti, pagamenti, servizi, i fornitori da cui compra e chi lo dice), le sue quotazioni e ogni pagina letta. ?format=jsonld per schema.org.	aperto
GET /v1/dealers/{id}/coins	Le monete che un rivenditore copre, ciascuna con la quotazione in corso o null.	aperto
GET /v1/dealers/{id}/bars	I lingotti che un rivenditore copre, ciascuno sulla riga del suo produttore, con la quotazione in corso o null.	aperto

il grafo intero

percorso	cosa risponde	serve
GET /v1/graph	Tutto il grafo della conoscenza in una risposta: ogni nodo e ogni arco con la sua provenienza, compresi i fornitori dei negozi. ?types=coin,family tiene solo alcuni tipi di nodo.	Pro o Business

Una moneta, un lingotto o un rivenditore rispondono anche nel vocabolario di schema.org (Product, ProductGroup, Offer, Store) come application/ld+json: aggiungi ?format=jsonld.

esempio

curl -s "https://aurumfeed.live/api/v1/coins/sterlina" \
  -H "X-Api-Key: af_live_…"

curl -s "https://aurumfeed.live/api/v1/coins/sterlina/quotes?asOf=2026-10-01T09:00:00Z" \
  -H "X-Api-Key: af_live_…"

curl -s "https://aurumfeed.live/api/v1/bars/lingotto-c-hafner-100-g" \
  -H "X-Api-Key: af_live_…"

Postman

Una collezione pronta: ogni endpoint qui sopra, una cartella per compartimento — prezzi, monete, lingotti, rivenditori, il grafo — una variabile baseUrl e una variabile apiKey in cui mettere la chiave, mandata come X-Api-Key a ogni richiesta. Importa il file, incolla la chiave nella variabile, e il test di ogni richiesta stampa quanto resta del budget del mese.

scarica la collezione Postman

limiti e header

Ogni piano ha un budget di richieste per mese di calendario (UTC) e un limite di raffica al minuto. Senza chiave si legge quello che legge la pagina — il feed, lo storico, i cambi — con un tetto di richieste al minuto per indirizzo; una chiave lo toglie. Ogni risposta porta X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (il primo del mese prossimo, in secondi Unix); X-RateLimit-Burst è il tetto al minuto. Oltre uno dei due limiti la risposta è 429 con Retry-After.

errori

Un errore è JSON con un campo error. 401: nessuna chiave, o una revocata. 402: l’abbonamento dietro la chiave non è servito — in attesa, sospeso o cancellato — e la dashboard dice perché. 403: il piano non include la risorsa. 404: moneta, lingotto, produttore, famiglia o rivenditore sconosciuti — e un lingotto chiesto sotto /v1/coins, o una moneta sotto /v1/bars, con un campo che dice dov’è. 429: oltre un limite.

freschezza

Il feed si muove una volta ogni trenta secondi, e con lui lo storico e il grafo. Chiedi quello che ti serve e tienilo per l’intervallo: cento letture al minuto dello stesso feed non comprano niente che un lettore possa vedere.

piani

I piani a pagamento non sono ancora aperti: il feed, lo storico e i cambi rispondono senza chiave.