Programadores · API REST de paper trading

Treina o teu algoritmo, desafia a comunidade

Liga o teu programa, o teu bot ou a tua IA à tua carteira virtual do Fanta-Trade: opera com preços reais e dinheiro virtual, mede os resultados e compara-os com milhares de investidores e com a Fanta-AI. As mesmas regras para todos, sem dinheiro real.

Um verdadeiro banco de ensaio

Preços reais das bolsas de todo o mundo, 100.000 € virtuais e as mesmas regras para todos: liquidez, peso máximo de um título, limite de volume, ordens na abertura. O teu algoritmo opera como operaria no mercado, sem arriscar um euro.

Compara-te com a comunidade

O teu bot entra nas classificações semanal e geral ao lado de milhares de investidores de carne e osso. Com a API das classificações vês a qualquer momento a posição, a rentabilidade e a queda máxima, e comparas com os outros.

Desafia a Fanta-AI

A Fanta-AI, o investidor artificial do Fanta-Trade, está na classificação: todos os dias um modelo de machine learning escolhe os seus títulos. O teu modelo consegue batê-lo?

Ligas entre algoritmos

Cria uma liga privada e convida amigos, colegas ou estudantes com os seus bots: classificação da liga, temporadas e reinícios para todos recomeçarem do mesmo ponto.

Para cursos e laboratórios

Ciência de dados, machine learning e finanças quantitativas: os estudantes escrevem um algoritmo, testam-no no mercado real durante semanas e medem os resultados. Com o perfil Edu os docentes acompanham as turmas.

Também com critérios éticos

Cada ação mostra as suas atividades sensíveis (armas, tabaco, combustíveis fósseis...): podes excluí-las do teu algoritmo e ver no gráfico da carteira como corre a parte ética.

Para quem treina IA e algoritmos de trading

Trading algorítmico, quant, ciência de dados: o Fanta-Trade é um ambiente de paper trading gratuito, com preços reais de milhares de ações e ETF, onde um bot ou uma inteligência artificial opera com as mesmas regras de um investidor humano.

Forward test depois do backtest

O backtest sobre o passado não basta: o paper trading com preços reais é o teste fora da amostra (out-of-sample) que mostra se o modelo aguenta com dados que nunca viu, sem sobreajuste (overfitting) nem viés de sobrevivência.

Machine learning e aprendizagem por reforço

Um ambiente real para o teu modelo: treina uma rede neural, um modelo LightGBM ou um agente de aprendizagem por reforço e põe-no a operar no mercado real com estado, recompensa e restrições de liquidez realistas.

Agentes de IA e LLM

Liga um agente baseado num modelo de linguagem (LLM) com function calling: a API REST em JSON é simples de descrever como ferramentas, e o agente pode ler a carteira, decidir e colocar ordens sozinho.

Métricas e benchmarks

Rentabilidade e queda máxima (drawdown) a partir da classificação, comparação com a comunidade e com a Fanta-AI: mede o teu modelo face a um benchmark, não só pela rentabilidade absoluta. Lendo /account todos os dias reconstróis a curva de capital e calculas o índice de Sharpe e a volatilidade.

Do backtest ao paper trading: treina, testa, mede, melhora

  1. TreinaTreina o teu modelo offline, com os teus dados e as tuas ferramentas (Python, R, o que preferires).
  2. Testa ao vivoLiga o modelo à tua carteira com a API: compra, vende, coloca ordens e stop loss com os preços de hoje, não com os do passado.
  3. MedeLê a rentabilidade, as posições e os movimentos, e compara o teu bot com a comunidade e com a Fanta-AI através das classificações.
  4. MelhoraMuda o modelo e recomeça: no perfil podes repor a conta a zero e recomeçar com 100.000 € para uma nova experiência.

Exemplo em Python: um bot de trading em poucas linhas

Um bot que lê a sua carteira, opera com base nos sinais do teu modelo e verifica a sua posição na classificação em relação à Fanta-AI. A API não fornece cotações nem históricos: os dados para treinar o modelo trazes tu.

import requests

API = "https://www.fanta-trade.eu/api/v1"
H = {"Authorization": "Bearer ft_la_tua_chiave"}

def get(path, **params):
    r = requests.get(API + path, headers=H, params=params, timeout=20)
    r.raise_for_status()
    return r.json()["data"]

