Skip to main content

​
📖 Descrição

Endpoint que cria ou atualiza (upsert) os dados de entrada de uma posição de arbitragem spot-futuro na Calculadora. Se já existir uma entrada para o par email + ticker, ela é sobrescrita com os novos valores. Os dados de entrada são o ponto de referência para o cálculo do PNL em tempo real.
Este endpoint é o primeiro passo — registrar a posição de entrada. Depois de salvo, use GET /v1/calculators/stream para monitorar o PNL em tempo real.

​
🛠️ Requisição

​
Método

POST

​
URL

/v1/calculators

​
Request Body

CampoTipoObrigatórioDescrição
emailstringSimEmail do usuário
tickerstringSimPar de trading (ex: BTC-USDT)
entrySpotValuefloatSimPreço de entrada no mercado Spot
entryShortValuefloatSimPreço de entrada no mercado Futuro (short)
entrySpotQtyfloatSimQuantidade comprada no Spot
entryFuturesQtyfloatSimQuantidade vendida nos Futuros

​
Exemplo de Requisição

curl -X POST http://localhost:8080/v1/calculators \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "ticker": "BTC-USDT",
    "entrySpotValue": 83000.00,
    "entryShortValue": 83150.00,
    "entrySpotQty": 0.1,
    "entryFuturesQty": 0.1
  }'

​
📤 Resposta

​
Exemplo de Resposta (200 OK)

{
  "id": "507f1f77bcf86cd799439011",
  "email": "user@example.com",
  "ticker": "BTC-USDT",
  "entrySpotValue": 83000.00,
  "entryShortValue": 83150.00,
  "entrySpotQty": 0.1,
  "entryFuturesQty": 0.1,
  "entrySpotTotalValue": 8300.00,
  "entryFuturesTotalValue": 8315.00,
  "entrySpread": 150.00,
  "entrySpreadPercentage": 0.18,
  "timestamp": 1743595200000
}

​
Campos da Resposta

CampoTipoDescrição
idstringID da entrada no MongoDB
emailstringEmail do usuário
tickerstringPar de trading
entrySpotValuefloatPreço spot de entrada
entryShortValuefloatPreço futuro de entrada
entrySpotQtyfloatQuantidade spot
entryFuturesQtyfloatQuantidade futuro
entrySpotTotalValuefloatentrySpotValue × entrySpotQty
entryFuturesTotalValuefloatentryShortValue × entryFuturesQty
entrySpreadfloatentryShortValue − entrySpotValue
entrySpreadPercentagefloat(entrySpread / entrySpotValue) × 100
timestampint64Timestamp de criação (milissegundos Unix)

​
📝 Códigos de Resposta

200 OK: Posição criada ou atualizada com sucesso. Retorna o objeto completo com spread calculado.
400 Bad Request:
  • Invalid request body: JSON malformado
  • email is required: Campo email ausente
  • ticker is required: Campo ticker ausente
500 Internal Server Error: Failed to create or update calculator — Erro ao persistir no MongoDB.

​
🔁 Comportamento de Upsert

O endpoint verifica se já existe uma entrada para email + ticker:
  • Não existe → cria um novo documento
  • Já existe → atualiza todos os campos de valor/quantidade
Isso garante que cada usuário tenha apenas uma posição por par de trading, facilitando o rastreamento via stream.

​
🔍 Fluxo Completo da Calculadora

1. POST /v1/calculators          → Registra dados de entrada (este endpoint)
2. GET  /v1/calculators/stream   → Monitora PNL em tempo real (SSE)
3. POST /v1/calculators/process  → Consulta pontual de PNL (alternativa ao stream)