> ## Documentation Index
> Fetch the complete documentation index at: https://docs.levery.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Executar um Swap

> Aprenda como funciona o swap de ativos em pools autorizadas usando execução compatível com padrões, precificação garantida por oráculos e recibos prontos para auditoria.

A página **Trade** é a interface de swap spot que fornece uma experiência estilo DEX (selecionar pool, inserir valor, trocar) enquanto mantém guardrails institucionais **aplicados on-chain**:

* **Acesso permissionado**: apenas contas elegíveis podem negociar em pools restritas.
* **Liquidação conforme**: os recebíveis do swap só podem ser recebidos pela carteira iniciadora.
* **Execução determinística**: a plataforma habilita swaps apenas quando consegue computar uma **cotação on-chain** para o contexto exato da negociação.
* **Resultados prontos para auditoria**: toda negociação é rastreável por hash de transação, logs e estado canônico do pool.

***

## Tela de Trade

<Columns cols={2}>
  <Card title="Painel de swap" icon="arrows-rotate">
    Selecione um pool, escolha a direção, insira valores, revise taxas e gas, e execute o swap. O botão de swap só é habilitado quando há uma cotação on-chain disponível e a conta passa nas checagens de política.
  </Card>

  <Card title="Informações de ativos" icon="circle-info">
    Perfis de ativos com descrição do projeto, métricas de mercado/oferta, variação em 24h e precificação proveniente de feeds de oráculo de preços de mercado confiáveis, permitindo decisões de trade informadas e responsáveis.
  </Card>
</Columns>

<Card title="Seletor de pool (par + rede)" icon="magnifying-glass">
  Pools são identificadas por **par + rede** e podem incluir regras específicas do pool (comportamento de taxas, configuração de oráculo
  e políticas de acesso). Quando o usuário seleciona um pool, a página Trade vincula a sessão do usuário aos parâmetros desse pool.
</Card>

***

## O que a Levery garante durante a execução

<CardGroup cols={2}>
  <Card title="Negociação permissionada" icon="shield-check">
    Swaps executam apenas quando a conta conectada atende às regras de admissão do pool da instituição, incluindo papéis, status de compliance e quaisquer restrições de acesso definidas pelo operador.
  </Card>

  <Card title="Liquidação conforme" icon="user-lock">
    A liquidação é vinculada à conta iniciadora. O router conforme impede que os recebíveis sejam redirecionados a
    destinatários arbitrários, garantindo que controles de custódia e contabilidade permaneçam intactos.
  </Card>
</CardGroup>

<Card title="Determinismo on-chain" icon="link">
  Negociações são habilitadas apenas quando uma cotação on-chain pode ser produzida e a transação submetida corresponde aos mesmos
  parâmetros de pool e contexto de conta usados para aplicação e precificação.
</Card>

<Note>
  A Levery separa **correção de execução** (cotação on-chain + checagens aplicadas) de **conveniência de exibição** (conversão para fiat
  e métricas informativas). Uma estimativa de UI nunca é suficiente, por si só, para habilitar execução.
</Note>

***

## Executar um swap

