Saltar para o conteúdo principal
Em resumo
A API de Assinatura da Blockradar permite que você assine criptograficamente mensagens de texto simples e dados estruturados (dados tipados) usando as chaves privadas da sua carteira. As assinaturas comprovam a propriedade da carteira para serviços de terceiros sem movimentar fundos ou pagar taxas de rede (gas).

​
Pré-requisitos

Antes de usar a API de Assinatura, certifique-se de ter:
1

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue até Developers para gerar uma.
2

Carteira Criada

Crie uma carteira mestra no Painel da Blockradar. Navegue até Wallets e crie uma para a blockchain desejada. Você precisará do walletId para operações de assinatura.
3

Ambiente

Escolha entre Testnet (para desenvolvimento) ou Mainnet (para produção). Carteiras são isoladas por ambiente.

​
Como Funciona

A API de Assinatura produz uma assinatura criptográfica que comprova que você controla um endereço de carteira específico. A saída assinada pode ser verificada por qualquer terceiro sem acessar suas chaves privadas.

Assinatura de Mensagem

Assine mensagens de texto simples para comprovar a propriedade da carteira. Funciona em todas as blockchains suportadas: EVM, Tron e Solana.

Assinatura de Dados Tipados

Assine dados estruturados seguindo o padrão EIP-712. Usado para aprovações sem gas (EIP-2612 Permit) e transferências autorizadas (EIP-3009). Apenas EVM.

​
Casos de uso comuns

  • Registro em provedores terceiros — Comprove que você é proprietário de um endereço ao se cadastrar em serviços como Iron, Circle ou outros protocolos DeFi
  • Aprovações de tokens sem gas — Assine mensagens EIP-2612 Permit para autorizar gastos de tokens sem uma transação on-chain
  • Transferências autorizadas — Assine mensagens EIP-3009 TransferWithAuthorization para transferências delegadas
  • Atestações off-chain — Crie provas verificáveis de intenção ou acordo vinculadas a um endereço de carteira

​
Carteira Mestra vs Endereço Filho

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

Carteira Mestra

Assine usando as chaves da carteira mestra. Ideal para operações de tesouraria e integrações com provedores.

Endereço Filho

Assine usando as chaves de um endereço filho específico. Use quando o terceiro exigir uma assinatura de um endereço de depósito.

​
Endpoints

OperaçãoCarteira MestraEndereço Filho
Assinar MensagemPOST /v1/wallets/{walletId}/signing/messagePOST /v1/wallets/{walletId}/addresses/{addressId}/signing/message
Assinar Dados TipadosPOST /v1/wallets/{walletId}/signing/typed-dataPOST /v1/wallets/{walletId}/addresses/{addressId}/signing/typed-data

​
Assinatura de Mensagem

Assine uma mensagem de texto simples com a chave privada da sua carteira. A API assina a mensagem, verifica se a assinatura corresponde ao endereço da carteira e retorna tanto a assinatura quanto um registro de transação.

​
Blockchains Suportadas

BlockchainPadrão de AssinaturaFormato da Assinatura
EVM (Ethereum, Polygon, BSC, Base, Arbitrum, Optimism, Celo)EIP-191 (personal_sign)Codificado em hex com componentes r, s, v
TronTronWeb signMessageV2String codificada em hex
SolanaEd25519String codificada em Base58

​
Parâmetros da Requisição

ParâmetroTipoObrigatórioDescrição
messagestringSimA mensagem de texto simples a ser assinada. Máximo de 4.096 caracteres.
referencestringNãoSeu ID de rastreamento interno. Use para idempotência — referências duplicadas são rejeitadas.
metadataobjectNãoPares chave-valor personalizados armazenados com o registro da transação.

​
Exemplo de Assinatura de Mensagem

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/signing/message \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "message": "Please sign this message to verify your wallet ownership for Iron provider registration.",
    "reference": "iron-verification-001",
    "metadata": {
      "provider": "iron",
      "purpose": "wallet-verification"
    }
  }'

​
Resposta EVM

{
  "message": "Message signed successfully",
  "statusCode": 200,
  "data": {
    "id": "770f9100-7338-4823-b1ce-3658fc67db09",
    "hash": "0xdb095e6cbf235d630cee43e0953e60c351e46897bc4e65abfce3e975810e21335aa3918399dac1e01badb2dc8c59c171e65d0c328c92737de702da9d76b889b31b",
    "status": "SUCCESS",
    "type": "SIGNED",
    "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "recipientAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "signedTransaction": {
      "r": "0xdb095e6cbf235d630cee43e0953e60c351e46897bc4e65abfce3e975810e2133",
      "s": "0x5aa3918399dac1e01badb2dc8c59c171e65d0c328c92737de702da9d76b889b3",
      "v": 27,
      "signature": "0xdb095e6cbf...b31b"
    },
    "reference": "iron-verification-001",
    "metadata": {
      "provider": "iron",
      "purpose": "wallet-verification"
    },
    "confirmed": true,
    "createdAt": "2025-03-02T19:00:52.000Z"
  }
}

