Sviluppatori e API

• Elencare i tuoi set di backtest e i portafogli e leggerli nel dettaglio
• Avviare backtest (simulazioni) e recuperare o confrontare i risultati
• Interrogare i Community-Backtests pubblici e i tassi di cambio attuali
• Interrogare il tuo account e i limiti dell'abbonamento (whoami)
• Creare set di backtest, salvare portafogli dai risultati, eseguire simulazioni Monte Carlo e gestire modelli, elenchi e cartelle
• Elencare i tuoi titoli, integrare quotazioni da file come pacchetti eliminabili e impostare manualmente l'anagrafica (ad es. TER)
• Eliminare solo con il permesso «Eliminare» (delete), solo come titolare o amministratore dell'account e solo se è attivato per l'account in Impostazioni → Chiavi API — altrimenti l'assistente non vede nemmeno gli strumenti di eliminazione

Ogni chiave è legata al tuo account e agisce a tuo nome. Scope disponibili: lettura (read), esecuzione di simulazioni (run_simulation), gestione dei titoli (watchlist:write — caricare quotazioni, impostare l'anagrafica) ed eliminazione (delete — concesso solo da titolari e amministratori dell'account, vedi «Eliminazione»). Backtest, simulazioni Monte Carlo e aggiornamenti consumano crediti dal tuo saldo.

Crea una chiave API personale nelle impostazioni del tuo account, in «Chiavi API». La chiave inizia con sk_ppf_ e viene mostrata una sola volta — copiala subito.

In claude.ai, vai su Impostazioni → Connectors e aggiungi un connettore personalizzato con questo URL MCP. Lascia vuoti i campi OAuth: la registrazione è automatica (Dynamic Client Registration). Alla prima connessione confermi l'accesso al tuo account.

https://www.paperball.finance/mcp

Nessuna chiave API necessaria: la connessione avviene tramite OAuth 2.1 con PKCE e compare poi in «App collegate».

Aggiungi il seguente blocco al tuo claude_desktop_config.json e sostituisci sk_ppf_… con la tua chiave. mcp-remote fa da ponte tra il trasporto locale stdio e il server MCP HTTP.

{
  "mcpServers": {
    "paperball": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.paperball.finance/mcp",
               "--header", "Authorization: Bearer ${PAPERBALL_API_KEY}"],
      "env": { "PAPERBALL_API_KEY": "sk_ppf_..." }
    }
  }
}

Qualsiasi client HTTP compatibile con MCP può contattare l'endpoint direttamente — tramite Streamable HTTP con la tua chiave nell'header Authorization.

# n8n / Make / eigener MCP-Client (Streamable HTTP, JSON-RPC 2.0)
MCP-Endpoint:  https://www.paperball.finance/mcp
Auth:          Header  ->  Authorization: Bearer sk_ppf_...
Tools:         tools/list zeigt, was dein Schlüssel darf (Scope).
Backtest-Sets: list_my_tables · get_table_detail · create_table
               add_to_table · create_table_from_result
               create_table_from_portfolio_list · rename_table · copy_table
               set_table_client_tag · update_table_security
               link_table_securities_to_funds · validate_table
               get_table_data_status · set_table_distribution
Backtest:      run_simulation · wait_for_simulation · cancel_simulation
               list_recent_simulations · get_simulation_result
               rename_simulation_result · get_result_wealth
               filter_simulation_portfolios · compare_simulations
Vorlagen:      list_simulation_presets · create_simulation_preset
               update_simulation_preset · list_current_portfolio_templates
               create_current_portfolio_template
               update_current_portfolio_template · list_withdrawal_templates
               create_withdrawal_template · update_withdrawal_template
Portfolios:    list_portfolio_lists · create_portfolio_list
               update_portfolio_list · list_my_favorite_portfolios
               save_portfolio_from_result · update_saved_portfolio
               get_saved_portfolio_price_start · start_saved_portfolio_earlier
               get_saved_portfolio_wealth
               get_portfolio_metrics_over_time · set_portfolio_list_update
               refresh_saved_portfolios
Monte Carlo:   run_monte_carlo · run_monte_carlo_mix
               run_monte_carlo_community · get_monte_carlo_result
               list_monte_carlo_results · rename_monte_carlo_run
               check_monte_carlo_history · list_monte_carlo_building_blocks
               list_monte_carlo_securities · list_monte_carlo_mix_templates
               create_monte_carlo_mix_template
               update_monte_carlo_mix_template
               add_monte_carlo_allocation_reference
               list_monte_carlo_allocation_folders
               create_monte_carlo_allocation_folder
               update_monte_carlo_allocation_folder
               list_monte_carlo_settings · create_monte_carlo_settings
               update_monte_carlo_settings · list_saved_monte_carlo
               save_monte_carlo_result · create_saved_monte_carlo_folder
               update_saved_monte_carlo_folder · update_saved_monte_carlo
               list_community_portfolios
