Swap e Bridge - Blockradar

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 pelo dashboard (consulte Criar uma Carteira Principal). 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 de origem quando `amountSide` é `source`, ou o valor de destino quando `amountSide` é `target`
`amountSide`	string	Não	`source` ou `target`. O padrão é `source`. Use `target` para cotar ou executar um valor exato de destino
`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)
`recipientRouting`	object	Não	Somente para destinos Stellar: `{ type: "none" }` ou `{ type: "memo_id", value: "<numeric string>" }`. Omita-o para destinos EVM, Solana e Tron.

Use amountSide: "source" quando o usuário informa quanto quer gastar. Use amountSide: "target" quando o usuário informa quanto quer receber e você precisa que a Blockradar resolva o valor de origem necessário.

Roteamento de destinatário Stellar

recipientRouting só é compatível quando a blockchain de destino é Stellar. É um contrato de roteamento genérico, compartilhado por todos os endpoints de cotação e execução deste guia. As solicitações existentes para EVM, Solana e Tron não sofrem nenhuma alteração incompatível: elas não devem enviar recipientRouting; solicitações que o incluírem são rejeitadas. recipientAddress continua sendo uma string opcional; não o envie como objeto. Não envie um campo separado de memo do destinatário.

Regras de destino Stellar

Destinatário muxed M...: omita recipientRouting. O ID de roteamento já está incorporado no endereço muxed, e fornecer dados de roteamento é rejeitado.
Destinatário base G... com ID de roteamento: envie { type: "memo_id", value: "123" }. value deve ser uma string numérica não vazia entre 0 e 18446744073709551615. A Blockradar normaliza o endereço para M... antes de solicitar a cotação ou a execução.
Destinatário base G... sem ID de roteamento: envie { type: "none" } sem incluir value. Um destinatário G... sem recipientRouting é rejeitado. A conta base de destino precisa ter uma trustline de Stellar USDC antes da cotação ou da execução.
Carteira Stellar padrão da Blockradar: envie explicitamente { type: "none" } em recipientRouting.

Exemplos de requisição

Todos os exemplos usam o mesmo formato de corpo em cada um destes endpoints:

POST /v1/wallets/{walletId}/swaps/quote
POST /v1/wallets/{walletId}/swaps/execute
POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote
POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute

Non-Stellar destination — no routing field

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdt_bsc_mainnet",
  "amount": "100",
  "recipientAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
}

Stellar G... without a routing ID

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "G...",
  "recipientRouting": {
    "type": "none"
  }
}

Stellar G... with a routing ID

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "G...",
  "recipientRouting": {
    "type": "memo_id",
    "value": "123"
  }
}

Stellar M... recipient — no routing field

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientAddress": "M..."
}

Default Blockradar Stellar wallet

{
  "fromAssetId": "asset_usdc_base_mainnet",
  "toAssetId": "asset_usdc_stellar_mainnet",
  "amount": "100",
  "recipientRouting": {
    "type": "none"
  }
}

Migração de campos específicos de Stellar

Campo anterior	Substituto
`recipientMemoId`	`recipientRouting: { type: "memo_id", value: "<numeric string>" }`
`stellarMemoNotRequired: true`	`recipientRouting: { type: "none" }`

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",
    "amountSide": "source",
    "order": "RECOMMENDED"
  }'

const quote = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/swaps/quote`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      fromAssetId: 'asset_usdc_base_mainnet',
      toAssetId: 'asset_usdt_bsc_mainnet',
      amount: '100',
      amountSide: 'source',
      order: 'RECOMMENDED'
    })
  }
).then(r => r.json());

console.log('Quote:', quote.data);

Resposta da cotação

{
  "message": "Swap quote fetched successfully",
  "statusCode": 200,
  "data": {
    "amount": "99.45",
    "fromAmount": "100",
    "toAmount": "99.45",
    "requestedAmount": "100",
    "amountSide": "source",
    "minAmount": "98.95",
    "rate": "0.9945",
    "impact": "0.12",
    "slippage": "0.5",
    "networkFee": "0.002",
    "networkFeeInUSD": "0.15",
    "estimatedArrivalTime": 180,
    "recipientRouting": {
      "status": "none",
      "message": "No recipient routing value will be used. Confirm the destination accepts direct deposits without one."
    }
  }
}

Para um destino muxed, data.recipientRouting pode, em vez disso, informar que o ID de roteamento está incorporado no endereço de destino normalizado:

{
  "recipientRouting": {
    "status": "embedded",
    "message": "The recipient routing ID is embedded in the normalized destination address."
  }
}

data.recipientRouting é opcional e só é retornado nas respostas de cotação. Não espere encontrá-lo nas respostas de execução.

Entendendo os campos da cotação

Campo	Descrição
`amount`	Valor estimado de destino a receber. Em cotações pelo destino, este é o valor de destino solicitado
`fromAmount`	Valor do ativo de origem necessário para a cotação
`toAmount`	Valor do ativo de destino retornado pela cotação
`requestedAmount`	Valor original enviado na requisição
`amountSide`	Indica se `requestedAmount` representa o valor de origem ou o valor de destino
`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
`recipientRouting`	Metadados opcionais de roteamento Stellar. `none` significa que nenhum valor de roteamento é usado; `embedded` significa que ele está incorporado no endereço de destino normalizado.

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 de origem quando `amountSide` é `source`, ou o valor de destino quando `amountSide` é `target`
`amountSide`	string	Não	`source` ou `target`. O padrão é `source`. Use `target` para cotar ou executar um valor exato de destino
`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)
`recipientRouting`	object	Não	Somente para Stellar. Use o mesmo valor da requisição de cotação; omita-o para destinos EVM, Solana e Tron.
`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",
    "amountSide": "source",
    "order": "RECOMMENDED",
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    }
  }'

const swap = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/swaps/execute`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      fromAssetId: 'asset_usdc_base_mainnet',
      toAssetId: 'asset_usdt_bsc_mainnet',
      amount: '100',
      amountSide: 'source',
      order: 'RECOMMENDED',
      reference: 'swap-order-12345',
      metadata: {
        userId: 'user_abc123',
        orderId: 'order_xyz789'
      }
    })
  }
).then(r => r.json());

console.log('Swap initiated:', swap.data);

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, amountSide = 'source') {
  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,
        amountSide,
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  // Step 2: Display quote to user
  console.log(`You will receive: ${quote.data.toAmount}`);
  console.log(`Required source amount: ${quote.data.fromAmount}`);
  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,
        amountSide,
        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.

​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

​Roteamento de destinatário Stellar

​Regras de destino Stellar

​Exemplos de requisição

​Migração de campos específicos de Stellar

​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

Roteamento de destinatário Stellar

Regras de destino Stellar

Exemplos de requisição

Migração de campos específicos de Stellar

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