Desarrolladores y API

• Listar tus sets de backtest y carteras y leerlos en detalle
• Iniciar backtests (simulaciones) y obtener o comparar resultados
• Consultar Community-Backtests públicos y tipos de cambio actuales
• Consultar tu cuenta y los límites de tu suscripción (whoami)
• Crear sets de backtest, guardar carteras a partir de resultados, ejecutar simulaciones de Montecarlo y gestionar plantillas, listas y carpetas
• Listar tus valores, completar cotizaciones desde archivos como paquetes eliminables y fijar datos maestros (p. ej. TER) manualmente
• Borrar solo con el permiso «Eliminar» (delete), solo como titular o administrador de la cuenta y solo si está activado para la cuenta en Ajustes → Claves API; si no, el asistente ni siquiera ve las herramientas de borrado

Cada clave está vinculada a tu cuenta y actúa en tu nombre. Scopes disponibles: leer (read), ejecutar simulaciones (run_simulation), gestionar valores (watchlist:write — subir cotizaciones, fijar datos maestros) y eliminar (delete — solo lo conceden titulares y administradores de la cuenta, consulta «Eliminar»). Los backtests, las simulaciones de Monte Carlo y las actualizaciones consumen créditos de tu saldo.

Crea una clave API personal en la configuración de tu cuenta, en «Claves API». La clave empieza por sk_ppf_ y se muestra solo una vez — cópiala de inmediato.

En claude.ai, ve a Ajustes → Connectors y añade un conector personalizado con esta URL de MCP. Deja los campos de OAuth vacíos: el registro es automático (Dynamic Client Registration). En la primera conexión confirmas el acceso a tu cuenta.

https://www.paperball.finance/mcp

No necesitas clave API: la conexión se establece mediante OAuth 2.1 con PKCE y luego aparece en «Aplicaciones conectadas».

Añade el siguiente bloque a tu claude_desktop_config.json y sustituye sk_ppf_… por tu clave. mcp-remote conecta el transporte local stdio con el 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_..." }
    }
  }
}

Cualquier cliente HTTP compatible con MCP puede acceder al endpoint directamente — mediante Streamable HTTP con tu clave en la cabecera 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

Las herramientas que eliminan solo aparecen en tools/list si se cumplen tres condiciones: la clave tiene el permiso «delete», pertenece a un titular o administrador de la cuenta, y «Eliminar mediante asistentes de IA y la API» está activado en Ajustes → Claves API (predeterminado: desactivado). Solo se puede eliminar lo que aún no está en uso.

Las claves y conexiones existentes no tienen el permiso «Eliminar». Crea una clave nueva con «Permitir eliminar» o vuelve a conectar el asistente y confirma la eliminación.

Las herramientas devuelven ahora las mismas cifras que las páginas de la app. Para ello han cambiado algunos campos y valores predeterminados; adapta tus llamadas y scripts guardados:

• run_monte_carlo, run_monte_carlo_mix, run_monte_carlo_community: los campos se llaman como en los ajustes de Monte Carlo guardados (horizon_years → horizont_jahre, start_capital → startkapital, block_months → block_monate, tax → steuer); alter_heute es nuevo. Los campos desconocidos se rechazan en lugar de ignorarse.
• get_exchange_rates: los tipos de cambio siguen ahora la dirección de la app, 1 EUR = X moneda extranjera; antes era el inverso.
• get_top_portfolios_leaderboard: las mismas clasificaciones que la página Backtests de la comunidad (sharpe_ratio, sortino_ratio, calmar_ratio, sterling_ratio, martin_ratio, recovery_ratio, por defecto sharpe_ratio); desaparecen cagr, ulcer y max_drawdown.
• list_community_portfolios: sin parámetros, una página de la búsqueda como en la página Monte Carlo (10 entradas, el historial de precios más largo primero) con total, en lugar de hasta 200 por Sharpe.
• get_table_detail: desaparecen weight_pct y distribution_type (siempre estaban vacíos); se añaden los campos de la página del conjunto de backtest.
• list_my_favorite_portfolios: nuevo campo metrics con las métricas del backtest propio, como las muestra Mis carteras; leaderboard_metrics queda aparte.
• run_simulation: valores predeterminados como en el formulario de la página (mínimo 2 valores, paso según tu plan); una plantilla se aplica a cada campo que no envíes.
• list_watchlist, compare_watchlist_securities, get_security_price_history: los mismos valores que la watchlist (también datos de prueba y carpetas compartidas); sin indicarla, la ventana temporal es la de tu tarjeta.

ulcer_index se expresa ahora en puntos porcentuales, como max_drawdown (7,65 en lugar de 0,0765). sortino_ratio promedia las pérdidas al cuadrado sobre todos los días en lugar de solo los días con pérdidas, como es habitual; por eso el valor resulta aproximadamente una vez y media más alto. Esto se aplica a todas las herramientas que devuelven estas métricas, y a los backtests y carteras guardados en cuanto se hayan recalculado.

Para clientes OAuth, los metadatos se ofrecen en las rutas estándar según RFC 8414 / RFC 9728:

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

La superficie programática de Paperball es MCP-first. Aquí encuentras un documento OpenAPI legible por máquina de los endpoints REST públicos (solo lista blanca, sin rutas internas): openapi.json