PaperballPaperball

Programadores e API

Liga o Paperball a assistentes de IA e às tuas próprias ferramentas. O acesso programático funciona através do servidor MCP — via OAuth (p. ex. claude.ai) ou com uma chave API pessoal.

O que podes fazer com isto

  • Listar os teus conjuntos de backtest e carteiras e lê-los em detalhe
  • Iniciar backtests (simulações) e obter ou comparar resultados
  • Consultar Community-Backtests públicos e taxas de câmbio atuais
  • Consultar a tua conta e os limites da subscrição (whoami)
  • Criar conjuntos de backtest, guardar carteiras a partir de resultados, executar simulações de Monte Carlo e gerir modelos, listas e pastas
  • Listar os teus títulos, completar cotações a partir de ficheiros como pacotes elimináveis e definir dados mestres (p. ex. TER) manualmente
  • Eliminar só com a permissão «Eliminar» (delete), só como titular ou administrador da conta e só se estiver ligado para a conta em Definições → Chaves API — caso contrário, o assistente nem vê as ferramentas de eliminação

Cada chave está associada à tua conta e age em teu nome. Scopes disponíveis: ler (read), executar simulações (run_simulation), gerir títulos (watchlist:write — carregar cotações, definir dados mestres) e eliminar (delete — só concedido por titulares e administradores da conta, vê «Eliminar»). Os backtests, as simulações de Monte Carlo e as atualizações consomem créditos do teu saldo.

Início rápido: criar uma chave

Cria uma chave API pessoal nas definições da tua conta, em «Chaves API». A chave começa por sk_ppf_ e é mostrada apenas uma vez — copia-a de imediato.

Ir para a gestão de chaves

Ligar o claude.ai (OAuth)

No claude.ai, vai a Definições → Connectors e adiciona um conector personalizado com este URL de MCP. Deixa os campos OAuth vazios — o registo é automático (Dynamic Client Registration). Na primeira ligação confirmas o acesso à tua conta.

https://www.paperball.finance/mcp

Não é preciso chave API — a ligação é feita via OAuth 2.1 com PKCE e aparece depois em «Aplicações ligadas».

Ligar o Claude Desktop (chave)

Adiciona o seguinte bloco ao teu claude_desktop_config.json e substitui sk_ppf_… pela tua chave. O mcp-remote faz a ponte entre o transporte local stdio e o servidor MCP por 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 e os teus scripts

Qualquer cliente HTTP compatível com MCP pode aceder ao endpoint diretamente — via Streamable HTTP com a tua chave no cabeçalho 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

Eliminar

As ferramentas que eliminam só aparecem em tools/list quando se cumprem três condições: a chave tem a permissão «delete», pertence a um titular ou administrador da conta, e «Eliminar através de assistentes de IA e da API» está ligado em Definições → Chaves API (predefinição: desligado). Só se pode eliminar o que ainda não está em uso.

As chaves e ligações existentes não têm a permissão «Eliminar». Cria uma chave nova com «Permitir eliminar» ou volta a ligar o assistente e confirma a eliminação.

Ferramentas alteradas (28/10/2026)

As ferramentas devolvem agora os mesmos números que as páginas da app. Para isso, alguns campos e valores predefinidos mudaram — ajusta as chamadas e os scripts guardados:

  • run_monte_carlo, run_monte_carlo_mix, run_monte_carlo_community: os campos chamam-se como nas definições de Monte Carlo guardadas (horizon_years → horizont_jahre, start_capital → startkapital, block_months → block_monate, tax → steuer); alter_heute é novo. Campos desconhecidos são recusados em vez de ignorados.
  • get_exchange_rates: as taxas seguem agora a direção da app, 1 EUR = X moeda estrangeira — antes era o inverso.
  • get_top_portfolios_leaderboard: as mesmas classificações da página Backtests da comunidade (sharpe_ratio, sortino_ratio, calmar_ratio, sterling_ratio, martin_ratio, recovery_ratio, predefinição sharpe_ratio); cagr, ulcer e max_drawdown deixam de existir.
  • list_community_portfolios: sem parâmetros, uma página da pesquisa como na página Monte Carlo (10 entradas, histórico de cotações mais longo primeiro) com total — em vez de até 200 por Sharpe.
  • get_table_detail: weight_pct e distribution_type deixam de existir (estavam sempre vazios); juntam-se os campos da página do conjunto de backtest.
  • list_my_favorite_portfolios: novo campo metrics com os indicadores do próprio backtest, como Os meus portfólios os mostra; leaderboard_metrics fica à parte.
  • run_simulation: valores predefinidos como no formulário da página (mínimo 2 títulos, passo conforme o teu plano); um modelo aplica-se a cada campo que não envies.
  • list_watchlist, compare_watchlist_securities, get_security_price_history: os mesmos títulos que a watchlist (também dados de teste e pastas partilhadas); sem indicação, a janela temporal é a do teu cartão.

Indicadores alterados (30/10/2026)

ulcer_index passa a ser indicado em pontos percentuais, como max_drawdown (7,65 em vez de 0,0765). sortino_ratio calcula a média das perdas ao quadrado em todos os dias e não apenas nos dias de perda, como é habitual; o valor fica assim cerca de uma vez e meia mais alto. Isto aplica-se a todas as ferramentas que devolvem estes indicadores, e aos backtests e carteiras guardados assim que forem recalculados.

OAuth discovery

Para clientes OAuth, os metadados são disponibilizados nos caminhos padrão conforme RFC 8414 / RFC 9728:

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

Esquema OpenAPI

A superfície programática do Paperball é MCP-first. Aqui encontras um documento OpenAPI legível por máquina dos endpoints REST públicos (apenas whitelist, sem rotas internas): openapi.json