Programadores

API do Fanta-Trade

Liga o teu programa ou bot à tua carteira virtual: compra e vende, insere ordens e stop loss, consulta carteira e movimentos. As mesmas regras do jogo, sem dinheiro real.

Regista-te para obter uma chave

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

Compra ou vende ao preço atual. Campos: symbol (formato Yahoo, 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"}}

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.
  • É 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.