Cómo obtener todas las transferencias de una billetera de Solana

La Wallet API está en versión beta. Los endpoints y formatos de respuesta pueden cambiar.

Descripción general

El endpoint Token Transfers recupera toda la actividad de transferencias de tokens de una billetera de Solana, incluida información detallada del remitente y el destinatario. A diferencia del historial de transacciones completo, este endpoint se centra específicamente en las transferencias, por lo que es ideal para rastrear pagos y monitorear transferencias. El endpoint devuelve hasta 100 transferencias por solicitud (50 de forma predeterminada). Usa el parámetro cursor con pagination.nextCursor para obtener la siguiente página y consulta pagination.hasMore para saber cuándo hay más resultados disponibles.

Cuándo usarlo

Usa la API Token Transfers cuando necesites:

Rastrear pagos: monitorea los pagos entrantes para procesadores de pagos.
Crear un feed de transferencias: muestra un feed sencillo de actividad con estados “enviado/recibido”.
Monitorear tokens específicos: rastrea las transferencias de un token específico (por ejemplo, pagos en USDC).
Identificar contrapartes: consulta quién envió o recibió tokens.
Generar recibos: crea recibos de pago con los datos del remitente y destinatario.
Detectar actividad sospechosa: monitorea patrones de transferencia inusuales.

Inicio rápido

Consulta básica de transferencias

Obtén las transferencias entrantes y salientes recientes:

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 dirección

Filtra los resultados del lado del cliente para obtener solo las transferencias entrantes o salientes:

Incoming Only
Outgoing Only

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	Valor predeterminado	Descripción
`limit`	entero	50	Número máximo de transferencias que se devolverán (1-100)
`cursor`	cadena	-	Cursor de paginación de la respuesta anterior

Formato de respuesta

{
  "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 sobre los campos

direction: relativo a la billetera que consultas. in corresponde a tokens recibidos (pago entrante); out corresponde a tokens enviados (pago saliente).
counterparty: para transferencias in, el remitente; para transferencias out, el destinatario.
amount: monto de la transferencia legible para humanos, ya dividido por decimals. Úsalo para mostrar el monto (por ejemplo, 1.5 SOL, 100.0 USDC).
amountRaw: el mismo monto como una cadena de entero sin procesar, antes del ajuste decimal (por ejemplo, "1500000000" para 1.5 SOL). Se serializa como una cadena para evitar la pérdida de precisión de punto flotante. Úsalo para instrucciones on-chain o cálculos precisos: amount = parseInt(amountRaw) / 10**decimals.
mint: dirección de mint del token (So11111111111111111111111111111111111111111 para SOL nativo).
symbol: símbolo del token. No todos los tokens tienen uno; usa la dirección de mint como alternativa cuando symbol sea null.

Casos de uso

Rastrear el historial de pagos de un comercio

Monitorea los pagos entrantes en USDC:

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
  };
};

Generar un recibo de pago

Crea un recibo detallado para una transferencia 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;
};

Monitorear patrones de transferencia sospechosos

Detecta actividad de transferencia inusual:

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
  };
};

Crear un feed de actividad de transferencias

Crea un feed de actividad fácil de usar:

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 pagos

Compara las transferencias con los pagos 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);

Paginación

Para las billeteras con muchas transferencias, recorre los resultados página por página con el parámetro cursor y 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;
};

Prácticas recomendadas

Filtra tokens específicos del lado del cliente. La API devuelve todas las transferencias de tokens. Filtra por la dirección mint para rastrear tokens específicos como USDC o SOL.
Combínala con la Identity API. Usa el endpoint Identity para mostrar nombres legibles para humanos de contrapartes conocidas (exchanges, protocolos y otras).
Almacena en caché las transferencias recientes. Los datos de las transferencias no cambian. Almacena los resultados en caché y recupera únicamente las transferencias nuevas desde tu última consulta.
Usa la paginación para obtener el historial completo. Implementa la paginación para gestionar de forma eficiente billeteras con miles de transferencias.
Gestiona los símbolos faltantes. No todos los tokens tienen un campo symbol. Usa la dirección de mint como alternativa cuando symbol sea null.

Transferencias frente al historial de transacciones

Característica	Transferencias	Historial de transacciones
Enfoque	Solo transferencias de tokens	Todos los tipos de transacciones
Datos	Información del remitente y destinatario	Cambios de saldo de todos los tokens
Caso de uso	Rastreo de pagos	Registro completo de actividad
Rendimiento	Más rápido y sencillo	Más completo

Usa Transferencias cuando solo te interesen los pagos. Usa el Historial de transacciones cuando necesites datos completos sobre los cambios de saldo.

Errores comunes

Código de error	Descripción	Solución
400	Formato de dirección de billetera no válido	Verifica que la dirección sea una dirección de Solana válida en base58
401	Clave de API faltante o no válida	Comprueba que tu clave de API esté incluida en la solicitud
429	Límite de solicitudes excedido	Reduce la frecuencia de las solicitudes o mejora tu plan

Próximos pasos

Wallet History

Historial completo de transacciones con cambios de saldo por transacción.

Wallet API Overview

Todos los endpoints de Wallet API y las convenciones compartidas.

API Reference

Esquemas de solicitudes y respuestas para transferencias de tokens.

Primeros pasos

Streaming de datos y escucha de eventos

API de datos y RPC

Trading

Envío de transacciones

Billetera como servicio

Privacidad

Recursos

Cómo obtener todas las transferencias de una billetera de Solana

Descripción general

Cuándo usarlo

Inicio rápido

Consulta básica de transferencias

Filtrar por dirección

Parámetros de consulta

Formato de respuesta

Notas sobre los campos

Casos de uso

Rastrear el historial de pagos de un comercio

Generar un recibo de pago

Monitorear patrones de transferencia sospechosos

Crear un feed de actividad de transferencias

Conciliar pagos

Paginación

Prácticas recomendadas

Transferencias frente al historial de transacciones

Errores comunes

Próximos pasos

Wallet History

Wallet API Overview

API Reference

​Descripción general

​Cuándo usarlo

​Inicio rápido

​Consulta básica de transferencias

​Filtrar por dirección

​Parámetros de consulta

​Formato de respuesta

​Notas sobre los campos

​Casos de uso

​Rastrear el historial de pagos de un comercio

​Generar un recibo de pago

​Monitorear patrones de transferencia sospechosos

​Crear un feed de actividad de transferencias

​Conciliar pagos

​Paginación

​Prácticas recomendadas

​Transferencias frente al historial de transacciones

​Errores comunes

​Próximos pasos

Wallet History

Wallet API Overview

API Reference

Descripción general

Cuándo usarlo

Inicio rápido

Consulta básica de transferencias

Filtrar por dirección

Parámetros de consulta

Formato de respuesta

Notas sobre los campos

Casos de uso

Rastrear el historial de pagos de un comercio

Generar un recibo de pago

Monitorear patrones de transferencia sospechosos

Crear un feed de actividad de transferencias

Conciliar pagos

Paginación

Prácticas recomendadas

Transferencias frente al historial de transacciones

Errores comunes

Próximos pasos