Troca & Ponte

Em resumo
A API de Troca da Blockradar permite que você troque ativos na mesma cadeia (swap) ou mova ativos entre diferentes cadeias (bridge) usando um único endpoint unificado.

Pré-requisitos

Antes de usar a API de Troca, certifique-se de ter:

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue até Configurações → Chaves API para gerar uma.

Carteira Criada

Crie uma carteira via API Criar Carteira ou pelo painel. Você precisará do walletId para operações de troca.

IDs de Ativos

Obtenha o assetId dos seus ativos de origem e destino em Ativos no painel ou via API Obter Ativos.

Saldo Suficiente

Certifique-se de que sua carteira tenha saldo suficiente do ativo de origem para cobrir o valor da troca mais as taxas de rede.

Como Funciona

A Blockradar determina automaticamente se sua transação é uma troca ou uma ponte com base na sua seleção de ativos:

Troca

Troque diferentes ativos na mesma blockchain.Exemplo: USDC → USDT na Base

Ponte

Mova ativos entre diferentes blockchains.Exemplo: USDC na BSC → USDC na Optimism

Você não precisa especificar se é uma troca ou ponte—a API lida com isso automaticamente com base no fromAssetId e toAssetId que você fornece.

Ativos e Cadeias Suportados

A API de Troca suporta as principais stablecoins nas cadeias suportadas pela Blockradar:

Stablecoin	Descrição
USDT	Tether USD
USDC	USD Coin
DAI	Dai Stablecoin
BUSD	Binance USD
cNGN	Naira Stablecoin
EURC	Euro Coin
IDRX	Indonesian Stablecoin

A disponibilidade de ativos varia por cadeia. Sempre use a API Obter Ativos para buscar a lista atual de ativos suportados e seus valores de assetId para suas cadeias alvo.

Consulte Integrações para a lista completa de redes e stablecoins suportadas.

Carteira Principal vs Endereço Filho

A API de Troca está disponível em dois níveis:

Carteira Principal

Execute trocas diretamente da sua carteira principal. Ideal para operações de tesouraria.

Endereço Filho

Execute trocas a partir de endereços filhos individuais. Perfeito para operações específicas de usuários.

Endpoints

Operação	Carteira Principal	Endereço Filho
Obter Cotação	`POST /v1/wallets/{walletId}/swaps/quote`	`POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote`
Executar	`POST /v1/wallets/{walletId}/swaps/execute`	`POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute`

Passo 1: Obter uma Cotação

Sempre busque uma cotação antes de executar uma troca para mostrar aos usuários o resultado esperado.

Parâmetros da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
`fromAssetId`	string	Sim	O ID do ativo de origem
`toAssetId`	string	Sim	O ID do ativo de destino
`amount`	string	Sim	O valor a ser trocado
`order`	string	Não	Preferência de cotação: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE`
`recipientAddress`	string	Não	Endereço de carteira externa (para envio para carteiras não-Blockradar)

Exemplo de Cotação

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/quote \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "fromAssetId": "asset_usdc_base_mainnet",
    "toAssetId": "asset_usdt_bsc_mainnet",
    "amount": "100",
    "order": "RECOMMENDED"
  }'

Resposta da Cotação

{
  "message": "Cotação de troca obtida com sucesso",
  "statusCode": 200,
  "data": {
    "amount": "99.45",
    "minAmount": "98.95",
    "rate": "0.9945",
    "impact": "0.12",
    "slippage": "0.5",
    "networkFee": "0.002",
    "networkFeeInUSD": "0.15",
    "estimatedArrivalTime": 180
  }
}

Entendendo os Campos da Cotação

Campo	Descrição
`amount`	Valor estimado que você receberá após a troca
`minAmount`	Valor mínimo garantido (considerando o slippage)
`rate`	Taxa de câmbio efetiva (valorDestino / valorOrigem)
`impact`	Porcentagem de impacto no preço
`slippage`	Porcentagem máxima permitida de variação de preço
`networkFee`	Taxa de gas em unidades de token nativo
`networkFeeInUSD`	Taxa de gas convertida para USD
`estimatedArrivalTime`	Tempo esperado de conclusão em segundos

Sempre exiba no mínimo: valor a receber, tempo estimado de chegada e taxas antes que o usuário confirme a troca.

Passo 2: Executar a Troca

Depois que o usuário confirmar a cotação, execute a troca.

Parâmetros da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
`fromAssetId`	string	Sim	O ID do ativo de origem
`toAssetId`	string	Sim	O ID do ativo de destino
`amount`	string	Sim	O valor a ser trocado
`order`	string	Não	Preferência de cotação: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE`
`recipientAddress`	string	Não	Endereço de carteira externa (para envio para carteiras não-Blockradar)
`reference`	string	Não	Seu ID de rastreamento interno
`metadata`	object	Não	Dados personalizados passados através dos webhooks

