Ir para o conteúdo

Referência da API

Conceitos comuns

Volume, preços, tipos de ordem e tempo em vigor

Volume

O volume é especificado em cêntimos (unidades de 0,0000001 lotes).

Lotes Volume (cêntimos)
0,01 100.000
0,1 1.000.000
1,0 10.000.000

Preços

Os valores de preço estão em pipettes. Para converter: display_price = pipette_value / 10^pipDigits

Para EURUSD (5 dígitos), um valor de pipette de 112345 = 1,12345.

Tipos de ordem

Tipo Descrição Campos obrigatórios
MARKET Executar imediatamente ao preço atual symbolId, tradeSide, volume
LIMIT Executar ao preço limite ou melhor + limitPrice
STOP Acionar quando o mercado atingir o preço stop + stopPrice
MARKET_RANGE Executar dentro de um intervalo de preços + baseSlippagePrice
STOP_LIMIT Ordem limite acionada ao preço stop + stopPrice, limitPrice

Tempo em vigor

Política Descrição
GOOD_TILL_CANCEL A ordem permanece ativa até ser executada ou cancelada
GOOD_TILL_DATE A ordem expira no expirationTimestamp especificado
IMMEDIATE_OR_CANCEL Executar o que estiver disponível imediatamente, cancelar o resto

Informações da conta

GET /v1/balance Get account balance

Devolve o saldo da conta, capital e margem livre.

Parâmetros

Sem parâmetros.

Respostas

200 Resposta bem-sucedida

Response body
{
  "balance": 10000.00,
  "equity": 10250.75,
  "freeMargin": 9800.50,
  "balanceVersion": 42,
  "moneyDigits": 2,
  "depositAssetId": 1
}
Campo Tipo Descrição
balance double Saldo da conta na moeda de depósito
equity double Saldo + P&L flutuante
freeMargin double Margem disponível para novas negociações
balanceVersion int64 Contador de versão do saldo
moneyDigits int32 Casas decimais para valores monetários
depositAssetId int64 ID do ativo da moeda de depósito
GET /v1/symbols Obter símbolos disponíveis

Devolve todos os símbolos disponíveis para negociação na conta.

Parâmetros

Sem parâmetros.

Respostas

200 Array de objetos Symbol

Response body
[
  {
    "symbolId": 1,
    "symbolName": "EURUSD",
    "enabled": true,
    "baseAssetId": 2,
    "quoteAssetId": 1,
    "description": "Euro vs US Dollar"
  }
]

Symbol

Campo Tipo Descrição
symbolId int64 ID do símbolo (usado noutras chamadas de API)
symbolName string Nome do símbolo (por exemplo, "EURUSD")
enabled boolean Se o símbolo é negociável
baseAssetId int64 ID do ativo base
quoteAssetId int64 ID do ativo de cotação
description string Descrição legível
GET /v1/assets Obter ativos disponíveis

Devolve os ativos disponíveis (moedas).

Parâmetros

Sem parâmetros.

Respostas

200 Array de objetos Asset

Response body
[
  {
    "assetId": 1,
    "name": "USD",
    "displayName": "US Dollar"
  }
]

Asset

Campo Tipo Descrição
assetId int64 ID do ativo
name string Código do ativo (por exemplo, "USD")
displayName string Nome de exibição

Dados de mercado

GET /v1/prices Obter preços spot

Devolve os preços de venda/compra atuais para os símbolos especificados. Isto é um instantâneo – a API não suporta streaming.

Parâmetros
Nome Localizado em Tipo Obrigatório Descrição
symbolId query int64[] IDs de símbolos separados por vírgulas
Respostas

200 Array de objetos SpotPrice

Response body
[
  {
    "symbolId": 1,
    "bid": 112340,
    "ask": 112355,
    "high": 112890,
    "low": 111950,
    "sessionClose": 112100,
    "timestamp": 1700000000000
  }
]

SpotPrice

