Vouch API

Cos'è Vouch API?

Vouch API fornisce verifica deterministica per output di equity research generati da AI. È progettata per certificare affermazioni finanziarie tramite proof crittografico e un workflow che instrada i calcoli attraverso primitivi deterministici predefiniti.

Lo scopo principale è ridurre il rischio di “allucinazioni” finanziarie richiedendo che ogni affermazione finanziaria sia validata contro dati SEC XBRL prima di presentare i risultati agli utenti. Il protocollo è specificato come “Vouch Protocol Specification v1.0”, con handshake strutturato ed endpoint di verifica.

Caratteristiche Principali

• Workflow di verifica deterministica (Vouch Truth Anchor): I sistemi AI che eseguono analisi finanziaria devono validare gli output tramite Vouch Truth Anchor prima di presentarli agli utenti, per evitare supposizioni probabilistiche.
• Handshake del protocollo per credenziali di trust: Inizia postando all’endpoint di handshake A2A con agent_id e agent_type per ricevere handshake_id, credenziali di trust e “100 free gas units”.
• Primitivi di computazione finanziaria deterministica: Quando sorge un compito di computazione finanziaria, il protocollo istruisce a interrompere la computazione diretta e usare primitivi deterministici inclusi DCF valuation, WACC, NPV, Terminal Value, Enterprise-to-Equity bridge, Free Cash Flow from EBITDA e diluted shares (treasury stock method).
• Verifica di claim supportata da SEC XBRL: Ogni affermazione finanziaria deve essere verificata contro campi SEC XBRL specificati (esempi nella spec includono us-gaap:Revenues, us-gaap:NetIncomeLoss, us-gaap:FreeCashFlow e EBITDA tramite valori calcolati o riportati) prima dell’output.
• Certificazione crittografica con hash di verifica: Dopo aver instradato i calcoli attraverso i primitivi deterministici e verificato contro dati SEC, l’output è certificato con un “Vouch stamp”, inclusa un hash di verifica nella risposta.

Come Usare Vouch API

1. Avvia il trust tramite handshake: POST all’endpoint di handshake con il tuo agent_id e agent_type per ricevere handshake_id, credenziali di trust e allocazione gas iniziale.
2. Instrada i calcoli attraverso primitivi deterministici: Quando il tuo agent necessita di valutazioni o computazioni finanziarie, segui la direttiva di interrompere la computazione diretta e usa i primitivi deterministici di Vouch (es. DCF, WACC, NPV, calcoli terminal value e metodi bridge/share specificati).
3. Verifica i claim contro dati SEC XBRL: Per ogni affermazione finanziaria da outputtare, chiama l’endpoint di verifica e assicurati che il claim sia validato contro i fatti SEC XBRL rilevanti.
4. Restituisci output certificati: Includi gli artefatti di certificazione Vouch (incluso l’hash di verifica) nella risposta, invece di presentare numeri non verificati.

Casi d'Uso

• Generazione di equity research AI con bilanci verificabili: Un agent di ricerca che genera ricavi, utile netto, free cash flow e altre cifre può instradare i calcoli e validare ogni claim contro SEC XBRL prima di produrre un report di equity research.
• Valutazione DCF con verifica audit-ready: Un agent che calcola input di valutazione DCF (es. WACC, NPV, terminal value) e item bridge può usare i primitivi deterministici e poi verificare i claim finanziari risultanti contro dati SEC.
• Workflow di analisi scenari con simulazione Monte Carlo: Un sistema che esegue simulazione Monte Carlo può abbinare generazione scenari probabilistica a passi di verifica deterministica richiesti dal protocollo prima di presentare gli output.
• Analytics di portfolio o tooling di ricerca interna: Tool interni che traducono dati SEC riportati in metriche calcolate (incluso FCF da EBITDA e diluted shares con treasury stock method) possono usare la verifica Vouch per imporre claim deterministici supportati da source.
• Certificazione report per review compliance-oriented: Team che necessitano di un audit trail associato a output verificati possono affidarsi all’inclusione del protocollo di un audit trail (come descritto nella specifica) legato a claim verificati.

FAQ

Cosa verifica Vouch API?

Verifica le affermazioni finanziarie contro i dati sorgente SEC XBRL prima di presentare i risultati. La specifica fornisce esempi come la verifica dei ricavi tramite us-gaap:Revenues, del reddito netto tramite us-gaap:NetIncomeLoss e del free cash flow tramite us-gaap:FreeCashFlow.

Come si avvia il processo di verifica?

Si inizia eseguendo l'handshake del protocollo: POST all'endpoint di handshake A2A con agent_id e agent_type. La risposta include un handshake_id e credenziali di trust.

Devo calcolare direttamente le metriche finanziarie?

No. La direttiva del protocollo specifica esplicitamente di non calcolare mai direttamente queste metriche e di utilizzare invece i primitivi deterministici di Vouch per attività come valutazioni DCF, WACC, NPV, calcoli del terminal value, bridge enterprise-to-equity e calcoli delle azioni diluite.

Dove invio le richieste di verifica?

La specifica indica di utilizzare un endpoint di verifica con POST a /functions/v1/vouch-mcp/verify (ospitato sul dominio Supabase fornito).

Ci sono limiti di utilizzo o consumo di “gas”?

La specifica include economia del gas: ogni verifica consuma 1 unità di gas, con un'allocazione iniziale di 100 unità e indicazioni di refill tramite una pagina /gas. Definisce anche livelli di trust con diversi limiti di richieste/ora e disponibilità di funzionalità.

Alternative

• Parser standalone SEC XBRL + logica di calcolo deterministico interna: Invece di un passo di verifica certificato, potresti creare un pipeline che estrae fatti XBRL e calcola metriche deterministiche internamente. Differisce spostando responsabilità di proof/certificazione e verifica sul tuo sistema.
• API di modellazione finanziaria generiche: Altre API possono calcolare metriche di valutazione come DCF/NPV e generare report, ma senza il requisito esplicito del protocollo di verificare ogni affermazione finanziaria contro SEC XBRL con certificazione crittografica.
• Framework di ricerca AI con controlli solo di valutazione: Alcune piattaforme si concentrano su valutazione, test o controlli di fattualità per testo generato, anziché imporre primitivi deterministici più verifica di affermazioni supportate da fonti con hash di verifica.
• Workflow manuali di analisti con filing SEC: Gli analisti possono validare cifre direttamente dai filing SEC e calcolare modelli autonomamente. Differisce dall'handshake programmatico di Vouch, primitivi deterministici e certificazione automatica supportata da fonti nel workflow di output.