Processar Calculadora (Consulta Pontual)

📖 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

Campo	Tipo	Obrigatório	Descrição
`email`	string	Sim	Email do usuário dono da posição
`ticker`	string	Sim	Par de trading (ex: `BTC-USDT`)
`exchange`	string	Sim	Exchange 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

Campo	Tipo	Descrição
`email`	string	Email do usuário
`ticker`	string	Par de trading
`exchange`	string	Exchange
`entrySpotValue`	float	Preço spot de entrada
`entryShortValue`	float	Preço futuro de entrada
`entrySpotQty`	float	Quantidade spot
`entryFuturesQty`	float	Quantidade futuro
`entrySpread`	float	Spread na abertura
`entrySpreadPercentage`	float	Spread na abertura em %
`currentSpotPrice`	float	Preço spot atual
`currentFuturePrice`	float	Preço futuro atual
`currentSpread`	float	Spread atual
`currentSpreadPercentage`	float	Spread atual em %
`fundingRate`	float	Taxa de funding atual
`pnl`	float	PNL total em USDT
`pnlPercentage`	float	PNL em % sobre o capital
`isProfitable`	boolean	`true` 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

API Documentation

Endpoint Examples

Processar Calculadora (Consulta Pontual)

📖 Descrição

🛠️ Requisição

Método

URL

Request Body

Exemplo de Requisição

📤 Resposta

Exemplo de Resposta (200 OK)

Campos da Resposta

📝 Códigos de Resposta

💡 Cache de Dados de Mercado

🔁 Fórmula do PNL

​📖 Descrição

​🛠️ Requisição

​Método

​URL

​Request Body

​Exemplo de Requisição

​📤 Resposta

​Exemplo de Resposta (200 OK)

​Campos da Resposta

​📝 Códigos de Resposta

​💡 Cache de Dados de Mercado

​🔁 Fórmula do PNL

📖 Descrição

🛠️ Requisição

Método

URL

Request Body

Exemplo de Requisição

📤 Resposta

Exemplo de Resposta (200 OK)

Campos da Resposta

📝 Códigos de Resposta

💡 Cache de Dados de Mercado

🔁 Fórmula do PNL