​
Resposta Tron / Solana

Para Tron e Solana, o objeto signedTransaction contém apenas o campo signature (sem componentes r, s, v): 
{
  "message": "Message signed successfully",
  "statusCode": 200,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "hash": "3xYkZ9...",
    "status": "SUCCESS",
    "type": "SIGNED",
    "senderAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRT9Y",
    "recipientAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRT9Y",
    "signedTransaction": {
      "signature": "3xYkZ9..."
    },
    "reference": "tron-verification-001",
    "confirmed": true,
    "createdAt": "2025-03-02T19:00:52.000Z"
  }
}

​
Campos da Resposta

CampoDescrição
idID único da transação para o registro de assinatura
hashA assinatura criptográfica. Para EVM: string hex. Para Tron: string hex. Para Solana: string base58.
statusSempre SUCCESS para assinaturas concluídas
typeSempre SIGNED para transações de assinatura
senderAddressO endereço da carteira que produziu a assinatura
signedTransactionComponentes da assinatura. EVM inclui r, s, v e signature completa. Tron e Solana incluem apenas signature.
referenceSua string de referência fornecida (se houver)
metadataSeu objeto de metadados fornecido (se houver)

​
Assinatura de Dados Tipados (Apenas EVM)

Assine dados estruturados seguindo o padrão EIP-712. Isso é usado para aprovações sem gas, transferências delegadas e outros fluxos de autorização on-chain que requerem uma assinatura estruturada.
A assinatura de dados tipados está disponível apenas para blockchains compatíveis com EVM (Ethereum, Polygon, BSC, Base, Arbitrum, Optimism, Celo). Tron e Solana não suportam EIP-712.

​
Padrões Suportados

PadrãoCaso de Uso
EIP-712Assinatura genérica de dados estruturados
EIP-2612 (Permit)Aprovações de tokens sem gas — aprove gastos sem uma transação on-chain
EIP-3009 (TransferWithAuthorization)Transferências delegadas — autorize uma transferência que um terceiro submete

​
Parâmetros da Requisição

ParâmetroTipoObrigatórioDescrição
domainobjectSimSeparador de domínio EIP-712. Inclui name, version, chainId e verifyingContract.
typesobjectSimDefinições de tipo para os dados estruturados.
messageobjectSimOs dados a serem assinados, em conformidade com as definições de tipo.

​
Exemplo EIP-2612 Permit

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/signing/typed-data \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "domain": {
      "name": "USD Coin",
      "version": "2",
      "chainId": 11155111,
      "verifyingContract": "0xa0b86a33e6441b8c4c8c0c077bcdd28571685701"
    },
    "types": {
      "Permit": [
        { "name": "owner", "type": "address" },
        { "name": "spender", "type": "address" },
        { "name": "value", "type": "uint256" },
        { "name": "nonce", "type": "uint256" },
        { "name": "deadline", "type": "uint256" }
      ]
    },
    "message": {
      "owner": "0x742d35cc6634c0532925a3b8d4c9db96c4b4d8b6",
      "spender": "0x8ba1f109551bd432803012645aac136c4c8c8c0c",
      "value": "1000000000",
      "nonce": "0",
      "deadline": "1641081600"
    }
  }'

​
Resposta de Dados Tipados

{
  "message": "Typed data signed successfully",
  "statusCode": 200,
  "data": {
    "id": "770f9100-7338-4823-b1ce-3658fc67db09",
    "hash": "0xdb095e6cbf235d630cee43e0953e60c351e46897bc4e65abfce3e975810e21335aa3918399dac1e01badb2dc8c59c171e65d0c328c92737de702da9d76b889b31b",
    "status": "SUCCESS",
    "type": "SIGNED",
    "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "recipientAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "signedTransaction": {
      "r": "0xdb095e6cbf235d630cee43e0953e60c351e46897bc4e65abfce3e975810e2133",
      "s": "0x5aa3918399dac1e01badb2dc8c59c171e65d0c328c92737de702da9d76b889b3",
      "v": 27,
      "signature": "0xdb095e6cbf...b31b"
    },
    "confirmed": true,
    "createdAt": "2025-03-02T19:00:52.000Z"
  }
}

​
Campos do Objeto Domain

CampoTipoObrigatórioDescrição
namestringSimO nome do domínio de assinatura (ex.: o nome do token ou do dApp)
versionstringSimA versão do domínio
chainIdnumberSimO ID da chain. Deve corresponder à rede blockchain da carteira.
verifyingContractstringSimO endereço do contrato que verificará a assinatura
saltstringNãoSalt de domínio opcional para EIP-712 v4
Validação do Chain ID
O chainId no seu objeto de domínio deve corresponder ao chain ID da rede blockchain da carteira. Se não corresponderem, a API retorna um erro 400 Chain ID mismatch.

​
Assinatura com Endereço Filho