<Steps>
  <Step title="Selecione um pool (par + rede)">
    O usuário abre o seletor de par no topo do card de swap e seleciona um pool.

    Um pool define:

    * os dois ativos,
    * a rede,
    * o comportamento de taxas (estático ou dinâmico),
    * e a política de permissões que se aplica aos swaps.

    Se a carteira conectada estiver em outra rede, a carteira solicita a troca de rede antes da execução.
  </Step>

  <Step title="Escolha a direção (From → To)">
    O usuário seleciona o ativo a gastar em **From** e o ativo a receber em **To**, e pode usar o controle de inversão para trocar a direção.

    A direção importa porque a lógica de taxas, regras de desvio do oráculo e restrições de política podem ser sensíveis à direção.
  </Step>

  <Step title="Escolha uma intenção de execução (Exact input ou Exact output)">
    A Levery suporta duas intenções de trade:

    * **Exact input**: o usuário especifica o valor em **From**. A plataforma computa uma saída estimada sujeita à proteção de slippage.
    * **Exact output**: o usuário especifica o valor em **To**. A plataforma computa uma entrada máxima estimada sujeita à proteção de slippage.

    Essa escolha impacta **como as taxas de serviço são cobradas** (ver abaixo) e qual garantia de trade é preservada.
  </Step>

  <Step title="Aguarde uma cotação on-chain (obrigatória)">
    A página Trade solicita continuamente uma **cotação on-chain** para o pool selecionado, direção e valores. Essa cotação é produzida simulando o swap contra o estado atual do pool e as regras de aplicação.

    Estados típicos incluem:

    * **Quoting…**: a UI está buscando ou atualizando uma cotação.
    * **Ready**: uma cotação válida está disponível e o botão de swap pode ser habilitado.
    * **Estimate only (swap disabled)**: a UI pode mostrar uma estimativa indicativa, mas a execução é bloqueada porque uma cotação on-chain determinística não está disponível.

    <Callout type="warning" title="Por que a Levery pode desabilitar swaps mesmo quando um preço é exibido">
      Preços em fiat e estimativas indicativas ainda podem ser mostrados. Porém, a execução só é habilitada quando a Levery consegue reproduzir a negociação de forma determinística on-chain sob o mesmo contexto usado para aplicação.
    </Callout>
  </Step>

  <Step title="Revise taxas e gas antes de enviar">
    Revise os badges abaixo dos inputs:

    * **Taxas totais**: a estimativa agregada de taxa de LP e taxa de serviço para essa intenção e direção.
    * **Estimativa de gas**: a estimativa da taxa de rede (no token nativo da chain e convertida para fiat por conveniência).

    <Callout type="info" title="Estimativas vs valores finais">
      O gas final pago depende das condições de rede. As taxas finais dependem das regras de execução on-chain do pool e dos deltas exatos realizados durante o swap.
    </Callout>
  </Step>

  <Step title="Aprove permissões de gasto (se necessário)">
    Se o ativo de entrada for um token ERC-20, aprovações podem ser necessárias antes de trocar.

    Muitas implantações da Levery usam um modelo de allowance reforçado:

    * **Token → camada de permit** (autoriza o contrato de permit a mover tokens)
    * **Camada de permit → Router** (autoriza o router conforme a gastar sob regras estritas)

    Se o ativo de entrada for o token nativo da chain, aprovações de token não são necessárias.
  </Step>

  <Step title="Execute o swap e confirme o recibo">
    O usuário seleciona **Swap** e confirma a transação na carteira conectada.

    Após o envio, a página Trade acompanha a transação até a confirmação e então exibe um recibo incluindo:

    * valor pago,
    * valor recebido,
    * taxas cobradas,
    * gas pago,
    * e um link para ver a transação em um explorador de blocos.

    Esse recibo é destinado à reconciliação: ele reflete o que foi de fato registrado on-chain.
  </Step>
</Steps>

***

## Exact input vs exact output

<Columns cols={2}>
  <Card title="Exact input" icon="arrow-right">
    O usuário especifica o valor a gastar. A Levery computa uma saída estimada e aplica um **valor mínimo de saída** (`minOut`) usando proteção de slippage.

    **Comportamento de taxa de serviço**

    * A taxa de serviço é cobrada **a partir do valor de entrada especificado** antes da execução do swap.
    * O pool consome o valor restante após a retenção da taxa de serviço.
  </Card>

  <Card title="Exact output" icon="arrow-left">
    O usuário especifica o valor a receber. A Levery computa uma entrada máxima estimada e aplica um **valor máximo de entrada** (`maxIn`) usando proteção de slippage.

    **Comportamento de taxa de serviço**

    * A taxa de serviço é cobrada **após a execução**, com base no **delta de entrada real** necessário para produzir a saída exata.
    * O valor de saída solicitado permanece exato (desde que a transação não reverta).
  </Card>
</Columns>

<Callout type="tip" title="Quando usar cada modo">
  **Exact input** é adequado quando é necessário um valor de gasto preciso. **Exact output** é adequado quando é necessário um
  valor de recebimento preciso (com uma entrada máxima limitada).
</Callout>

***

## Explicando as taxas

A Levery separa taxas em duas categorias.

<CardGroup cols={2}>
  <Card title="Taxa de LP (provedores de liquidez)" icon="droplet">
    Taxas de LP são pagas a provedores de liquidez e dependem da configuração do pool.

    * **Pools estáticas**: aplica-se uma taxa fixa.
    * **Pools dinâmicas**: a taxa pode ajustar on-chain com base no contexto de mercado (por exemplo, desvio entre o preço do pool e uma referência de oráculo), para suportar políticas de integridade de mercado.
  </Card>

  <Card title="Taxa de serviço (protocolo / operador)" icon="receipt">
    A instituição que opera a instância Levery cobra uma taxa de serviço. Essa taxa é coletada **on-chain** e roteada para o cofre de taxa de serviço para distribuição segundo regras institucionais.

    O momento da taxa de serviço depende da intenção de trade:

    * **Exact input**: cobrada da entrada *antes* da execução do swap.
    * **Exact output**: cobrada *após* a execução usando o delta de entrada realizado.
  </Card>
