Skip to main content

​
📖 Descrição

Endpoint que calcula pontualmente o PNL (Profit and Loss) atual de uma posição de arbitragem spot-futuro. Busca os preços de mercado mais recentes da coleção operations_future (com cache de 55 segundos) e recalcula o PNL em relação aos dados de entrada salvos.
Para monitoramento contínuo da posição, use GET /v1/calculators/stream em vez deste endpoint. O stream SSE elimina o polling e reduz a latência para ~1 segundo com menor sobrecarga no servidor.

​
🛠️ Requisição

​
Método

POST

​
URL

/v1/calculators/process

​
Request Body

CampoTipoObrigatórioDescrição
emailstringSimEmail do usuário dono da posição
tickerstringSimPar de trading (ex: BTC-USDT)
exchangestringSimExchange da posição (ex: binance)

​
Exemplo de Requisição

curl -X POST http://localhost:8080/v1/calculators/process \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "ticker": "BTC-USDT",
    "exchange": "binance"
  }'

​
📤 Resposta

​
Exemplo de Resposta (200 OK)

{
  "email": "user@example.com",
  "ticker": "BTC-USDT",
  "exchange": "binance",
  "entrySpotValue": 83000.00,
  "entryShortValue": 83150.00,
  "entrySpotQty": 0.1,
  "entryFuturesQty": 0.1,
  "entrySpread": 150.00,
  "entrySpreadPercentage": 0.18,
  "currentSpotPrice": 85400.00,
  "currentFuturePrice": 85450.00,
  "currentSpread": 50.00,
  "currentSpreadPercentage": 0.058,
  "fundingRate": 0.0001,
  "pnl": 42.50,
  "pnlPercentage": 0.026,
  "isProfitable": true
}

​
Campos da Resposta

CampoTipoDescrição
emailstringEmail do usuário
tickerstringPar de trading
exchangestringExchange
entrySpotValuefloatPreço spot de entrada
entryShortValuefloatPreço futuro de entrada
entrySpotQtyfloatQuantidade spot
entryFuturesQtyfloatQuantidade futuro
entrySpreadfloatSpread na abertura
entrySpreadPercentagefloatSpread na abertura em %
currentSpotPricefloatPreço spot atual
currentFuturePricefloatPreço futuro atual
currentSpreadfloatSpread atual
currentSpreadPercentagefloatSpread atual em %
fundingRatefloatTaxa de funding atual
pnlfloatPNL total em USDT
pnlPercentagefloatPNL em % sobre o capital
isProfitablebooleantrue se pnl > 0

​
📝 Códigos de Resposta

200 OK: PNL calculado com sucesso.
400 Bad Request:
  • Invalid request body: JSON malformado
  • email is required
  • ticker is required
  • exchange is required
404 Not Found:
  • calculator not found: Não há posição salva para email + ticker. Salve via POST /v1/calculators primeiro.
  • market data not found: Não há dados de mercado recentes (últimos 20 min) para o par na exchange.
500 Internal Server Error: Failed to process calculator — Erro interno.

​
💡 Cache de Dados de Mercado

Internamente, o endpoint usa um cache de 55 segundos por ticker + exchange. Isso significa que chamadas feitas dentro desse intervalo reutilizam o mesmo dado, evitando queries repetidas ao MongoDB. A primeira chamada após o TTL faz uma nova query à coleção operations_future. Para dados mais frescos (atualização a cada 5s), use GET /v1/calculators/stream.

​
🔁 Fórmula do PNL

spotValueChange    = (currentSpotPrice − entrySpotValue) × entrySpotQty
futureValueChange  = (entryShortValue − currentFuturePrice) × entryFuturesQty
PNL                = spotValueChange + futureValueChange

entryTotalValue    = (entrySpotValue × entrySpotQty) + (entryShortValue × entryFuturesQty)
PNLPercentage      = (PNL / entryTotalValue) × 100