Ontwikkelaars en API

• Je backtestsets en portefeuilles opsommen en in detail uitlezen
• Backtests (simulaties) starten en resultaten ophalen of vergelijken
• Publieke Community-Backtests en actuele wisselkoersen opvragen
• Je account en abonnementslimieten opvragen (whoami)
• Backtestsets aanmaken, portefeuilles uit resultaten opslaan, Monte-Carlosimulaties uitvoeren en sjablonen, lijsten en mappen beheren
• Je effecten opsommen, koersen uit bestanden als verwijderbare pakketten aanvullen en stamgegevens (bijv. TER) handmatig instellen
• Verwijderen alleen met het recht ‘Verwijderen’ (delete), alleen als eigenaar of accountbeheerder en alleen als het voor het account is aangezet onder Instellingen → API-sleutels — anders ziet de assistent de verwijdertools niet eens

Elke sleutel is aan je account gekoppeld en handelt namens jou. Beschikbare scopes: lezen (read), simulaties uitvoeren (run_simulation), effecten beheren (watchlist:write — koersen uploaden, stamgegevens instellen) en verwijderen (delete — alleen toegekend door eigenaren en accountbeheerders, zie ‘Verwijderen’). Backtests, Monte-Carlo-simulaties en updates verbruiken credits uit je tegoed.

Maak een persoonlijke API-sleutel aan in je accountinstellingen onder “API-sleutels”. De sleutel begint met sk_ppf_ en wordt precies één keer getoond — kopieer hem meteen.

Ga in claude.ai naar Instellingen → Connectors en voeg een aangepaste connector met deze MCP-URL toe. Laat de OAuth-velden leeg — registratie gebeurt automatisch (Dynamic Client Registration). Bij de eerste verbinding bevestig je de toegang tot je account.

https://www.paperball.finance/mcp

Geen API-sleutel nodig — de verbinding wordt gemaakt via OAuth 2.1 met PKCE en verschijnt daarna onder “Gekoppelde apps”.

Voeg het volgende blok toe aan je claude_desktop_config.json en vervang sk_ppf_… door je sleutel. mcp-remote overbrugt het lokale stdio-transport naar de HTTP-MCP-server.

{
  "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_..." }
    }
  }
}

Elke MCP-compatibele HTTP-client kan het endpoint rechtstreeks aanspreken — via Streamable HTTP met je sleutel in de Authorization-header.

# 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

Verwijderende tools verschijnen alleen in tools/list als drie dingen gelden: de sleutel heeft het recht ‘delete’, hij is van een eigenaar of accountbeheerder, en ‘Verwijderen via AI-assistenten en de API’ staat aan onder Instellingen → API-sleutels (standaard: uit). Alleen wat nog niet in gebruik is, kan worden verwijderd.

Bestaande sleutels en verbindingen hebben het recht ‘Verwijderen’ niet. Maak daarvoor een nieuwe sleutel aan met ‘Verwijderen toestaan’ of verbind de assistent opnieuw en bevestig het verwijderen.

De tools geven nu dezelfde cijfers als de pagina's van de app. Daarvoor zijn enkele velden en standaardwaarden gewijzigd — pas opgeslagen aanroepen en scripts aan:

• run_monte_carlo, run_monte_carlo_mix, run_monte_carlo_community: de velden heten zoals in de opgeslagen Monte Carlo-instellingen (horizon_years → horizont_jahre, start_capital → startkapital, block_months → block_monate, tax → steuer); alter_heute is nieuw. Onbekende velden worden geweigerd in plaats van genegeerd.
• get_exchange_rates: de koersen volgen nu de richting van de app, 1 EUR = X vreemde valuta — eerder was het het omgekeerde.
• get_top_portfolios_leaderboard: dezelfde ranglijsten als de pagina Community-backtests (sharpe_ratio, sortino_ratio, calmar_ratio, sterling_ratio, martin_ratio, recovery_ratio, standaard sharpe_ratio); cagr, ulcer en max_drawdown vervallen.
• list_community_portfolios: zonder parameters één pagina van de zoekopdracht zoals op de Monte Carlo-pagina (10 items, langste koershistorie eerst) met total — in plaats van maximaal 200 op Sharpe.
• get_table_detail: weight_pct en distribution_type vervallen (ze waren altijd leeg); de velden van de pagina van de backtestset komen erbij.
• list_my_favorite_portfolios: nieuw veld metrics met de kengetallen van de eigen backtest, zoals Mijn portefeuilles ze toont; leaderboard_metrics blijft apart.
• run_simulation: standaardwaarden zoals het formulier van de pagina (minimaal 2 effecten, stapgrootte volgens je abonnement); een sjabloon geldt voor elk veld dat je niet meegeeft.
• list_watchlist, compare_watchlist_securities, get_security_price_history: dezelfde effecten als de watchlist (ook testgegevens en gedeelde mappen); zonder opgave geldt het tijdvenster van je tegel.

ulcer_index staat nu in procentpunten, net als max_drawdown (7,65 in plaats van 0,0765). sortino_ratio middelt de gekwadrateerde verliezen over alle dagen in plaats van alleen over de verliesdagen, zoals gebruikelijk is; de waarde valt daardoor ongeveer anderhalf keer zo hoog uit. Dit geldt voor elke tool die deze kengetallen levert, en voor opgeslagen backtests en portefeuilles zodra ze opnieuw zijn berekend.

Voor OAuth-clients worden de metadata aangeboden op de standaardpaden volgens RFC 8414 / RFC 9728:

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

Het programmatische oppervlak van Paperball is MCP-first. Een machineleesbaar OpenAPI-document van de publieke REST-endpoints (alleen whitelist, zonder interne routes) vind je hier: openapi.json