Como Obter Tokens Solana SPL: Guia Completo da API

Visão Geral

Este guia cobre a leitura de tokens fungíveis no Solana: saldos de contas, contas de token por proprietário ou mint, oferta total, maiores detentores e a extensão de token fungível DAS. O Helius expõe tanto os métodos padrão de token RPC do Solana quanto os métodos DAS que adicionam metadados e preços em USD. Para NFTs, NFTs comprimidos, edições e provas, veja o guia Get Assets. Esta página foca em tokens fungíveis (SPL e Token-2022).

Quando usar isso

Use os métodos nesta página quando você estiver:

Lendo o saldo de uma única conta de token
Listando todas as contas de token que uma carteira possui
Encontrando todas as contas que possuem um mint específico
Verificando a oferta total de um token ou seus maiores detentores
Buscando metadados de token e preço em USD junto com os saldos

Saldo de conta de token

Obtenha o saldo para uma conta de token específica usando RPC padrão:

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: '1',
    method: 'getTokenAccountBalance',
    params: [
      '3emsAVdmGKERbHjmGfQ6oZ1e35dkf5iYcS6U4CPKFVaa'
    ]
  })
});
const data = await response.json();
console.log(data);

Referência da API

getTokenAccountBalance

Contas de token por proprietário

Liste todas as contas de token de uma carteira:

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: '1',
    method: 'getTokenAccountsByOwner',
    params: [
      '86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY',
      {
        programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
      },
      {
        encoding: 'jsonParsed'
      }
    ]
  })
});
const data = await response.json();
console.log(data);

Referência da API

getTokenAccountsByOwner

Contas de token por mint

Liste todas as contas que possuem um token específico:

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: '1',
    method: 'getTokenAccountsByOwner',
    params: [
      'CEXq1uy9y15PL2Wb4vDQwQfcJakBGjaAjeuR2nKLj8dk',
      {
        mint: "8wXtPeU6557ETkp9WHFY1n1EcU6NxDvbAggHGsMYiHsB"
      },
      {
        encoding: 'jsonParsed'
      }
    ]
  })
});
const data = await response.json();
console.log(data);

Referência da API

getTokenAccountsByOwner

Para encontrar todas as contas que possuem um mint em todos os proprietários (não apenas um proprietário), use o método DAS getTokenAccounts descrito abaixo.

Oferta de token

Verifique a oferta total de um token:

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: '1',
    method: 'getTokenSupply',
    params: [
      'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
    ]
  })
});
const data = await response.json();
console.log(data);

Referência da API

getTokenSupply

Maiores detentores de tokens

Identifique as maiores contas que possuem um token:

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: '1',
    method: 'getTokenLargestAccounts',
    params: [
      'he1iusmfkpAdwvxLNGV8Y1iSbj4rUy6yMhEA3fotn9A'
    ]
  })
});
const data = await response.json();
console.log(data);

Referência da API

getTokenLargestAccounts

Retorna até as 20 maiores contas para o mint:

{
  "context": { "slot": 0 },
  "value": [
    { "address": "...", "amount": "1000000000000", "decimals": 9, "uiAmount": 1000.0, "uiAmountString": "1000" }
  ]
}

Contas de token com a API DAS

O método DAS getTokenAccounts retorna contas de token por mint ou proprietário, incluindo saldos, em uma única chamada paginada. Ao contrário de getTokenAccountsByOwner, você pode consultar por mint sozinho para listar todas as contas que possuem um token em todos os proprietários.

const url = `https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY`;

const getTokenAccounts = async (params) => {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "my-request-id",
      method: "getTokenAccounts",
      params: params,
    }),
  });

  const { result } = await response.json();
  return result;
};

// Example: Get all accounts holding a specific token
getTokenAccounts({
  mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
  page: 1,
  limit: 100
});

Referência da API

getTokenAccounts

Paginada; cada entrada inclui a conta, mint, proprietário e saldo:

{
  "total": 100,
  "limit": 100,
  "page": 1,
  "token_accounts": [
    { "address": "...", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "owner": "...", "amount": 12345678 }
  ]
}

Metadados de token e preço com a API DAS

Para metadados de token e preço em USD, chame o método DAS getAsset com showFungible habilitado. Os preços para tokens verificados são retornados sob token_info.price_info.

Os dados de preço de getAsset são armazenados em cache por até 600 segundos, então podem ter até 10 minutos de idade.

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: '1',
    method: 'getAsset',
    params: {
      id: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263', // Bonk
      options: {
        showFungible: true
      }
    }
  })
});
const { result } = await response.json();
console.log(result.token_info.price_info);

Referência da API

getAsset

A resposta retorna a oferta, decimais e preço sob token_info:

{
  "token_info": {
    "symbol": "Bonk",
    "supply": 8881594973561640000,
    "decimals": 5,
    "token_program": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "price_info": {
      "price_per_token": 0.0000192271,
      "currency": "USDC"
    }
  }
}

Calcular valor de mercado

Multiplique o preço pela oferta ajustada por decimais:

const { price_per_token } = result.token_info.price_info;
const { supply, decimals } = result.token_info;
const marketCap = (supply / Math.pow(10, decimals)) * price_per_token;

Para listar todos os tokens fungíveis em uma carteira (com saldos e preços) em uma única chamada, use getAssetsByOwner ou searchAssets com tokenType: "fungible". Veja a extensão de token fungível para como tokenType, saldos, extensões Token-2022 e dados de preço aparecem na resposta.

Melhores práticas

Use paginação para métodos que retornam grandes conjuntos de resultados. Veja o guia de Paginação.
Prefira métodos DAS (getAsset, getAssetsByOwner, getTokenAccounts) quando precisar de metadados ou preços em USD; use métodos RPC padrão para saldos brutos na cadeia e oferta.
Trate erros graciosamente com blocos try/catch e tentativas de nova execução.
Armazene respostas em cache quando apropriado para reduzir chamadas de API.

Próximos passos

Extensão de Token Fungível

Como DAS retorna tokens fungíveis, extensões Token-2022 e preços.

Obter Ativos (NFTs)

Recupere NFTs, NFTs comprimidos, edições e provas.

Referência da API DAS

Esquemas completos para cada método DAS.

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 Tokens Solana SPL: Guia Completo da API

Visão Geral

Quando usar isso

Saldo de conta de token

Referência da API

Contas de token por proprietário

Referência da API

Contas de token por mint

Referência da API

Oferta de token

Referência da API

Maiores detentores de tokens

Referência da API

Contas de token com a API DAS

Referência da API

Metadados de token e preço com a API DAS

Referência da API

Calcular valor de mercado

Melhores práticas

Próximos passos

Extensão de Token Fungível

Obter Ativos (NFTs)

Referência da API DAS

​Visão Geral

​Quando usar isso

​Saldo de conta de token

Referência da API

​Contas de token por proprietário

Referência da API

​Contas de token por mint

Referência da API

​Oferta de token

Referência da API

​Maiores detentores de tokens

Referência da API

​Contas de token com a API DAS

Referência da API

​Metadados de token e preço com a API DAS

Referência da API

​Calcular valor de mercado

​Melhores práticas

​Próximos passos

Extensão de Token Fungível

Obter Ativos (NFTs)

Referência da API DAS

Visão Geral

Quando usar isso

Saldo de conta de token

Contas de token por proprietário

Contas de token por mint

Oferta de token

Maiores detentores de tokens

Contas de token com a API DAS

Metadados de token e preço com a API DAS

Calcular valor de mercado

Melhores práticas

Próximos passos