Exemplo de Execução

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "fromAssetId": "asset_usdc_base_mainnet",
    "toAssetId": "asset_usdt_bsc_mainnet",
    "amount": "100",
    "order": "RECOMMENDED",
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    }
  }'

Resposta da Execução

{
  "message": "Transação de troca criada com sucesso",
  "statusCode": 200,
  "data": {
    "id": "swap-uuid-123",
    "type": "SWAP",
    "status": "PENDING",
    "fromAsset": {
      "symbol": "USDC",
      "amount": "100",
      "blockchain": "base"
    },
    "toAsset": {
      "symbol": "USDT",
      "amount": "99.45",
      "blockchain": "bsc"
    },
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

As operações de troca são assíncronas. A resposta inicial mostra status PENDING. Escute o webhook swap.success ou swap.failed para confirmar a conclusão.

Tipos de Ordem

Escolha o tipo de ordem certo com base no seu caso de uso:

Tipo de Ordem	Descrição	Melhor Para
`FASTEST`	Prioriza velocidade sobre custo	Transações sensíveis ao tempo
`CHEAPEST`	Minimiza taxas	Operações sensíveis a custos
`RECOMMENDED`	Abordagem equilibrada (padrão)	A maioria dos casos de uso
`NO_SLIPPAGE`	Valor exato ou falha	Requisitos de valor preciso

Eventos de Webhook

Monitore a conclusão da troca através de webhooks:

Evento	Descrição
`swap.success`	Troca concluída com sucesso
`swap.failed`	Troca falhou

Payload do Webhook

{
  "event": "swap.success",
  "data": {
    "id": "swap-uuid-123",
    "type": "SWAP",
    "status": "SUCCESS",
    "fromAsset": {
      "symbol": "USDC",
      "amount": "100",
      "blockchain": "base",
      "hash": "0xabc..."
    },
    "toAsset": {
      "symbol": "USDT",
      "amount": "99.45",
      "blockchain": "bsc",
      "hash": "0xdef..."
    },
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    },
    "completedAt": "2024-01-15T10:33:00Z"
  }
}

Exemplo de Fluxo Completo

Aqui está uma implementação completa mostrando o fluxo cotação → confirmação → execução:

async function executeSwap(walletId, fromAssetId, toAssetId, amount) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';

  // Passo 1: Obter cotação
  const quote = await fetch(
    `${baseUrl}/wallets/${walletId}/swaps/quote`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId,
        toAssetId,
        amount,
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  // Passo 2: Exibir cotação para o usuário
  console.log(`Você receberá: ${quote.data.amount}`);
  console.log(`Valor mínimo: ${quote.data.minAmount}`);
  console.log(`Taxa de rede: $${quote.data.networkFeeInUSD}`);
  console.log(`Tempo estimado: ${quote.data.estimatedArrivalTime}s`);

  // Passo 3: Executar troca (após confirmação do usuário)
  const swap = await fetch(
    `${baseUrl}/wallets/${walletId}/swaps/execute`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId,
        toAssetId,
        amount,
        order: 'RECOMMENDED',
        reference: `swap-${Date.now()}`
      })
    }
  ).then(r => r.json());

  console.log('Troca iniciada:', swap.data.id);
  console.log('Status:', swap.data.status);

  // Passo 4: Escutar webhook para confirmar conclusão
  return swap.data;
}

// Uso
executeSwap(
  'wallet-uuid',
  'asset_usdc_base_mainnet',
  'asset_usdt_bsc_mainnet',
  '100'
);

Respostas de Erro

Saldo Insuficiente

{
  "message": "Saldo insuficiente para troca",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}

