Executando SWAP

Este documento descreve os fluxos necessários para a integração da troca direta de ativos digitais e detalha as notificações assíncronas (Webhooks) geradas ao final de cada processo.

A operação é estruturada em dois passos fundamentais para garantir assertividade: o estágio rápido de cotação (onde o token e a rede são validados) e o estágio final de fechamento da operação que inicia a liquidação de forma assíncrona.

1. Criptomoedas e Redes Aceitas

Tanto na cotação quanto na execução, a API requer que os pares de conversão (Tokens e suas Redes) sejam informados. O sistema suporta nativamente a conversão entre as redes descritas abaixo.

• BTC (Bitcoin): Rede Bitcoin.

• USDT (Tether): Redes Ethereum (ERC20), Tron (TRC20) e Polygon.

• USDC (USD Coin): Redes Ethereum (ERC20), Polygon, Base, Optimism e Solana.

2. Cotação de Conversão (Quote)

O mercado de câmbio exige avaliação prévia das taxas agregadas e conversão cambial exata no momento pretendido. O frontend ou serviço integrador precisa obrigatoriamente submeter um pedido de verificação, resultando na clareza do montante de destino que o usuário irá receber.

Endpoint: GET /exchange/swap/quote

Autenticação Obrigatória: Sim (Header Authorization)

2.1 Parâmetros Obrigatórios (Query Params)

2.2 Exemplo de Submissão

GET /exchange/swap/quote?fromToken=BTC&fromAmount=0.05&fromNetwork=bitcoin&toToken=USDC&toNetwork=Polygon

2.3 Exemplo de Cotação Resolvida

{
  "isSimulation": true,
  "canPay": true,
  "swapDetails": {
    "from": { 
      "token": "BTC", 
      "amount": 0.05 
    },
    "to": { 
      "token": "USDC", 
      "amountEstimated": 3275.50
    },
    "currentPrice": 65510.00,
    "feeAmount": 1.25
  }
}

3. Confirmação do Câmbio (Execução)

A aprovação definitiva e realocação de carteiras processam-se a partir da subordinação efetiva confirmada pelo usuário. O saldo debitado constará com resíduo zerado e o reflexo creditado do lado oposto surgirá após a transação alcançar seu status terminal de conferência.

Endpoint: POST /exchange/swap

Autenticação Obrigatória: Sim (Header Authorization)

3.1 Corpo da Requisição Base (JSON)

Mantenha em harmonia as chaves adquiridas na cotação para garantir fidelidade tarifária:

{
  "fromToken": "BTC",
  "fromNetwork": "bitcoin",
  "fromAmount": 0.05,
  "toToken": "USDC",
  "toNetwork": "Polygon",
  "isSimulation": false 
}

3.2 Exemplo de Finalização Pendente da Execução

A requisição finaliza na entrega segura de recebimento (status 201 Created), sinalizando à instituição emissora que o processamento interno e as confirmações perante as pontas de blockchain foram instaurados.

{
  "success": true,
  "message": "Swap iniciado com sucesso. Aguardando processamento da operação.",
  "orderId": "e8bede1e-26ff-4bd8-bb3b-9a2cfcfadfb5",
  "status": "PROCESSING"
}

4. Retornos Assíncronos via Webhook

Para impedir que a sua aplicação faça varreduras de gargalo na plataforma em busca dos status concluídos (polling), toda operação de swap aciona o canal ativo de Push Webhook a cada alteração severa. O payload subirá diretamente de volta ao URL provisionado nas configurações da conta.

4.1 Captador Evento Inicial: pix.exchange.updated

Você receberá atualizações constantes com base em como o núcleo validador avança para a aprovação final.

A proteção da carga é dada pelo Cabeçalho da Ordem assediada com o parâmetro integrador de assinatura. Ao bater no seu endpoint, você verifica o segredo fornecido inicialmente pela arquitetura, geralmente validado via cabeçalho x-ether-key ou um Payload Signature Verification.

4.2 Exemplo do Payload Transmitido (JSON)

{
  "event": "pix.exchange.updated",
  "data": {
    "pixExchangeOrder": {
      "id": "e8bede1e-26ff-4bd8-bb3b-9a2cfcfadfb5",
      "userId": "c5bddeb3-7284-4fb9-a0ef-4fbae8a9310d",
      "status": "COMPLETED",
      "orderType": "SWAP",
      "fromToken": "BTC",
      "fromAmount": "0.05",
      "fromNetwork": "bitcoin",
      "toToken": "USDC",
      "toAmountEstimated": "3275.50",
      "finalAmount": "3273.90",
      "token": "USDC",
      "network": "Polygon",
      "tradePrice": "65478.00",
      "transactionHash": "0xcc2a15f013d3143bd4a0c8bdcc17bdf",
      "createdAt": "2026-04-17T14:50:00.000Z",
      "updatedAt": "2026-04-17T15:05:00.000Z"
    },
    "logs": [
      {
         "stage": "COMPLETED",
         "message": "Saldo em USDC garantido com sucesso para a carteira depositária de uso exclusivo da contraparte."
      }
    ],
    "timestamp": "2026-04-17T15:05:01.000Z"
  }
}

4.3 Fases Evolutivas da Ocorrência (pixExchangeOrder.status)

Sua implementação precisa cobrir adequadamente pelo menos as trincas fundamentais listadas abaixo, prevenindo a duplicação se o pacote repisar (Devido à taxa intermitente de refazimento padrão do serviço webhook):

1. PROCESSING / PENDING: Estágio nativo de espera transitória. A operação consta em custódia e submetendo cálculos ou checagens finais. Na ponta interface não exiba o dinheiro como recebido e sim "Na rede".

2. COMPLETED: Ciclo consolidado. O ativo digital expresso integralmente na chave finalAmount repousa devidamente liberado e auditado para movimentação e reuso contínuo na carteira da rede referida. Note que devido à derrapagem cambial de flutuação e latência (Slippage de mercado), a garantia final em finalAmount pode estar nominalmente variando do orçado da requisição toAmountEstimated.

3. ERROR / FAILED: Transação bloqueada de modo irrecuperável que extorna as garantias para os status iniciais do depositário primário após apontar nos fluxos de exceções em logs.