Como Obter Todas as Transferências de Carteira Solana

A Wallet API está em Beta. Endpoints e formatos de resposta podem mudar.

Visão Geral

O endpoint de Transferências de Tokens recupera toda a atividade de transferências de tokens para uma carteira Solana, incluindo informações detalhadas do remetente e destinatário. Ao contrário do histórico de transações completo, este endpoint foca especificamente em transferências, sendo ideal para rastreamento de pagamentos e monitoramento de transferências. O endpoint retorna até 100 transferências por solicitação (padrão 50). Use o parâmetro cursor com pagination.nextCursor para buscar a próxima página, e leia pagination.hasMore para saber quando mais resultados estão disponíveis.

Quando usar isto

Use a API de Transferências de Tokens quando você precisar:

Rastrear pagamentos: monitorar pagamentos recebidos para processadores de pagamento.
Construir um feed de transferências: exibir um feed de atividades “enviado/recebido” simples.
Monitorar tokens específicos: rastrear transferências de um token específico (por exemplo, pagamentos USDC).
Identificar contrapartes: ver quem enviou ou recebeu tokens.
Gerar recibos: criar recibos de pagamento com detalhes do remetente/destinatário.
Detectar atividade suspeita: monitorar padrões de transferências incomuns.

Início Rápido

Consulta básica de transferências

Obter transferências recentes de entrada e saída:

JavaScript
Python
cURL

const getWalletTransfers = async (address) => {
  const url = `https://api.helius.xyz/v1/wallet/${address}/transfers?api-key=YOUR_API_KEY`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();

  console.log(`Found ${data.data.length} transfers`);

  // Display recent transfers
  data.data.forEach(transfer => {
    const date = new Date(transfer.timestamp * 1000).toLocaleString();
    const direction = transfer.direction === 'in' ? 'Received' : 'Sent';
    const counterparty = transfer.counterparty.slice(0, 8) + '...';

    console.log(`\n${direction} - ${date}`);
    console.log(`Amount: ${transfer.amount} ${transfer.symbol || transfer.mint.slice(0, 8) + '...'}`);
    console.log(`${transfer.direction === 'in' ? 'From' : 'To'}: ${counterparty}`);
    console.log(`Signature: ${transfer.signature.slice(0, 20)}...`);
  });

  return data;
};

getWalletTransfers("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");

import requests
from datetime import datetime

def get_wallet_transfers(address: str):
    url = f"https://api.helius.xyz/v1/wallet/{address}/transfers"
    headers = {"X-Api-Key": "YOUR_API_KEY"}

    response = requests.get(url, headers=headers)
    response.raise_for_status()

    data = response.json()

    print(f"Found {len(data['data'])} transfers")

    # Display recent transfers
    for transfer in data['data']:
        date = datetime.fromtimestamp(transfer['timestamp']).strftime('%Y-%m-%d %H:%M:%S')
        direction = 'Received' if transfer['direction'] == 'in' else 'Sent'
        counterparty = transfer['counterparty'][:8] + '...'
        symbol = transfer.get('symbol') or transfer['mint'][:8] + '...'

        print(f"\n{direction} - {date}")
        print(f"Amount: {transfer['amount']} {symbol}")
        print(f"{'From' if transfer['direction'] == 'in' else 'To'}: {counterparty}")
        print(f"Signature: {transfer['signature'][:20]}...")

    return data

get_wallet_transfers("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")

curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/transfers?api-key=YOUR_API_KEY"

Filtrar por direção

Filtre os resultados no lado do cliente para obter apenas transferências de entrada ou saída:

Apenas Entrada
Apenas Saída

const getIncomingTransfers = async (address) => {
  const data = await getWalletTransfers(address);

  const incoming = data.data.filter(t => t.direction === 'in');

  console.log(`Received ${incoming.length} incoming transfers`);

  incoming.forEach(transfer => {
    console.log(`Received ${transfer.amount} ${transfer.symbol} from ${transfer.counterparty.slice(0, 8)}...`);
  });

  return incoming;
};

