Jornada do cliente

1. 1

   Cadastro

   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

   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

   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

   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

   O cliente

   Confere o plano e paga a mensalidade aplicável em Resultados e faturas. Depois liga ou pausa a automação.

   Seu backend

   Consulta a elegibilidade comercial antes de oferecer novas entradas. Conectar a corretora não comprova pagamento. A primeira mensalidade deve estar paga; vencimento e grace valem para renovações. INITIAL_SUBSCRIPTION_PAYMENT_REQUIRED indica a primeira cobrança pendente. 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

   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

   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

   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, destinatário, rede e validade). EVM usa txHash; DEPOSIT_INVOICE gera um endereço exclusivo; HYPERLIQUID_USD_SEND abre o Hosted Payment para assinatura da carteira principal. Hyperliquid exige obrigação em USDC e receptor configurado. Seu app nunca marca pago: consulte o estado PAID da obrigação. HTTP de sucesso ou envio da transação isoladamente não comprovam quitação. Pagamento parcial continua pendente; excedente registrado não é abatimento automático da próxima cobrança.

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

   Eventos

   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.