Riferimento dell’Open API e del server MCP di Fincanva

Come si invoca un’operazione di Fincanva?

• Via REST, invia POST a https://app.fincanva.com/api/v1/research/<operation_id> con i parametri in un corpo JSON e un’intestazione Authorization: Bearer con una chiave API o un token di accesso OAuth.
• Via MCP, aggiungi https://app.fincanva.com/mcp a un client MCP; ogni operazione è uno strumento con il nome del suo id, e il client accede con il tuo account Fincanva.
• Il documento OpenAPI 3.1 di tutte le operazioni REST si trova in https://app.fincanva.com/api/v1/research/openapi.json.

Che cosa restituisce ogni operazione di Fincanva?

Una chiamata REST riuscita restituisce status: true e un oggetto data che contiene result (il risultato proprio dell’operazione), summary (poche righe di testo), assumed (ogni valore che l’operazione ha riempito perché la richiesta lo ometteva, con il motivo), dataVersion (la build notturna dei dati da cui provengono le cifre, oppure null quando nulla è stato calcolato dai dati di mercato) e, quando il risultato è una serie, chart. Un risultato registrato porta anche recipeId (ciò che lo riproduce: la stessa operazione, lo stesso input e la stessa versione dei dati) e permalink (l’indirizzo permanente del risultato su Fincanva). Via MCP lo stesso oggetto è il contenuto strutturato dello strumento e il riepilogo ne è il testo.

Il significato di ogni unità e di ogni segno è scritto una volta sola, nelle convenzioni.

Quali operazioni di Fincanva puoi invocare?

Creazione delle strategie

• Elenca i metodi di allocazione — list_allocation_methods. Elenca i metodi di allocazione che Fincanva offre — il modo in cui una strategia, o una Combinata tra le sue strategie, stabilisce il peso di ogni posizione — con le impostazioni proprie di ciascun metodo, i valori predefiniti e i limiti, i livelli a cui funziona e se il tuo piano lo include.
• Elenca i preset delle condizioni di rischio — list_risk_rule_presets. Elenca le condizioni di rischio pronte che una strategia può attivare — il VIX, il rapporto VIX, i TIPS, le regole sulla curva dei rendimenti, l’S&P 500 rispetto alla sua media a 200 giorni e il suo momentum a 12 mesi — ciascuna con la regola che applica: l’indicatore, le soglie di risk-off e di risk-on, le settimane di ritardo e i valori che puoi modificare.
• Descrivi il modello di strategia — describe_portfolio_model. Descrive il modello di strategia di Fincanva una sezione alla volta — il livello della Combinata (il portfolio dell’API), le condizioni di rischio, l’allocazione, le strategie dentro una Combinata (i models dell’API), le uscite dalle posizioni, la selezione e le impostazioni di simulazione — elencando ogni campo con il tipo, l’unità, il valore predefinito, i limiti e i valori ammessi, e il limite del tuo piano dove ce n’è uno.

Screening

• Elenca i filtri dello screener — list_screen_filters. Cerca nel catalogo dei filtri dello screener per parole nel nome o nella descrizione di un filtro, per concetto d’investimento (value, momentum, quality e altri), per livello (asset, sector, market), per categoria o per tipo di asset, e restituisce ogni filtro trovato con gli input che accetta e i tipi di confronto che supporta.
• Descrivi un filtro dello screener — describe_screen_filter. Restituisce un filtro dello screener per intero: che cosa misura, gli input che accetta (come quanti mesi o bilanci prima viene letto il suo valore), ogni relazione che supporta (maggiore di, tra, i primi N, rispetto all’aggregato di mercato o di settore, rispetto al proprio passato), i termini di confronto di ciascuna relazione con i valori ammessi e quelli predefiniti, e l’unità di ogni valore.

Quali codici di errore può restituire un’operazione di Fincanva?

• invalid_input — HTTP 422. I parametri non corrispondono allo schema dell’operazione; details elenca ogni problema con il suo campo.
• payload_too_large — HTTP 413. Il corpo della richiesta è più grande di quanto un’operazione accetti; details.maxBytes indica il limite. Non è stato eseguito né addebitato nulla.
• result_too_large — HTTP 422. La richiesta era valida, ma il suo risultato è più grande di quanto Fincanva conservi (details.maxBytes; details.what indica il valore). L’esecuzione viene rimborsata. Restringila (meno strumenti, un periodo più breve, meno passi) ed eseguila di nuovo.
• ambiguous — HTTP 422. Un nome che hai indicato corrisponde a più strumenti; details elenca i candidati, quindi scegline uno e chiama di nuovo.
• not_resolved — HTTP 422. Un nome che hai indicato non corrisponde a nessuno strumento che Fincanva ha.
• insufficient_history — HTTP 422. Gli strumenti non hanno abbastanza storico per il periodo o il lookback richiesto.
• unauthorized — HTTP 401. La chiave API o il token di accesso manca, è scaduto o è stato revocato.
• plan_limit — HTTP 403. Il tuo piano non include questa operazione o questa impostazione; unlockedBy indica il piano più basso che la include.
• toolset_disabled — HTTP 403. La famiglia dell’operazione è disattivata per questa connessione MCP; attivala nelle impostazioni della connessione in Fincanva.
• licence — HTTP 403. I dati di cui questa operazione ha bisogno non possono essere serviti tramite l’API o MCP secondo i termini del loro fornitore.
• quota_exhausted — HTTP 429. La quota mensile di chiamate, di esecuzioni pesanti o di report di ricerca è esaurita; resetsAt indica la data in cui si azzera.
• not_found — HTTP 404. L’operazione, oppure un elemento che hai indicato come un filtro, non esiste.
• busy — HTTP 503. Fincanva è al limite della capacità per questo tipo di esecuzione; non è stato addebitato nulla sulla tua quota, quindi riprova a breve.
• engine_failed — HTTP 502. Il calcolo è fallito da parte di Fincanva; non è stato addebitato nulla sulla tua quota.
• internal — HTTP 500. Un errore imprevisto da parte di Fincanva; non è stato addebitato nulla sulla tua quota.