Campo Tipo Descrição
symbolId int64 ID do Símbolo
bid int64 Melhor preço de venda (pipettes)
ask int64 Melhor preço de compra (pipettes)
high int64 Máximo da sessão (pipettes)
low int64 Mínimo da sessão (pipettes)
sessionClose int64 Fecho da sessão anterior (pipettes)
timestamp int64 Timestamp da cotação (epoch ms)
GET /v1/trendbars Obter dados históricos OHLCV

Devolve dados históricos de candlestick (OHLCV) para um símbolo.

Parâmetros
Nome Localizado em Tipo Obrigatório Predefinição Descrição
symbolId query int64 – ID do Símbolo
period query string – Período da barra
fromTimestamp query string – Hora de início (ISO-8601)
toTimestamp query string – Hora de fim (ISO-8601)
count query int32 100 Máximo de barras a devolver
Períodos disponíveis

M_1 M_2 M_3 M_4 M_5 M_10 M_15 M_30 H_1 H_2 H_3 H_4 H_6 H_8 H_12 D_1 W_1 MN_1

Respostas

200 Array de objetos Trendbar

Response body
[
  {
    "timestamp": 1700000000000,
    "open": 112340.0,
    "high": 112890.0,
    "low": 111950.0,
    "close": 112500.0,
    "volume": 4521
  }
]

Trendbar

Campo Tipo Descrição
timestamp int64 Hora de abertura da barra (epoch ms)
open double Preço de abertura (pipettes)
high double Preço máximo (pipettes)
low double Preço mínimo (pipettes)
close double Preço de fecho (pipettes)
volume int64 Volume de ticks

Ordens

POST /v1/orders Colocar uma nova ordem

Coloca uma nova ordem de negociação. Devolve uma ExecutionResponse.

Parâmetros

Sem parâmetros de caminho ou query.

Corpo do pedido application/json
Campo Tipo Obrigatório Descrição
symbolId int64 Símbolo a negociar
orderType string MARKET, LIMIT, STOP, MARKET_RANGE, STOP_LIMIT
tradeSide string BUY ou SELL
volume int64 Volume em cêntimos
limitPrice double Preço de limite – obrigatório para LIMIT, STOP_LIMIT
stopPrice double Preço de acionamento do stop – obrigatório para STOP, STOP_LIMIT
stopLoss double Preço de stop loss
takeProfit double Preço de take profit
comment string Comentário de texto livre (máx. 256 carateres)
label string Etiqueta do bot (máx. 100 carateres)
timeInForce string GOOD_TILL_CANCEL, GOOD_TILL_DATE, IMMEDIATE_OR_CANCEL
baseSlippagePrice double Preço base para slippage – obrigatório para MARKET_RANGE
slippageInPoints int32 Slippage máximo em pontos
expirationTimestamp int64 Timestamp de expiração (epoch ms) – para GOOD_TILL_DATE
Example request body
{
  "symbolId": 1,
  "orderType": "MARKET",
  "tradeSide": "BUY",
  "volume": 10000000,
  "stopLoss": 112000,
  "takeProfit": 113000
}
Respostas

200 ExecutionResponse – ordem aceite ou executada

400 INVALID_REQUEST ou TRADING_BAD_VOLUME

422 NOT_ENOUGH_MONEY

409 MARKET_CLOSED

Example success response
{
  "orderId": 12345,
  "positionId": 67890,
  "executionType": "ORDER_FILLED",
  "order": { "..." : "..." },
  "position": { "..." : "..." },
  "deal": { "..." : "..." }
}
GET /v1/orders Obter ordens pendentes

Devolve todas as ordens pendentes (não executadas).

Parâmetros

Sem parâmetros.

Respostas

200 Array de objetos Order pendentes

PUT /v1/orders/{orderId} Alterar uma ordem pendente

Altera uma ordem pendente existente. Devolve uma ExecutionResponse.

Parâmetros
Nome Localizado em Tipo Obrigatório Descrição
orderId path int64 A ordem a alterar
Corpo do pedido application/json

Qualquer subconjunto dos seguintes campos.

Campo Tipo Descrição
volume int64 Novo volume em cêntimos
limitPrice double Novo preço limite
stopPrice double Novo preço de stop
stopLoss double Novo preço de stop loss
takeProfit double Novo preço de take profit
expirationTimestamp int64 Novo timestamp de expiração (epoch ms)
Respostas