# 1. il tuo modello decide (con i tuoi dati e i tuoi segnali)
account = get("/account")
held = {p["symbol"]: p for p in get("/portfolio")["positions"]}
signals = {"ENI.MI": 0.8, "AAPL": -0.4}          # es. le previsioni del tuo modello

# 2. il bot opera con le regole del gioco
for symbol, score in signals.items():
    if score > 0.5 and symbol not in held:
        requests.post(API + "/trades", headers=H, timeout=20,
                      json={"symbol": symbol, "side": "buy", "quantity": 100})
    elif score < 0 and symbol in held:
        requests.post(API + "/trades", headers=H, timeout=20,
                      json={"symbol": symbol, "side": "sell", "quantity": held[symbol]["quantity"]})

# 3. misura: dove sei rispetto alla community e a Fanta-AI?
lb = get("/leaderboard", board="week", limit=10)
print("Tu:", lb["you"]["position"], "di", lb["players"], lb["you"]["return_pct"], "%")
print("Fanta-AI:", lb["fanta_ai"]["position"], lb["fanta_ai"]["return_pct"], "%")

1. Cria uma chave

Inicia sessão e vai a Perfil › API: dá um nome à chave e copia-a logo, porque só é mostrada uma vez. Podes ter até 3 e revogá-las a qualquer momento.

2. Autenticação

Envia a chave em cada pedido com o cabeçalho Authorization (ou X-API-Key). As respostas são em JSON: os dados em «data», os erros em «error» com um código e uma mensagem.

curl -H "Authorization: Bearer ft_la_tua_chiave" https://www.fanta-trade.eu/api/v1/account

Endereço base: https://www.fanta-trade.eu/api/v1 · montantes e preços em euros, datas no formato ISO 8601

3. Endpoints

GET /api/v1/account

A tua conta: liquidez, valor investido, valor total, rendimento desde o início, número de posições e de ordens pendentes.

Exemplo de resposta
{"data":{"id":42,"name":"Marco Rossi","currency":"EUR","cash":22226.49,"invested":77870.2,"total":100096.69,"performance_pct":0.1,"positions":8,"open_orders":2,"starting_capital":100000.0}}

GET /api/v1/portfolio

As posições abertas com quantidade, preço médio de compra, último preço, valor, ganho ou perda e peso na carteira.

Exemplo de resposta
{"data":{"currency":"EUR","cash":22226.49,"total":100096.69,"positions":[{"symbol":"ENI.MI","name":"Eni","quantity":400.0,"avg_price":15.12,"price":15.48,"currency":"EUR","value":6192.0,"pl":144.0,"pl_pct":2.38,"weight_pct":6.19}]}}

GET /api/v1/transactions?limit=50&offset=0

Os teus movimentos, do mais recente (no máximo 100 por pedido).

Exemplo de resposta
{"data":{"total":37,"limit":50,"offset":0,"items":[{"id":901,"date":"2026-10-14T10:02:11+02:00","symbol":"ENI.MI","name":"Eni","side":"buy","quantity":100.0,"price":15.48,"currency":"EUR","amount":1548.0,"realized_pl":null,"cash_after":22226.49}]}}

POST /api/v1/trades

Compre ou venda ao preço atual. Campos: symbol (com o sufixo da bolsa, ex. ENI.MI, AAPL), side (buy ou sell), quantity.

curl -X POST -H "Authorization: Bearer ft_la_tua_chiave" -H "Content-Type: application/json" \
  -d '{"symbol":"ENI.MI","side":"buy","quantity":100}' https://www.fanta-trade.eu/api/v1/trades
Exemplo de resposta
{"data":{"message":"…","transaction":{"id":902,"symbol":"ENI.MI","side":"buy","quantity":100.0,"price":15.48,"amount":1548.0}}}

GET /api/v1/orders

As ordens pendentes. type vale buy_limit (compra se descer), buy_stop (compra se subir), stop_loss (vende se descer) ou take_profit (vende se subir).

Exemplo de resposta
{"data":[{"id":55,"symbol":"ENI.MI","side":"sell","type":"stop_loss","quantity":100.0,"price":14.5,"currency":"EUR","status":"open","created_at":"…","expires_at":"…"}]}

POST /api/v1/orders

Insere uma ordem «comprar a / vender a»: é executada quando o preço atinge price (em euros). Uma venda abaixo do preço atual é um stop loss, acima é uma realização de lucro. expiry: 1w, 1m (predefinido) ou 3m.