</CardGroup>

<Note>
  As taxas são aplicadas por lógica on-chain. A UI exibe estimativas para transparência, mas os valores finais são determinados
  pelos deltas executados na transação.
</Note>

***

## Proteção contra slippage e deadlines

Cada swap inclui duas proteções de execução:

* **Tolerância de slippage**
  * Swaps de exact input aplicam um mínimo de saída (`minOut`).
  * Swaps de exact output aplicam um máximo de entrada (`maxIn`).

* **Deadline**
  * Transações devem executar antes de um timestamp de deadline. Depois disso, a execução é rejeitada.

<Callout type="warning" title="Por que swaps podem reverter">
  Se o preço do pool se mover além da tolerância, a cotação ficar obsoleta ou o deadline expirar, a transação pode reverter
  em vez de executar a um preço inesperado.
</Callout>

***

## Precificação e origem dos dados

A Levery usa dois conceitos de preço distintos na página Trade.

<CardGroup cols={2}>
  <Card title="Preço de execução (cotação on-chain)" icon="bolt">
    A precificação de execução vem de uma cotação on-chain que simula o swap contra:

    * o estado vivo do pool,
    * a lógica de taxas do pool (incluindo taxas dinâmicas),
    * e as regras de aplicação on-chain da instituição.

    Se uma cotação on-chain não puder ser produzida, o swap permanece desabilitado.
  </Card>

  <Card title="Preço de exibição (valores em fiat + métricas)" icon="chart-line">
    O preço de exibição é usado para conversão em fiat, resumos de ativos e contexto histórico. Ele é proveniente dos feeds de precificação configurados pela instituição, respaldados por infraestrutura de oráculos e indexados para referência em tempo real e histórica.

    Isso melhora a confiança porque a origem da precificação é consistente, auditável e não depende de chamadas ad-hoc a APIs do cliente.
  </Card>
</CardGroup>

***

## Modelo de compliance e liquidação

A Levery é projetada para oferecer execução estilo DEX sem perder o controle de compliance:

* **Checagens de admissão on-chain**: swaps são rejeitados se a conta falhar na política de acesso do pool no momento da execução.
* **Liquidação apenas para o iniciador**: recebíveis do swap não podem ser enviados a destinatários arbitrários.
* **Cotação vinculada ao contexto**: cotações são computadas para os mesmos parâmetros de pool e contexto de conta exigidos para execução.
* **Prontidão para auditoria**: trades são rastreáveis a hashes de transação e transições de estado on-chain.

<Card title="O que compartilhar com suporte" icon="life-ring">
  Se uma negociação falhar ou for bloqueada, o usuário deve compartilhar o pool (par + rede), o valor tentado e o
  hash da transação (se uma foi enviada). Isso permite que o operador reconcilie resultados diretamente contra registros on-chain.
</Card>

***

## Solução de problemas

<CardGroup cols={2}>
  <Card title="Botão Swap desativado" icon="ban">
    Causas comuns incluem carteira desconectada, rede errada, nenhuma cotação on-chain executável (liquidez/RPC/config),
    ou a conta não estar permitida para o pool selecionado.
  </Card>

  <Card title="Transação revertida" icon="triangle-exclamation">
    Causas comuns incluem slippage acima da tolerância, deadline expirado, saldo insuficiente, aprovações ausentes (ou
    allowance ainda não refletido) ou uma regra de política on-chain rejeitando a execução.
  </Card>

  <Card title="Aprovação necessária" icon="key">
    Ativos de entrada ERC-20 podem exigir aprovações antes do swap. Quando as etapas de aprovação necessárias forem concluídas, o swap
    pode ser cotado novamente e enviado para execução.
  </Card>

  <Card title="Erro de cotação" icon="bug">
    Falhas de cotação podem indicar indisponibilidade do pool, instabilidade do quoter/RPC ou rejeição de execução por política. Tente novamente, atualize, troque o RPC ou escolha outro pool.
  </Card>
</CardGroup>
