Come costruire un agente di ricerca sugli investimenti: mercati, fondamentali, SEC e dati economici in un'unica API
Un agente di ricerca sugli investimenti ha bisogno di cinque livelli di dati distinti — prezzi, fondamentali, filing, macro e notizie — ciascuno di solito un fornitore, una chiave e uno schema a parte. Ecco come collegare tutti e cinque dietro un unico set di endpoint, con codice funzionante e i conti dei costi.
In breve
- •Un agente finanziario utile ha bisogno di cinque livelli di dati: mercati in tempo reale (prezzi), fondamentali aziendali (bilanci), filing SEC, indicatori economici e notizie. Cuciti insieme da fornitori distinti sono 5 contratti, 5 chiavi e 5 schemi.
- •API Pick espone tutti e cinque come endpoint di ricerca JSON coerenti — /search/markets, /search/financials, /search/sec, /search/economic, /search/news — più /extract per i documenti completi. Una sola chiave, già pronta per il tool calling degli LLM.
- •Il pattern dell'agente: esegui gli endpoint rilevanti in parallelo come strumenti, unisci il JSON e lascia che il modello ragioni su dati ancorati invece di allucinare cifre.
- •Il prezzo in crediti è solo-se-riesce: markets 120, financials 200, sec 120, economic 50, news 15 per chiamata. Un tipico turno di ricerca multi-strumento costa ben al di sotto di $0.01–$0.10 a seconda della profondità.
- •Build-vs-buy: assemblare da soli Polygon + un fornitore di fondamentali + SEC EDGAR + FRED + un'API di notizie sono settimane di integrazione e 5 fatture mensili; la via del singolo endpoint è un giorno.
Il problema dei cinque livelli
Chiedi a un LLM "NVIDIA è cara in questo momento?" e si inventerà un rapporto P/E con piena sicurezza. La soluzione non è un modello più grande — è l'ancoraggio. Un agente di research che si guadagna la fiducia deve recuperare dati live e citati attraverso cinque livelli, e poi ragionare su di essi:
- Mercati — il prezzo attuale, la capitalizzazione e come si è mosso. Cripto, forex, ETF e i titoli più movimentati della giornata quando è rilevante.
- Fondamentali — stato patrimoniale, conto economico, flusso di cassa, dividendi e transazioni degli insider. Il livello del "l'azienda è davvero sana".
- Filing SEC — fattori di rischio del 10-K, dettaglio del 10-Q, eventi dell'8-K, linguaggio delle earnings call. La dimensione qualitativa che le cifre non colgono.
- Indicatori economici — tassi, inflazione, occupazione, PIL da FRED, BLS, Banca Mondiale e IMF. Lo sfondo macro entro cui si colloca ogni tesi.
- Notizie — il catalizzatore tempestivo: un declassamento, il lancio di un prodotto, un'azione regolatoria.
Cuciti insieme da fornitori distinti, sono cinque contratti, cinque chiavi API, cinque regimi di rate-limit e cinque schemi di risposta da normalizzare prima che un modello possa toccarli. L'integrazione è dove i progetti di agenti finanziari si arenano.
Un set di endpoint, cinque livelli
API Pick espone ogni livello come un endpoint di ricerca JSON coerente, così l'agente parla con una sola chiave e una sola forma di risposta:
- Markets Search — azioni globali e USA, cripto, forex, ETF, fondi, materie prime e i titoli più movimentati negli USA.
- Financials Search — stati patrimoniali, conti economici, flusso di cassa, dividendi, transazioni degli insider.
- SEC Filings Search — 10-K/10-Q/8-K, trascrizioni degli utili, statistiche sull'equity.
- Economic Data Search — FRED, BLS, Banca Mondiale, IMF, USAspending, Destatis.
- News Search — notizie filtrate per data dai principali media.
- Extract — recupera un filing o un articolo completo in markdown pulito quando uno snippet non basta.
L'architettura dell'agente
Registra ogni endpoint come uno strumento. Quando arriva una domanda, l'agente decide quali livelli gli servono, li chiama in parallelo, unisce il JSON e ragiona sul risultato ancorato. Una domanda su un ticker tocca markets + fondamentali + notizie; una domanda "come è posizionato il settore" tocca economic + notizie + un paio di comparabili.
import asyncio, httpx, os
API = "https://api.apipick.com/v1"
HEADERS = {"x-api-key": os.environ["APIPICK_KEY"], "Content-Type": "application/json"}
async def search(client, path, query, **kw):
r = await client.post(f"{API}/{path}", headers=HEADERS,
json={"query": query, **kw})
r.raise_for_status()
return r.json()["results"]
async def research(ticker: str):
async with httpx.AsyncClient(timeout=30) as c:
markets, fundamentals, filings, macro, news = await asyncio.gather(
search(c, "search/markets", f"{ticker} price and market cap"),
search(c, "search/financials", f"{ticker} latest balance sheet and cash flow"),
search(c, "search/sec", f"{ticker} 10-K risk factors", end_date="2026-06-16"),
search(c, "search/economic", "US interest rates and inflation latest"),
search(c, "search/news", f"{ticker} latest news", end_date="2026-06-16"),
)
return {"markets": markets, "fundamentals": fundamentals,
"filings": filings, "macro": macro, "news": news}
# Feed the merged JSON back to your LLM as grounding, with the source URLs,
# and ask it to synthesize — never to recall numbers.
context = asyncio.run(research("NVDA"))Ogni risultato porta con sé un URL source. Trasmettili fino alla risposta finale così che un essere umano possa verificare ogni affermazione — e così che l'output dell'agente sia citabile, che è ciò che lo rende utile in un flusso di lavoro reale.
Build vs. buy
| Assemblarlo da solo | API Pick | |
|---|---|---|
| Fornitori / chiavi | ~5 (Polygon, fondamentali, EDGAR, FRED, notizie) | 1 |
| Forme di risposta | 5 da normalizzare | 1 forma di JSON |
| Tempo al primo agente | Settimane di integrazione | Un giorno |
| Fatturazione | 5 abbonamenti mensili | Per chiamata, solo se riesce |
| Pronto per LLM | Formatti tu ciascuno | Snippet pre-formattati + URL di origine |
Per un solo tipo di dato, andare diretti è ragionevole. Per un agente che ha bisogno di tutti e cinque ed esplora in modo imprevedibile, la via del singolo endpoint va in produzione in un giorno e fattura solo quando una chiamata riesce.
Cosa sblocca tutto questo
Gli stessi cinque strumenti alimentano molto più dei semplici lookup di ticker: agenti di briefing per la stagione degli utili, screen settoriali ancorati ai fondamentali, commenti di portafoglio consapevoli della macro e assistenti di due diligence che leggono il 10-K vero e proprio tramite Extract. Il pattern è sempre lo stesso — chiamate a strumenti ancorate, recupero in parallelo, sintesi su dati reali con le fonti allegate.
Parti con una chiave gratuita (100 crediti, senza carta) e collega i cinque strumenti al framework di agenti che preferisci. Da lì è ingegneria dei prompt, non idraulica.
Domande frequenti
Di quali dati ha davvero bisogno un agente di ricerca sugli investimenti?
Cinque livelli. (1) Mercati in tempo reale — prezzi, cripto, forex, ETF, i titoli più movimentati, per la domanda "cosa sta facendo adesso". (2) Fondamentali — stato patrimoniale, conto economico, flusso di cassa, dividendi, transazioni degli insider. (3) Filing SEC — testo di 10-K/10-Q/8-K e trascrizioni degli utili per i segnali qualitativi. (4) Indicatori economici — FRED, BLS, Banca Mondiale, IMF per lo sfondo macro. (5) Notizie — catalizzatori tempestivi. La maggior parte degli agenti fallisce perché ha i prezzi ma non i fondamentali, o i fondamentali ma non il contesto macro.
Perché non chiamare direttamente Polygon, FRED e SEC EDGAR?
Puoi farlo — e per un solo tipo di dato va bene. Il problema è che l'agente ha bisogno di tutti e cinque: sono cinque fornitori, cinque schemi di autenticazione, cinque regimi di rate-limit, cinque forme di risposta da normalizzare prima che l'LLM possa usarle, e cinque fatture. L'approccio a singolo endpoint scambia un piccolo sovrapprezzo per chiamata con una chiave, una forma di JSON e fatturazione solo-se-riesce — che, per un agente che fa chiamate esplorative multi-strumento, è di solito la via più economica e di gran lunga più rapida per andare in produzione.
Come evito che l'LLM alluci cifre finanziarie?
Non lasciare mai che il modello produca cifre a memoria. Rendi ogni fonte di dati uno strumento, obbliga l'agente a chiamarlo e ripassa il JSON restituito come ancoraggio. Il compito del modello è ragionare e sintetizzare sui valori recuperati, non ricordarli. Cita l'URL di origine di ogni risultato così che l'output sia verificabile — è anche ciò che rende la risposta affidabile per un revisore umano.
L'output è adatto per fare trading o dare consigli veri?
No. L'output di un'API di recupero è informativo. Ancora il ragionamento di un analista o di un agente a dati reali; non è consulenza d'investimento e non deve essere usato come segnale di trading automatizzato senza un essere umano qualificato e adeguati controlli del rischio. Tratta l'agente come un acceleratore di research, non come chi decide.
Quanto costa un turno di ricerca?
La fatturazione è per chiamata riuscita: markets 120 crediti, financials 200, sec 120, economic 50, news 15 (1000 crediti ≈ $1). Un turno mirato che tocca markets + fondamentali + notizie sono ~335 crediti (~$0.34); un turno più leggero di macro+notizie sono ~65 crediti. Paghi solo su HTTP 200, quindi le chiamate fallite o vuote non costano nulla — cosa che conta quando un agente esplora.
API usate in questo articolo
Sarah Choy è la CEO di API Pick. Scrive sulla creazione di API pronte per la produzione per agenti IA e flussi di lavoro con LLM.