ID de Ativo Inválido

{
  "message": "Ativo não encontrado",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}

Rota de Troca Não Disponível

{
  "message": "Nenhuma rota de troca disponível para este par",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}

Valor Muito Baixo

{
  "message": "Valor abaixo do limite mínimo de troca",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}

Slippage Excedido

{
  "message": "O preço variou além da tolerância de slippage",
  "statusCode": 400,
  "error": "SLIPPAGE_EXCEEDED",
  "data": {
    "expectedAmount": "99.45",
    "actualAmount": "97.00",
    "slippageTolerance": "0.5%"
  }
}

Melhores Práticas

Experiência do Usuário

Sempre mostre cotações: Exiba valor, taxas e tempo estimado antes da execução
Trate o slippage: Informe os usuários sobre possíveis variações de preço
Mostre o progresso: Use webhooks para atualizar os usuários sobre o status da troca

Segurança

Valide os valores: Certifique-se de que os valores de troca estão dentro de faixas aceitáveis
Use referências: Rastreie trocas com IDs de referência únicos
Monitore webhooks: Sempre verifique a conclusão da troca via webhooks

Performance

Armazene IDs de ativos em cache: Armazene IDs de ativos localmente para evitar consultas repetidas
Use tipos de ordem apropriados: Escolha FASTEST para sensibilidade ao tempo, CHEAPEST para sensibilidade a custos
Implemente retentativas: Trate falhas transitórias com backoff exponencial

Referência da API

Endpoint	Descrição
Obter Cotação Carteira Principal	Obter cotação de troca da carteira principal
Executar Carteira Principal	Executar troca da carteira principal
Obter Cotação Endereço Filho	Obter cotação de troca do endereço filho
Executar Endereço Filho	Executar troca do endereço filho

Suporte

Email: [email protected]
Documentação: Referência da API
Blog: Como Trocar ou Fazer Ponte de Ativos com Blockradar

A API de Troca fornece uma interface unificada para trocas na mesma cadeia e pontes entre cadeias. Comece com pequenos valores de teste em testnets antes de ir para produção.

Começar

Essenciais

Pré-requisitos

Como Funciona

Troca

Ponte

Ativos e Cadeias Suportados

Carteira Principal vs Endereço Filho

Carteira Principal

Endereço Filho

Endpoints

Passo 1: Obter uma Cotação

Parâmetros da Requisição

Exemplo de Cotação

Resposta da Cotação

Entendendo os Campos da Cotação

Passo 2: Executar a Troca

Parâmetros da Requisição

Exemplo de Execução

Resposta da Execução

Tipos de Ordem

Eventos de Webhook

Payload do Webhook

Exemplo de Fluxo Completo

Respostas de Erro

Melhores Práticas

Experiência do Usuário

Segurança

Performance

Referência da API

Suporte

Começar

Essenciais

​Pré-requisitos

​Como Funciona

Troca

Ponte

​Ativos e Cadeias Suportados

​Carteira Principal vs Endereço Filho

Carteira Principal

Endereço Filho

​Endpoints

​Passo 1: Obter uma Cotação

​Parâmetros da Requisição

​Exemplo de Cotação

​Resposta da Cotação

​Entendendo os Campos da Cotação

​Passo 2: Executar a Troca

​Parâmetros da Requisição

​Exemplo de Execução

​Resposta da Execução

​Tipos de Ordem

​Eventos de Webhook

​Payload do Webhook

​Exemplo de Fluxo Completo

​Respostas de Erro

​Melhores Práticas

​Experiência do Usuário

​Segurança

​Performance

​Referência da API

​Suporte

Pré-requisitos

Como Funciona

Ativos e Cadeias Suportados

Carteira Principal vs Endereço Filho

Endpoints

Passo 1: Obter uma Cotação

Parâmetros da Requisição

Exemplo de Cotação

Resposta da Cotação

Entendendo os Campos da Cotação

Passo 2: Executar a Troca

Parâmetros da Requisição

Exemplo de Execução

Resposta da Execução

Tipos de Ordem

Eventos de Webhook

Payload do Webhook

Exemplo de Fluxo Completo

Respostas de Erro

Melhores Práticas

Experiência do Usuário

Segurança

Performance

Referência da API

Suporte