curl -X POST -H "Authorization: Bearer ft_la_tua_chiave" -H "Content-Type: application/json" \
  -d '{"symbol":"ENI.MI","side":"sell","quantity":100,"price":14.50,"expiry":"1m"}' https://www.fanta-trade.eu/api/v1/orders
Exemplo de resposta
{"data":{"id":56,"symbol":"ENI.MI","side":"sell","type":"stop_loss","quantity":100.0,"price":14.5,"status":"open"}}

DELETE /api/v1/orders/{id}

Cancela uma ordem pendente.

curl -X DELETE -H "Authorization: Bearer ft_la_tua_chiave" https://www.fanta-trade.eu/api/v1/orders/56
Exemplo de resposta
{"data":{"id":56,"status":"cancelled"}}

GET /api/v1/leaderboard?board=week&limit=50&offset=0

A classificação: board=week (rentabilidade desde segunda-feira) ou overall (desde a inscrição, com a queda máxima). Em «you» está a tua posição, em «fanta_ai» a da Fanta-AI, o investidor artificial do Fanta-Trade. Os nomes são abreviados como na classificação pública e quem não quer aparecer é «anonymous».

Exemplo de resposta
{"data":{"board":"week","week_start":"2026-11-09","players":456,"limit":50,"offset":0,"you":{"position":37,"name":"Marco Rossi","is_you":true,"is_ai":false,"total":101250.4,"return_pct":1.25,"gain":1250.4,"previous_position":52},"fanta_ai":{"position":21,"name":"Fanta-AI","is_you":false,"is_ai":true,"total":102480.1,"return_pct":2.73,"gain":2726.3,"previous_position":null},"items":[{"position":1,"name":"Emilie D.","is_you":false,"is_ai":false,"total":106556.9,"return_pct":7.0,"gain":6556.96,"previous_position":4}]}}

GET /api/v1/portfolios

As tuas carteiras (com a funcionalidade «Várias carteiras»): id, nome, se conta na classificação, liquidez, valor e rendimento. Acrescenta o parâmetro portfolio=ID (no endereço ou no corpo JSON) a qualquer pedido para ler e operar nessa carteira; sem ele, usa-se a principal.

Exemplo de resposta
{"data":{"enabled":true,"max":5,"items":[{"id":42,"name":"main","main":true,"ranked":true,"cash":22226.49,"total":100096.69,"performance_pct":0.1},{"id":25101,"name":"Dividendi","main":false,"ranked":false,"cash":100000.0,"total":100000.0,"performance_pct":0.0}]}}

4. Erros

HTTPCódigoQuando
400invalid_symbol · invalid_side · invalid_quantity · invalid_priceCampos em falta ou inválidos.
401unauthorizedChave em falta, errada ou revogada.
404not_foundEndpoint inexistente, ou ordem não encontrada ou já fechada.
422trade_rejected · order_rejectedA operação não respeita as regras do jogo (liquidez, limites, preço indisponível): a mensagem explica o motivo.
429rate_limited · trade_limit · symbol_limitFoi ultrapassado um dos limites abaixo. O cabeçalho Retry-After indica quantos segundos esperar.

5. Limites e uso correto

  • 30 pedidos por minuto e 1.000 por dia por chave (os cabeçalhos X-RateLimit-* mostram quantos restam).
  • 50 operações e ordens por dia, incluindo as recusadas.
  • No máximo 10 títulos diferentes por dia que ainda não tenhas na carteira para comprar, vender ou inserir ordens; com os títulos que possuis podes operar livremente.
  • Aplicam-se todas as regras do jogo: liquidez disponível, peso máximo de um título na carteira, limite de volume diário e no máximo 50 ordens pendentes.
  • A API só dá acesso à tua conta. Não fornece cotações, pesquisas nem históricos: os preços só aparecem para os títulos que possuis e são os últimos registados pelo Fanta-Trade, que podem ter atraso.
  • Uma conta por pessoa: o bot opera na tua carteira e aparece na classificação com o teu nome. Para recomeçar do zero com um novo algoritmo, repõe a conta a zero no perfil.
  • É proibido usar a API para recolher ou redistribuir dados de mercado: em caso de abuso as chaves são revogadas e a conta pode ser suspensa.