const getOutgoingTransfers = async (address) => {
  const data = await getWalletTransfers(address);

  const outgoing = data.data.filter(t => t.direction === 'out');

  console.log(`Made ${outgoing.length} outgoing transfers`);

  outgoing.forEach(transfer => {
    console.log(`Sent ${transfer.amount} ${transfer.symbol} to ${transfer.counterparty.slice(0, 8)}...`);
  });

  return outgoing;
};

Parâmetros de consulta

Parâmetro	Tipo	Padrão	Descrição
`limit`	integer	50	Número máximo de transferências a retornar (1-100)
`cursor`	string	-	Cursor de paginação da resposta anterior

Formato de resposta

{
  "data": [
    {
      "signature": "5wHu1qwD7Jsj3xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE",
      "timestamp": 1704067200,
      "direction": "in",
      "counterparty": "HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664",
      "mint": "So11111111111111111111111111111111111111111",
      "symbol": "SOL",
      "amount": 1.5,
      "amountRaw": "1500000000",
      "decimals": 9
    },
    {
      "signature": "4aHu2qwD8Jtj4xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE",
      "timestamp": 1704067100,
      "direction": "out",
      "counterparty": "2ojv9BAiHUrvsm9gxDe7fJSzbNZSJcxZvf8dqmWGHG8S",
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "amount": 100.0,
      "amountRaw": "100000000",
      "decimals": 6
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "5wHu1qwD7Jsj3xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE"
  }
}

Notas de campo

direction: relativo à carteira que você está consultando. in são tokens recebidos (pagamento de entrada); out são tokens enviados (pagamento de saída).
counterparty: para transferências in, o remetente; para transferências out, o destinatário.
amount: quantidade de transferência legível por humanos, já dividida por decimals. Use isto para exibição (por exemplo, 1.5 SOL, 100.0 USDC).
amountRaw: a mesma quantidade como uma string inteira bruta, antes do ajuste decimal (por exemplo, "1500000000" para 1.5 SOL). Serializado como uma string para evitar perda de precisão de ponto flutuante. Use isto para instruções on-chain ou aritmética precisa: amount = parseInt(amountRaw) / 10**decimals.
mint: endereço de mint de token (So11111111111111111111111111111111111111111 para SOL nativo).
symbol: símbolo do token. Nem todos os tokens têm um; retorne ao endereço de mint quando symbol for null.

Casos de uso

Rastrear o histórico de pagamentos para um comerciante

Monitorar pagamentos de USDC recebidos:

const trackMerchantPayments = async (merchantWallet) => {
  const data = await getWalletTransfers(merchantWallet);

  // Filter for incoming USDC transfers
  const usdcPayments = data.data.filter(t =>
    t.direction === 'in' &&
    t.mint === 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC
  );

  console.log(`Received ${usdcPayments.length} USDC payments`);

  const totalReceived = usdcPayments.reduce((sum, t) => sum + t.amount, 0);
  console.log(`Total USDC Received: $${totalReceived.toFixed(2)}`);

  // Display each payment
  usdcPayments.forEach(payment => {
    const date = new Date(payment.timestamp * 1000).toLocaleString();
    console.log(`${date}: $${payment.amount} from ${payment.counterparty}`);
  });

  return {
    count: usdcPayments.length,
    total: totalReceived,
    payments: usdcPayments
  };
};

Gerar um recibo de pagamento

Criar um recibo detalhado para uma transferência específica:

const generatePaymentReceipt = async (address, signature) => {
  const data = await getWalletTransfers(address);

  const transfer = data.data.find(t => t.signature === signature);

  if (!transfer) {
    console.log('Transfer not found');
    return null;
  }

  const receipt = {
    receiptId: transfer.signature.slice(0, 16),
    date: new Date(transfer.timestamp * 1000).toISOString(),
    type: transfer.direction === 'in' ? 'Payment Received' : 'Payment Sent',
    amount: `${transfer.amount} ${transfer.symbol || 'tokens'}`,
    from: transfer.direction === 'in' ? transfer.counterparty : address,
    to: transfer.direction === 'out' ? transfer.counterparty : address,
    transactionUrl: `https://orbmarkets.io/tx/${transfer.signature}`
  };

  console.log('--- PAYMENT RECEIPT ---');
  Object.entries(receipt).forEach(([key, value]) => {
    console.log(`${key}: ${value}`);
  });

  return receipt;
};

Monitorar padrões de transferências suspeitas

Detectar atividade de transferência incomum:

const detectSuspiciousActivity = async (address) => {
  const data = await getWalletTransfers(address);

  const recentTransfers = data.data.filter(t => {
    const hourAgo = Date.now() / 1000 - 3600;
    return t.timestamp > hourAgo;
  });

  // Check for high frequency
  if (recentTransfers.length > 100) {
    console.log(`Warning: ${recentTransfers.length} transfers in the last hour`);
  }

  // Check for large amounts
  const largeTransfers = recentTransfers.filter(t => {
    // Assuming USDC/stablecoins
    return t.amount > 10000 && t.decimals === 6;
  });

  if (largeTransfers.length > 0) {
    console.log(`Warning: ${largeTransfers.length} large transfers (>$10k) in the last hour`);
  }

  // Check for transfers to same address
  const counterparties = recentTransfers.map(t => t.counterparty);
  const duplicates = counterparties.filter((item, index) => counterparties.indexOf(item) !== index);

  if (duplicates.length > 5) {
    console.log(`Warning: Multiple transfers to the same address`);
  }

  return {
    recentCount: recentTransfers.length,
    largeTransfers: largeTransfers.length,
    suspiciousPatterns: duplicates.length > 5
  };
};

Construir um feed de atividades de transferências

Criar um feed de atividades amigável ao usuário:

const buildTransferFeed = async (address) => {
  const data = await getWalletTransfers(address);

  const feed = data.data.map(transfer => {
    const date = new Date(transfer.timestamp * 1000);
    const timeAgo = getTimeAgo(date);

    return {
      id: transfer.signature,
      direction: transfer.direction,
      title: transfer.direction === 'in' ? 'Received' : 'Sent',
      subtitle: `${transfer.amount} ${transfer.symbol || 'tokens'}`,
      description: transfer.direction === 'in'
        ? `from ${transfer.counterparty.slice(0, 8)}...`
        : `to ${transfer.counterparty.slice(0, 8)}...`,
      timeAgo,
      explorerUrl: `https://orbmarkets.io/tx/${transfer.signature}`
    };
  });

  return feed;
};

function getTimeAgo(date) {
  const seconds = Math.floor((new Date() - date) / 1000);

  if (seconds < 60) return 'Just now';
  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
  return `${Math.floor(seconds / 86400)}d ago`;
}

Conciliar pagamentos

Corresponder transferências com pagamentos esperados:

const reconcilePayments = async (address, expectedPayments) => {
  const data = await getWalletTransfers(address);

  const recentTransfers = data.data.filter(t =>
    t.direction === 'in' &&
    t.mint === 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' // USDC
  );

  const reconciliation = expectedPayments.map(expected => {
    const match = recentTransfers.find(t =>
      Math.abs(t.amount - expected.amount) < 0.01 &&
      t.counterparty === expected.from
    );

    return {
      orderId: expected.orderId,
      expectedAmount: expected.amount,
      status: match ? 'Received' : 'Pending',
      receivedAmount: match?.amount,
      signature: match?.signature,
      timestamp: match?.timestamp
    };
  });

  console.log('Payment Reconciliation:');
  reconciliation.forEach(r => {
    console.log(`Order ${r.orderId}: ${r.status}`);
  });

  return reconciliation;
};

// Example usage
const expected = [
  { orderId: 'ORDER-001', amount: 100.00, from: 'ABC...' },
  { orderId: 'ORDER-002', amount: 250.50, from: 'XYZ...' }
];

reconcilePayments("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", expected);

Paginação

Para carteiras com muitas transferências, percorra os resultados com o parâmetro cursor e pagination.hasMore:

const getAllTransfers = async (address) => {
  let allTransfers = [];
  let cursor = null;

  do {
    const url = cursor
      ? `https://api.helius.xyz/v1/wallet/${address}/transfers?api-key=YOUR_API_KEY&cursor=${cursor}`
      : `https://api.helius.xyz/v1/wallet/${address}/transfers?api-key=YOUR_API_KEY`;

    const response = await fetch(url);
    const data = await response.json();

    allTransfers = allTransfers.concat(data.data);
    cursor = data.pagination.hasMore ? data.pagination.nextCursor : null;

    console.log(`Fetched ${allTransfers.length} transfers so far...`);

  } while (cursor);

  console.log(`\nTotal transfers: ${allTransfers.length}`);
  return allTransfers;
};

Melhores práticas

Filtrar no lado do cliente por tokens específicos. A API retorna todas as transferências de tokens. Filtre pelo endereço mint para rastrear tokens específicos como USDC ou SOL.
Combine com a API de Identidade. Use o endpoint Identity para mostrar nomes legíveis por humanos para contrapartes conhecidas (exchanges, protocolos e outros).
Cache de transferências recentes. Dados de transferência não mudam. Armazene os resultados em cache e busque apenas transferências novas desde sua última consulta.
Paginar para histórico completo. Implemente paginação para lidar com carteiras com milhares de transferências de forma eficiente.
Tratar símbolo ausente. Nem todos os tokens têm um campo symbol. Retorne ao endereço de mint quando symbol for null.

Transferências vs histórico de transações

Recurso	Transferências	Histórico de Transações
Foco	Apenas transferências de tokens	Todos os tipos de transação
Dados	Info de remetente/destinatário	Alterações de saldo para todos os tokens
Caso de uso	Rastreamento de pagamentos	Registro completo de atividades
Desempenho	Mais rápido, mais simples	Mais abrangente

Use Transferências quando você se preocupa apenas com pagamentos. Use Histórico de Transações quando precisar de dados completos de alteração de saldo.

Erros comuns

Código de Erro	Descrição	Solução
400	Formato de endereço de carteira inválido	Verifique se o endereço é um endereço válido base58 Solana
401	Chave de API ausente ou inválida	Verifique se sua chave de API está incluída na solicitação
429	Limite de taxa excedido	Reduza a frequência de solicitações ou atualize seu plano

Próximos passos

Histórico de Carteira

Histórico completo de transações com alterações de saldo por transação.

Visão Geral da Wallet API

Todos os endpoints da Wallet API e convenções compartilhadas.

Referência da API

Esquemas de requisição e resposta para transferências de tokens.

Primeiros Passos

Transmissão de Dados & Escuta de Eventos

APIs de Dados & RPCs

Negociação

Envio de Transações

Carteira como Serviço

Guias

Recursos

Como Obter Todas as Transferências de Carteira Solana

Visão Geral

Quando usar isto

Início Rápido

Consulta básica de transferências

Filtrar por direção

Parâmetros de consulta

Formato de resposta

Notas de campo

Casos de uso

Rastrear o histórico de pagamentos para um comerciante

Gerar um recibo de pagamento

Monitorar padrões de transferências suspeitas

Construir um feed de atividades de transferências

Conciliar pagamentos

Paginação

Melhores práticas

Transferências vs histórico de transações

Erros comuns

Próximos passos

Histórico de Carteira

Visão Geral da Wallet API

Referência da API

​Visão Geral

​Quando usar isto

​Início Rápido

​Consulta básica de transferências

​Filtrar por direção

​Parâmetros de consulta

​Formato de resposta

​Notas de campo

​Casos de uso

​Rastrear o histórico de pagamentos para um comerciante

​Gerar um recibo de pagamento

​Monitorar padrões de transferências suspeitas

​Construir um feed de atividades de transferências

​Conciliar pagamentos

​Paginação

​Melhores práticas

​Transferências vs histórico de transações

​Erros comuns

​Próximos passos

Histórico de Carteira

Visão Geral da Wallet API

Referência da API

Visão Geral

Quando usar isto

Início Rápido

Consulta básica de transferências

Filtrar por direção

Parâmetros de consulta

Formato de resposta

Notas de campo

Casos de uso

Rastrear o histórico de pagamentos para um comerciante

Gerar um recibo de pagamento

Monitorar padrões de transferências suspeitas

Construir um feed de atividades de transferências

Conciliar pagamentos

Paginação

Melhores práticas

Transferências vs histórico de transações

Erros comuns

Próximos passos