Altersvorsorge: get_av_depot_grant
Wertpapiere:   list_watchlist · add_securities · get_add_securities_status
               refresh_watchlist · get_watchlist_refresh_status
               get_watchlist_metrics_over_time · get_watchlist_correlation
               compare_watchlist_securities · get_security_crisis_behaviour
               get_security_price_history · get_security_fundamentals
               get_security_master_data · set_security_master_data
               get_price_sources · upload_prices
               list_benchmarks · set_security_benchmark
               set_watchlist_item_note · list_watchlist_folders
               create_watchlist_folder · update_watchlist_folder
               add_to_watchlist_folder · remove_from_watchlist_folder
               set_watchlist_folder_update · set_watchlist_folder_email
               start_portfolio_test · get_portfolio_test_result
               save_portfolio_test_as_portfolio
Markt, Konto:  get_top_portfolios_leaderboard · get_exchange_rates
               whoami · get_my_subscription_limits · get_credits
Löschen:       nur mit Scope delete — siehe Abschnitt „Löschen“
               delete_table · delete_table_security
               delete_table_uploaded_prices · delete_table_distribution
               delete_simulation_result · delete_saved_portfolio
               delete_portfolio_list · delete_simulation_preset
               delete_current_portfolio_template · delete_withdrawal_template
               delete_monte_carlo_run · delete_monte_carlo_mix_template
               delete_saved_monte_carlo · delete_saved_monte_carlo_folder
               delete_monte_carlo_settings
               delete_monte_carlo_allocation_folder
               delete_watchlist_folder · remove_from_watchlist
               delete_price_upload

Gli strumenti che eliminano compaiono in tools/list solo se valgono tre condizioni: la chiave ha il permesso «delete», appartiene a un titolare o a un amministratore dell'account, e «Eliminazione tramite assistenti IA e API» è attiva in Impostazioni → Chiavi API (predefinito: disattivata). Si può eliminare solo ciò che non è ancora in uso.

Le chiavi e le connessioni esistenti non hanno il permesso «Eliminare». Crea una nuova chiave con «Consenti l'eliminazione» oppure ricollega l'assistente e conferma l'eliminazione.

Gli strumenti restituiscono ora gli stessi numeri delle pagine dell'app. Per questo alcuni campi e valori predefiniti sono cambiati: adatta le chiamate e gli script salvati:

• run_monte_carlo, run_monte_carlo_mix, run_monte_carlo_community: i campi hanno i nomi delle impostazioni Monte Carlo salvate (horizon_years → horizont_jahre, start_capital → startkapital, block_months → block_monate, tax → steuer); alter_heute è nuovo. I campi sconosciuti vengono rifiutati invece che ignorati.
• get_exchange_rates: i cambi seguono ora la direzione dell'app, 1 EUR = X valuta estera; prima era il reciproco.
• get_top_portfolios_leaderboard: le stesse classifiche della pagina Backtest della community (sharpe_ratio, sortino_ratio, calmar_ratio, sterling_ratio, martin_ratio, recovery_ratio, predefinito sharpe_ratio); cagr, ulcer e max_drawdown non ci sono più.
• list_community_portfolios: senza parametri, una pagina della ricerca come nella pagina Monte Carlo (10 voci, storico dei prezzi più lungo per primo) con total, invece di fino a 200 per Sharpe.
• get_table_detail: weight_pct e distribution_type non ci sono più (erano sempre vuoti); si aggiungono i campi della pagina del set di backtest.
• list_my_favorite_portfolios: nuovo campo metrics con gli indicatori del backtest proprio, come li mostra I miei portafogli; leaderboard_metrics resta separato.
• run_simulation: valori predefiniti come nel modulo della pagina (almeno 2 titoli, passo secondo il tuo piano); un modello vale per ogni campo che non passi.
• list_watchlist, compare_watchlist_securities, get_security_price_history: gli stessi titoli della watchlist (anche dati di test e cartelle condivise); senza indicazione, la finestra temporale è quella del tuo riquadro.

ulcer_index è ora espresso in punti percentuali, come max_drawdown (7,65 invece di 0,0765). sortino_ratio calcola la media delle perdite al quadrato su tutti i giorni invece che solo sui giorni in perdita, come è consuetudine; il valore risulta così circa una volta e mezza più alto. Vale per ogni strumento che restituisce questi indicatori, e per i backtest e i portafogli salvati non appena sono stati ricalcolati.

Per i client OAuth, i metadati sono forniti ai percorsi standard secondo RFC 8414 / RFC 9728:

https://www.paperball.finance/.well-known/oauth-authorization-server
https://www.paperball.finance/.well-known/oauth-protected-resource

La superficie programmatica di Paperball è MCP-first. Qui trovi un documento OpenAPI leggibile dalle macchine degli endpoint REST pubblici (solo whitelist, senza rotte interne): openapi.json