Jornada do cliente

1. 1

   Cadastro

   Ver no modelo: Criar conta ↗

   O cliente

   Cria a conta no seu app (e-mail e senha — suas regras de cadastro).

   Seu backend

   Salva o usuário, gera o externalUserId e chama POST /v1/users com Idempotency-Key. Se a FINAUTON recusar, desfaça ou marque para tentar de novo. O e-mail não vai para a FINAUTON.

   POST/v1/users
2. 2

   Estratégia

   Ver no modelo: Risco e estratégia ↗

   O cliente

   Escolhe entre as estratégias do seu contrato (mostre displayName e summary).

   Seu backend

   Lista granted e grava a escolha.

   GET/v1/strategiesGET…/:id/strategiesPUT…/:id/strategies
3. 3

   Conectar a corretora

   Ver no modelo: Conectar corretora ↗

   O cliente

   Escolhe Binance ou Hyperliquid e conclui na página FINAUTON: Binance — cola a chave de API (Futures ligado, saque desligado, IP liberado conforme a página). Hyperliquid — conecta a carteira, autoriza a carteira-agente (opera, não saca) e aprova a taxa de builder do contrato.

   Seu backend

   Cria a sessão, abre o connectUrl (sem registrar em log) e acompanha o status ou o evento provider.connected. Seu app nunca recebe a chave nem a assinatura.

   GET…/:id/providersPOST…/:id/connect-sessionsGET…/:id/connect-sessions/:sessionId
4. 4

   Risco

   Ver no modelo: Risco e estratégia ↗

   O cliente

   Preenche os limites (tabela abaixo), vê os alertas e confirma.

   Seu backend

   Prévia (não grava; devolve alertas e fingerprint) → mostra os alertas → grava com riskAcknowledgement. O modo é sempre REAL, e gravar exige a corretora já conectada — por isso o passo 3 vem antes.

   GET…/:id/setupPOST…/:id/setup/previewPUT…/:id/setup

   Campo na tela	Campo na API	Observação
   Capital base (USD)	capitalBase	obrigatório para ligar
   Tamanho por operação (USD)	orderSizeUsd
   Perda máxima por operação (USD)	maxLossPerTrade	obrigatório para ligar
   Perda máxima diária (USD)	maxDailyLossUsd	atingiu → sem novas entradas até o dia seguinte (UTC)
   Alavancagem (x)	leverage	limitada pelo contrato
   Margem máxima por operação (USD)	maxMarginPerTradeUsd	limitada pelo contrato
   Operações simultâneas	maxConcurrentTrades	limitada pelo contrato
   Timeout de entrada (min)	entryTimeoutMinutes	1–1440; obrigatório para ligar
   Ativos permitidos	allowedSymbols	opcional
   Stop Loss / Take Profit / Break Even automáticos	autoStopLoss · autoTakeProfit · autoBreakEven	opcionais
   Ligar setup	enabled

5. 5

   Automação

   Ver no modelo: Operação ↗

   O cliente

   Liga ou pausa a automação.

   Seu backend

   Envia o corpo completo (inclusive risk, também para desligar). Mostra newEntries e blockReason para explicar por que está bloqueado.

   GET…/:id/automationPUT…/:id/automation
6. 6

   Acompanhar

   Ver no modelo: Operação ↗

   O cliente

   Vê posições, stop/alvo e ordens.

   Seu backend

   Lê o status consolidado, posições com proteção e ordens. Atualize com os eventos position.* e protection.degraded.

   GET…/:id/statusGET…/:id/execution-statusGET…/:id/intents
7. 7

   Resultados

   Ver no modelo: Resultados e faturas ↗

   O cliente

   Vê o resultado do período e os extratos.

   Seu backend

   Exibe os valores como vieram (providerNetRealizedPnlUsd = resultado). O período aberto é estimativa (LIVE_ESTIMATE), não cobrança. Não recalcule.

   GET…/:id/performanceGET…/:id/statements
8. 8

   Pagar a fatura

   Ver no modelo: Resultados e faturas ↗

   O cliente

   Abre a fatura e clica em Pagar. EVM: escolhe rede e informa a carteira de onde vai pagar; transfere o valor exato pela própria carteira; informa o txHash.

   Seu backend

   Gera a instrução (valor exato, destinatário, validade), mostra ao cliente e confirma o txHash. A FINAUTON verifica on-chain. Seu app nunca marca pago: espere o 200 do confirm ou o evento obligation.paid.

   GET…/:id/billingGET…/:id/obligationsPOST…/:id/obligations/:obligationId/payment-instructionsPOST…/:id/payments/:paymentId/confirm
9. 9

   Eventos

   Ver no modelo: Eventos (admin) ↗

   O cliente

   Recebe avisos no seu app (conexão concluída, fatura criada, fatura paga…).

   Seu backend

   Recebe o webhook assinado e/ou faz polling do feed com cursor. Ver Webhooks.

   GET/v1/events

Backoffice do parceiro

Sua equipe precisa de: lista de clientes, suspender/reativar, visão de qualquer cliente (as mesmas leituras acima), contrato e limites, eventos e consumo da API. O cliente final não acessa essas rotas — seu backend bloqueia.