Swap e Bridge

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

Pré-requisitos

Antes de usar a API Swap, garanta que você tem:

Chave de API

Obtenha sua chave de API no Dashboard da Blockradar. Vá até Developers para gerar uma.

Wallet criada

Crie uma wallet pela API Create Wallet ou pelo dashboard. Você precisará do walletId para as operações de swap.

IDs de ativos

Obtenha o assetId dos seus ativos de origem e destino em Assets no dashboard ou pela API Get Assets.

Saldo suficiente

Garanta que sua wallet tenha saldo suficiente do ativo de origem para cobrir o valor do swap mais as taxas de rede.

Como funciona

A Blockradar determina automaticamente se sua transação é um swap ou um bridge com base na seleção dos ativos:

Swap

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

Bridge

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

Você não precisa especificar se é um swap ou um bridge — a API trata isso automaticamente com base no fromAssetId e no toAssetId que você fornecer.

Ativos e cadeias suportados

A API Swap suporta as principais stablecoins nas cadeias compatíveis com a Blockradar:

Stablecoin	Descrição
USDT	Tether USD
USDC	USD Coin
DAI	Dai Stablecoin
BUSD	Binance USD
cNGN	Stablecoin de Naira
EURC	Euro Coin
IDRX	Stablecoin da Indonésia
JPYC	Stablecoin de Iene Japonês

A disponibilidade dos ativos varia por cadeia. Use sempre a API Get Assets para obter a lista atualizada de ativos suportados e seus valores de assetId para as cadeias de destino.

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

Master Wallet vs Child Address

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

Master Wallet

Execute swaps diretamente da sua master wallet. Ideal para operações de tesouraria.

Child Address

Execute swaps a partir de child addresses individuais. Perfeito para operações específicas de cada usuário.

Endpoints

Operação	Master Wallet	Child Address
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 solicite uma cotação antes de executar um swap para mostrar ao usuário o resultado esperado.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`fromAssetId`	string	Sim	O asset ID de origem do swap
`toAssetId`	string	Sim	O asset ID de destino do swap
`amount`	string	Sim	O valor a ser trocado
`order`	string	Não	Preferência da cotação: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE`
`recipientAddress`	string	Não	Endereço de wallet externa (para envios a wallets que não são da 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": "Swap quote fetched successfully",
  "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 o swap
`minAmount`	Valor mínimo garantido (considerando o slippage)
`rate`	Taxa de câmbio efetiva (toAmount / fromAmount)
`impact`	Percentual de impacto no preço
`slippage`	Percentual máximo de variação de preço permitida
`networkFee`	Taxa de gás em unidades do token nativo
`networkFeeInUSD`	Taxa de gás convertida em USD
`estimatedArrivalTime`	Tempo estimado de conclusão em segundos

Sempre exiba, no mínimo: valor a receber, tempo estimado de chegada e taxas antes do usuário confirmar o swap.

Passo 2: Executar o Swap

Assim que o usuário confirmar a cotação, execute o swap.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`fromAssetId`	string	Sim	O asset ID de origem do swap
`toAssetId`	string	Sim	O asset ID de destino do swap
`amount`	string	Sim	O valor a ser trocado
`order`	string	Não	Preferência da cotação: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE`
`recipientAddress`	string	Não	Endereço de wallet externa (para envios a wallets que não são da Blockradar)
`reference`	string	Não	Seu ID interno de rastreamento
`metadata`	object	Não	Dados personalizados encaminhados via 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": "Swap transaction created successfully",
  "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 swap são assíncronas. A resposta inicial mostra o status PENDING. Escute o webhook swap.success ou swap.failed para confirmar a conclusão.

Tipos de ordem

Escolha o tipo de ordem adequado ao seu caso de uso:

Tipo de ordem	Descrição	Indicado para
`FASTEST`	Prioriza velocidade em relação ao custo	Transações com restrição de tempo
`CHEAPEST`	Minimiza as taxas	Operações sensíveis ao custo
`RECOMMENDED`	Abordagem equilibrada (padrão)	Maioria dos casos
`NO_SLIPPAGE`	Valor exato ou falha	Requisitos de valor preciso

Eventos de Webhook

Monitore a conclusão do swap por meio de webhooks:

Evento	Descrição
`swap.success`	Swap concluído com sucesso
`swap.failed`	Swap 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

A seguir, uma implementação completa demonstrando 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';

  // Step 1: Get quote
  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());

  // Step 2: Display quote to user
  console.log(`You will receive: ${quote.data.amount}`);
  console.log(`Minimum amount: ${quote.data.minAmount}`);
  console.log(`Network fee: $${quote.data.networkFeeInUSD}`);
  console.log(`Estimated time: ${quote.data.estimatedArrivalTime}s`);

  // Step 3: Execute swap (after user confirmation)
  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('Swap initiated:', swap.data.id);
  console.log('Status:', swap.data.status);

  // Step 4: Listen for webhook to confirm completion
  return swap.data;
}

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

Respostas de erro

Saldo insuficiente

{
  "message": "Insufficient balance for swap",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}

Asset ID inválido

{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}

Rota de swap indisponível

{
  "message": "No swap route available for this pair",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}

Valor muito baixo

{
  "message": "Amount below minimum swap threshold",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}

Slippage excedido

{
  "message": "Price moved beyond slippage tolerance",
  "statusCode": 400,
  "error": "SLIPPAGE_EXCEEDED",
  "data": {
    "expectedAmount": "99.45",
    "actualAmount": "97.00",
    "slippageTolerance": "0.5%"
  }
}

Boas práticas

Experiência do usuário

Sempre exiba cotações: mostre 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 do swap

Segurança

Valide os valores: garanta que os valores do swap estejam dentro de faixas aceitáveis
Use referências: rastreie os swaps com IDs de referência únicos
Monitore os webhooks: sempre verifique a conclusão do swap por meio de webhooks

Desempenho

Faça cache dos asset IDs: armazene os asset IDs localmente para evitar consultas repetidas
Use os tipos de ordem adequados: escolha FASTEST para casos sensíveis ao tempo e CHEAPEST para os sensíveis ao custo
Implemente retentativas: trate falhas transitórias com backoff exponencial

Referência da API

Endpoint	Descrição
Master Wallet Get Quote	Obter cotação de swap pela master wallet
Master Wallet Execute	Executar swap pela master wallet
Child Address Get Quote	Obter cotação de swap por uma child address
Child Address Execute	Executar swap por uma child address

Suporte

E-mail: [email protected]
Documentação: Referência da API
Blog: Como fazer swap ou bridge de ativos com a Blockradar

A API Swap fornece uma interface unificada para swaps na mesma cadeia e bridges entre cadeias. Comece com pequenos valores de teste em testnets antes de migrar para produção.

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Pré-requisitos

Como funciona

Swap

Bridge

Ativos e cadeias suportados

Master Wallet vs Child Address

Master Wallet

Child Address

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 o Swap

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

Boas práticas

Experiência do usuário

Segurança

Desempenho

Referência da API

Suporte

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Documentation Index

​Pré-requisitos

​Como funciona

Swap

Bridge

​Ativos e cadeias suportados

​Master Wallet vs Child Address

Master Wallet

Child Address

​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 o Swap

​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

​Boas práticas

​Experiência do usuário

​Segurança

​Desempenho

​Referência da API

​Suporte

Pré-requisitos

Como funciona

Ativos e cadeias suportados

Master Wallet vs Child Address

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 o Swap

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

Boas práticas

Experiência do usuário

Segurança

Desempenho

Referência da API

Suporte