200 ExecutionResponse com ORDER_REPLACED

404 Ordem não encontrada

DELETE /v1/orders/{orderId} Cancelar uma ordem pendente

Cancela uma ordem pendente. Devolve uma ExecutionResponse.

Parâmetros
Nome Localizado em Tipo Obrigatório Descrição
orderId path int64 A ordem a cancelar
Respostas

200 ExecutionResponse com ORDER_CANCELLED

404 Ordem não encontrada

GET /v1/orders/history Obter histórico de ordens

Devolve ordens históricas dentro de um intervalo de tempo.

Parâmetros
Nome Localizado em Tipo Obrigatório Descrição
fromTimestamp query string Hora de início (ISO-8601)
toTimestamp query string Hora de fim (ISO-8601)
Respostas

200 OrderListResponse

Campo Tipo Descrição
orders Order[] Array de ordens históricas
hasMore boolean Se estão disponíveis páginas adicionais

Posições

GET /v1/positions Obter posições abertas

Devolve todas as posições abertas e ordens pendentes.

Parâmetros

Sem parâmetros.

Respostas

200 Array de objetos Position

Response body
[
  {
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "entryPrice": 112345.0,
    "stopLoss": 112000.0,
    "takeProfit": 113000.0,
    "unrealizedPnl": 155.25,
    "commission": -7.00,
    "swap": -1.20
  }
]

Posição

Campo Tipo Descrição
positionId int64 ID da posição
symbolId int64 ID do Símbolo
tradeSide string BUY ou SELL
volume int64 Volume em cêntimos
entryPrice double Preço de entrada VWAP
stopLoss double Preço de stop loss
takeProfit double Preço de take profit
unrealizedPnl double Lucro/prejuízo flutuante
commission double Comissão cobrada
swap double Montante de swap
GET /v1/positions/{positionId} Obter detalhes da posição

Devolve uma posição com as suas ordens e negócios relacionados.

Parâmetros
Nome Localizado em Tipo Obrigatório Descrição
positionId path int64 O ID da posição
Respostas

200 PositionDetailResponse

Campo Tipo Descrição
position Position Objeto de posição
orders Order[] Ordens relacionadas
deals Deal[] Negócios relacionados
PUT /v1/positions/{positionId} Alterar SL/TP da posição

Atualiza o stop loss e/ou take profit de uma posição aberta. Devolve uma ExecutionResponse.

Parâmetros
Nome Localizado em Tipo Obrigatório Descrição
positionId path int64 O ID da posição
Corpo do pedido application/json
Campo Tipo Descrição
stopLoss double Novo preço de stop loss (null para remover)
takeProfit double Novo preço de take profit (null para remover)
trailingStopLoss boolean Ativar trailing stop loss
Example request body
{
  "stopLoss": 111500,
  "takeProfit": 113500,
  "trailingStopLoss": false
}
Respostas

200 ExecutionResponse

POST /v1/positions/{positionId}/close Fechar uma posição

Fecha uma posição aberta total ou parcialmente. Utilize um valor inferior ao volume total da posição para um fecho parcial. Devolve uma ExecutionResponse.

Parâmetros
Nome Localizado em Tipo Obrigatório Descrição
positionId path int64 O ID da posição
Corpo do pedido application/json
Campo Tipo Obrigatório Descrição
volume int64 Volume a fechar em cêntimos
Example – full close (1 lot)
{
  "volume": 10000000
}
Respostas

200 ExecutionResponse

422 NOT_ENOUGH_MONEY – margem insuficiente para fecho parcial

Deals

GET /v1/deals Obter histórico de negócios

Devolve negócios executados dentro de um intervalo de tempo.

Parâmetros
Nome Localizado em Tipo Obrigatório Predefinição Descrição
fromTimestamp query string – Hora de início (ISO-8601)
toTimestamp query string – Hora de fim (ISO-8601)
maxRows query int32 50 Máximo de negócios a devolver
Respostas