Assine mensagens ou dados tipados usando um endereço filho específico em vez da carteira mestra: 
curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/signing/message \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "message": "Verify ownership of deposit address for provider onboarding.",
    "reference": "address-verify-001"
  }'
A assinatura com endereço filho segue o mesmo formato de requisição e resposta da assinatura com carteira mestra. A única diferença é a URL do endpoint, que inclui o addressId.

​
Eventos de Webhook

Operações de assinatura disparam um webhook com o registro da transação:
EventoDescrição
signed.successMensagem ou dados tipados assinados e verificados

​
Payload do Webhook

{
  "event": "signed.success",
  "data": {
    "id": "770f9100-7338-4823-b1ce-3658fc67db09",
    "hash": "0xdb095e6cbf...b31b",
    "status": "SUCCESS",
    "type": "SIGNED",
    "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "recipientAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "signedTransaction": {
      "r": "0xdb095e6cbf...2133",
      "s": "0x5aa3918399...89b3",
      "v": 27,
      "signature": "0xdb095e6cbf...b31b"
    },
    "reference": "iron-verification-001",
    "metadata": {
      "provider": "iron",
      "purpose": "wallet-verification"
    },
    "wallet": {
      "id": "d236a191-c1d4-423c-a439-54ce6542ca41",
      "name": "Ethereum Master Wallet"
    },
    "blockchain": {
      "name": "ethereum",
      "network": "testnet"
    },
    "confirmed": true,
    "createdAt": "2025-03-02T19:00:52.000Z"
  }
}

​
Exemplo de Fluxo Completo

Aqui está uma implementação completa para assinar uma mensagem e enviar a assinatura para um provedor terceiro: 
async function signAndVerifyWithProvider(walletId, providerMessage) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';

  // Step 1: Sign the message
  const signResponse = await fetch(
    `${baseUrl}/wallets/${walletId}/signing/message`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        message: providerMessage,
        reference: `provider-verify-${Date.now()}`
      })
    }
  ).then(r => r.json());

  if (signResponse.statusCode !== 200) {
    throw new Error(`Signing failed: ${signResponse.message}`);
  }

  const { hash, senderAddress } = signResponse.data;

  // Step 2: Submit the signature to the third-party provider
  // The provider can verify the signature matches the wallet address
  // without accessing your private keys
  return {
    address: senderAddress,
    signature: hash,
    message: providerMessage
  };
}

// Usage
signAndVerifyWithProvider(
  'wallet-uuid',
  'I authorize Iron to manage assets on my behalf.'
);

​
Respostas de Erro

{
  "message": "Wallet not found",
  "statusCode": 404
}
O walletId não existe ou não pertence ao seu negócio.
{
  "message": "Address not found",
  "statusCode": 404
}
O addressId não existe ou não está associado à carteira especificada.
{
  "message": "Typed data signing is only supported for EVM blockchains",
  "statusCode": 400
}
A assinatura de dados tipados (EIP-712) está disponível apenas em chains compatíveis com EVM. Use a assinatura de mensagem para Tron e Solana.
{
  "message": "Chain ID mismatch",
  "statusCode": 400
}
O chainId no seu objeto de domínio de dados tipados não corresponde à rede blockchain da carteira.
{
  "message": "Signature verification failed",
  "statusCode": 400
}
A verificação interna de ida e volta falhou. Isso indica um erro do sistema — entre em contato com o suporte.

​
Melhores Práticas

​
Segurança

  • Use referências — Rastreie operações de assinatura com IDs de referência únicos para trilhas de auditoria e idempotência
  • Verifique a mensagem — Antes de assinar, confirme que o conteúdo da mensagem corresponde ao que o serviço terceiro espera
  • Limite o tamanho da mensagem — Mensagens são limitadas a 4.096 caracteres. Mantenha as mensagens concisas e específicas

​
Integração

  • Sem taxas de gas — Operações de assinatura são off-chain e não requerem saldo de token nativo
  • Resposta imediata — As assinaturas são geradas de forma síncrona. Não é necessário polling ou espera por webhook para a assinatura em si
  • Ouça os webhooks — Use webhooks para manter uma trilha de auditoria de todos os eventos de assinatura

​
Dados Tipados

  • Combine os chain IDs — O chainId no seu domínio deve corresponder à rede da carteira. Use chain IDs de sandbox (testnet) para testes e chain IDs de produção (mainnet) para operações em produção
  • Verifique o contrato — O verifyingContract deve ser o contrato que verificará a assinatura on-chain

​
Referência da API

​
Endpoints da Carteira Mestra

EndpointDescrição
Assinar MensagemAssinar uma mensagem de texto simples
Assinar Dados TipadosAssinar dados estruturados EIP-712

​
Endpoints do Endereço Filho

EndpointDescrição
Assinar MensagemAssinar uma mensagem de texto simples a partir de um endereço filho
Assinar Dados TipadosAssinar dados estruturados EIP-712 a partir de um endereço filho