PaperballPaperball

Deweloperzy i API

Połącz Paperball z asystentami AI i własnymi narzędziami. Dostęp programowy odbywa się przez serwer MCP — za pomocą OAuth (np. claude.ai) lub osobistego klucza API.

Co możesz z tym zrobić

  • Wyświetlać swoje zestawy do backtestu i portfele oraz odczytywać ich szczegóły
  • Uruchamiać backtesty (symulacje) oraz pobierać lub porównywać wyniki
  • Odpytywać publiczne Community-Backtests i aktualne kursy walut
  • Odpytywać swoje konto i limity subskrypcji (whoami)
  • Tworzyć zestawy do backtestu, zapisywać portfele z wyników, uruchamiać symulacje Monte Carlo i zarządzać szablonami, listami i folderami
  • Wyświetlanie Twoich papierów, uzupełnianie kursów z plików jako usuwalnych pakietów i ręczne ustawianie danych podstawowych (np. TER)
  • Usuwanie tylko z uprawnieniem „Usuwanie” (delete), tylko jako właściciel lub administrator konta i tylko wtedy, gdy jest włączone dla konta w Ustawienia → Klucze API — inaczej asystent w ogóle nie widzi narzędzi do usuwania

Każdy klucz jest powiązany z Twoim kontem i działa w Twoim imieniu. Dostępne zakresy: odczyt (read), uruchamianie symulacji (run_simulation), zarządzanie papierami (watchlist:write — przesyłanie kursów, ustawianie danych podstawowych) i usuwanie (delete — nadają je tylko właściciele i administratorzy konta, zob. „Usuwanie”). Backtesty, symulacje Monte Carlo i aktualizacje zużywają kredyty z twojego salda.

Szybki start: utwórz klucz

Utwórz osobisty klucz API w ustawieniach konta w sekcji „Klucze API”. Klucz zaczyna się od sk_ppf_ i jest pokazywany tylko raz — skopiuj go od razu.

Przejdź do zarządzania kluczami

Połącz claude.ai (OAuth)

W claude.ai przejdź do Ustawienia → Connectors i dodaj niestandardowy konektor z tym adresem URL MCP. Pola OAuth pozostaw puste — rejestracja odbywa się automatycznie (Dynamic Client Registration). Przy pierwszym połączeniu potwierdzasz dostęp do swojego konta.

https://www.paperball.finance/mcp

Klucz API nie jest potrzebny — połączenie odbywa się przez OAuth 2.1 z PKCE i pojawia się następnie w „Połączone aplikacje”.

Połącz Claude Desktop (klucz)

Dodaj poniższy blok do pliku claude_desktop_config.json i zastąp sk_ppf_… swoim kluczem. mcp-remote łączy lokalny transport stdio z serwerem MCP przez 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_..." }
    }
  }
}

n8n, Make i własne skrypty

Każdy klient HTTP obsługujący MCP może łączyć się z endpointem bezpośrednio — przez Streamable HTTP z Twoim kluczem w nagłówku 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

Usuwanie

Narzędzia usuwające pojawiają się w tools/list tylko przy trzech warunkach: klucz ma uprawnienie „delete”, należy do właściciela lub administratora konta, a „Usuwanie przez asystentów AI i API” jest włączone w Ustawienia → Klucze API (domyślnie: wyłączone). Usunąć można tylko to, co nie jest jeszcze w użyciu.

Istniejące klucze i połączenia nie mają uprawnienia „Usuwanie”. Utwórz nowy klucz z opcją „Zezwalaj na usuwanie” albo połącz asystenta ponownie i potwierdź usuwanie.

Zmienione narzędzia (28.10.2026)

Narzędzia zwracają teraz te same liczby co strony aplikacji. W tym celu zmieniły się niektóre pola i wartości domyślne — dostosuj zapisane wywołania i skrypty:

  • run_monte_carlo, run_monte_carlo_mix, run_monte_carlo_community: pola nazywają się jak w zapisanych ustawieniach Monte Carlo (horizon_years → horizont_jahre, start_capital → startkapital, block_months → block_monate, tax → steuer); nowe jest alter_heute. Nieznane pola są odrzucane zamiast pomijane.
  • get_exchange_rates: kursy są teraz w kierunku aplikacji, 1 EUR = X waluty obcej — wcześniej była to odwrotność.
  • get_top_portfolios_leaderboard: te same rankingi co strona Backtesty społeczności (sharpe_ratio, sortino_ratio, calmar_ratio, sterling_ratio, martin_ratio, recovery_ratio, domyślnie sharpe_ratio); cagr, ulcer i max_drawdown odpadają.
  • list_community_portfolios: bez parametrów jedna strona wyszukiwania jak na stronie Monte Carlo (10 pozycji, najpierw najdłuższa historia kursów) z total — zamiast do 200 według Sharpe’a.
  • get_table_detail: weight_pct i distribution_type odpadają (zawsze były puste); dochodzą pola strony zestawu do backtestu.
  • list_my_favorite_portfolios: nowe pole metrics ze wskaźnikami własnego backtestu, tak jak pokazuje je strona Moje portfele; leaderboard_metrics pozostaje osobno.
  • run_simulation: wartości domyślne jak w formularzu strony (co najmniej 2 papiery, krok według twojego planu); szablon obowiązuje dla każdego pola, którego nie przekażesz.
  • list_watchlist, compare_watchlist_securities, get_security_price_history: te same papiery co na watchliście (także dane testowe i udostępnione foldery); bez podania okno czasowe jest takie jak na twoim kafelku.

Zmienione wskaźniki (30.10.2026)

ulcer_index jest teraz podawany w punktach procentowych, jak max_drawdown (7,65 zamiast 0,0765). sortino_ratio uśrednia kwadraty strat ze wszystkich dni, a nie tylko z dni ze stratą, jak to jest przyjęte; dzięki temu wartość jest mniej więcej półtora raza wyższa. Dotyczy to każdego narzędzia, które zwraca te wskaźniki, oraz zapisanych backtestów i portfeli, gdy tylko zostaną przeliczone.

OAuth discovery

Dla klientów OAuth metadane są udostępniane pod standardowymi ścieżkami zgodnie z RFC 8414 / RFC 9728:

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

Schemat OpenAPI

Powierzchnia programistyczna Paperball jest MCP-first. Tutaj znajdziesz czytelny maszynowo dokument OpenAPI publicznych endpointów REST (tylko whitelist, bez tras wewnętrznych): openapi.json