200 Array de objetos Deal

Response body
[
  {
    "dealId": 11111,
    "orderId": 12345,
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "filledVolume": 10000000,
    "executionPrice": 112345.0,
    "executionTimestamp": 1700000000000,
    "dealStatus": "FILLED",
    "commission": -7.00
  }
]

Deal

Campo Tipo Descrição
dealId int64 ID da transação
orderId int64 Ordem que desencadeou este negócio
positionId int64 ID da posição
symbolId int64 ID do Símbolo
tradeSide string BUY ou SELL
volume int64 Volume solicitado em cêntimos
filledVolume int64 Volume completado em cêntimos
executionPrice double Preço de execução
executionTimestamp int64 Hora de execução (epoch ms)
dealStatus string Estado – ver valores abaixo
commission double Comissão cobrada

Valores de dealStatus

Valor Significado
FILLED Ordem completamente completada
PARTIALLY_FILLED Ordem completada parcialmente
REJECTED Rejeitada pelo servidor de negociação
INTERNALLY_REJECTED Rejeitada internamente antes de chegar ao servidor
ERROR Ocorreu um erro durante a execução
MISSED Ordem perdida (por exemplo, gap no mercado)

Schemas { #execution-response-schema }

ExecutionResponse

Todas as operações de colocação, alteração e cancelamento de ordens devolvem este objeto.

Campo Tipo Descrição
orderId int64 ID da ordem afetada
positionId int64 ID da posição afetada
executionType string Tipo de resultado – ver valores abaixo
order Order Detalhes da ordem (se aplicável)
position Position Detalhes da posição (se aplicável)
deal Deal Detalhes do negócio (se aplicável)

Valores de executionType

Valor Significado
ORDER_ACCEPTED Ordem pendente aceite
ORDER_FILLED Ordem completamente completada
ORDER_REPLACED Ordem alterada
ORDER_CANCELLED Ordem cancelada
ORDER_EXPIRED Ordem expirada
ORDER_REJECTED Ordem rejeitada
ORDER_CANCEL_REJECTED Pedido de cancelamento rejeitado
ORDER_PARTIAL_FILL Ordem completada parcialmente
SWAP Swap de posição aplicado
DEPOSIT Depósito na conta
WITHDRAW Levantamento da conta
BONUS_DEPOSIT_WITHDRAW Depósito ou levantamento de bónus

Limites de taxa

O gateway aplica limites de taxa a vários níveis.

Nível Descrição
Por IP Limita o total de pedidos de um único endereço IP
Por utilizador Limita o total de pedidos em todas as contas para um único token
Por conta Limita os pedidos direcionados a uma única conta de negociação

Limite de taxa excedido

Quando um limite de taxa é excedido, a API devolve 429 Too Many Requests com um cabeçalho Retry-After.

Gestão de erros

Quando um pedido falha, a API devolve uma resposta de erro JSON.

Error response format
{
  "error": {
    "code": "NOT_ENOUGH_MONEY",
    "message": "Insufficient free margin for this order",
    "httpStatus": 422,
    "retryAfter": null
  }
}

Códigos de erro

Código HTTP Descrição
INVALID_REQUEST 400 Parâmetros de pedido inválidos ou em falta
UNAUTHORIZED 401 Token inválido, expirado ou em falta
TRADING_BAD_VOLUME 400 O volume é inválido (abaixo do mínimo ou excede a posição)
NOT_ENOUGH_MONEY 422 Margem livre insuficiente
SYMBOL_NOT_FOUND 404 O ID do símbolo não existe
MARKET_CLOSED 409 O mercado para o símbolo está atualmente encerrado
MAINTENANCE 503 O servidor de negociação está em modo de manutenção
TIMEOUT 504 O servidor de negociação não respondeu a tempo
GATEWAY_RATE_LIMIT 429 Limite de taxa excedido – consulte o cabeçalho Retry-After

Tratamento de limites de taxa

Quando recebe uma resposta 429, o cabeçalho Retry-After e o campo retryAfter indicam quantos segundos tem de aguardar antes de enviar o próximo pedido.