Busca de Ativos Solana: Encontre NFTs, Tokens e Ativos Comprimidos

Visão Geral

searchAssets é o método de leitura mais flexível na API do DAS. Retorna ativos que correspondem a uma combinação de filtros — proprietário, agrupamento de coleções, tipo de token e atributos — em uma única chamada paginada. Use-o sempre que precisar de mais do que um único ativo ou uma lista simples por proprietário. tokenType é opcional. Quando omitido, searchAssets retorna apenas NFTs regulares e comprimidos — sem tokens fungíveis. Para incluir tokens fungíveis, defina tokenType (por exemplo, "fungible" ou "all"). Os valores aceitos são fungible, nonFungible, regularNft, compressedNft, e all.

Quando usar isso

Use searchAssets quando você estiver:

Filtrando os ativos de uma carteira apenas para tokens fungíveis ou apenas NFTs
Listando os ativos que uma carteira possui dentro de uma coleção específica
Descobrindo NFTs comprimidos em massa
Construindo rolagem infinita sobre grandes conjuntos de resultados com paginação de cursor
Filtrando ativos MPL Core por status de agente ou signatário

Para ativos individuais, use getAsset; para uma lista simples de carteira, use getAssetsByOwner.

Referência da API

Veja a documentação detalhada para searchAssets

Início Rápido

// Replace YOUR_API_KEY with your Helius API key
const url = `https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY`;

async function searchAssets(params) {
  const body = {
    jsonrpc: "2.0",
    id: "search-assets-example",
    method: "searchAssets",
    params,
  };
  const res = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    throw new Error(`${res.status} ${res.statusText}`);
  }
  const { result } = await res.json();
  return result;
}

// Example: fetch first 50 compressed NFTs in a wallet
searchAssets({
  ownerAddress: "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  tokenType: "compressedNft",
  limit: 50,
}).then(console.log);

Escolhendo um tokenType

tokenType é opcional e especifica que tipo de ativos aparecem na resposta. Quando omitido, searchAssets retorna apenas NFTs regulares e comprimidos — defina tokenType para incluir tokens fungíveis.

string

Valores aceitos: fungible, nonFungible, regularNft, compressedNft, all. O padrão é NFTs regulares e comprimidos quando omitido.

tokenType	O que você obtém	Uso típico
`fungible`	Somente tokens SPL e Token-2022	Saldos de carteiras, acesso por token
`nonFungible`	Todos os NFTs (comprimidos e regulares)	Visão geral do portfólio
`regularNft`	NFTs antigos e pNFTs (não comprimidos)	Listagens de marketplace
`compressedNft`	Somente cNFTs	Moedas em massa ultra-baratas
`all`	Tudo (tokens e NFTs)	Descoberta abrangente

Paginação e ordenação

Carteiras Solana podem possuir milhares de ativos, então a paginação eficiente é importante:

Page / limit — paginação clássica (page começa em 1). Bom para visualizações estáticas.
Cursor — passe valores before ou after da resposta anterior para uma rolagem infinita rápida.

sortBy

"sortBy": {
  "sortBy": "created",      // created | recent_action | updated | none
  "sortDirection": "desc"   // asc | desc
}

Para estratégias completas de página/limite e cursor, incluindo consultas paralelas por chave, veja o Guia de Paginação.

Opções de exibição

Essas flags adicionam metadados; elas nunca mudam quais ativos são retornados.

Flag	Efeito
`showNativeBalance`	Inclui o saldo SOL da carteira
`showCollectionMetadata`	Adiciona dados JSON no nível da coleção
`showGrandTotal`	Retorna a contagem total de correspondências (mais lento)

options

"options": {
  "showNativeBalance": true,
  "showCollectionMetadata": true,
  "showGrandTotal": true
}

Agentes MPL Core, signatários de ativos e grupos MIP-11

Ativos MPL Core podem expor identidade de agente e metadados de signatário de ativo, e ativos ou coleções podem incluir um plugin groups (MIP-11) descrevendo a associação de grupo. Os mesmos campos opcionais aparecem em todos os métodos de retorno de ativos do DAS (getAsset, getAssetBatch, getAssetsByOwner, getAssetsByGroup, getAssetsByCreator, getAssetsByAuthority, e cada item em searchAssets). Use searchAssets para filtrar por status de agente ou endereços:

Parâmetro	Tipo	Finalidade
`isAgent`	booleano	Somente ativos com Identidade de Agente
`agentToken`	string	Corresponder a mint do token de agente (base58)
`assetSigner`	string	Corresponder a PDA do signatário do ativo (base58)

Você também pode definir interface para MplCoreAsset, MplCoreCollection, ou MplCoreGroup para descoberta específica do MPL Core.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "searchAssets",
  "params": {
    "ownerAddress": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    "tokenType": "all",
    "isAgent": true,
    "page": 1,
    "limit": 10
  }
}

Os campos de resposta is_agent, agent_token, e asset_signer são omitidos quando não aplicáveis (por exemplo, is_agent é omitido quando falso). Veja a referência da API searchAssets para esquemas completos.

Exemplos

O primeiro exemplo mostra o wrapper completo fetch. Os exemplos restantes seguem o mesmo padrão e estão colapsados — expanda-os para o corpo da solicitação.

Buscar todos os tokens fungíveis em uma carteira

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

const searchAssets = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 'my-id',
      method: 'searchAssets',
      params: {
        ownerAddress: '86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY',
        tokenType: 'fungible',
      },
    }),
  });
  const { result } = await response.json();
  console.log("Search Assets: ", result);
};
searchAssets();

Buscar tokens fungíveis com saldo nativo e informações de token

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

const searchAssetsTokenInfo = async () => {
    const response = await fetch(url, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            jsonrpc: '2.0',
            id: 'my-id',
            method: 'searchAssets',
            params: {
                ownerAddress: '86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY',
                tokenType: 'fungible',
                options: {
                    showNativeBalance: true,
                },
            },
        }),
    });

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

    result.items.forEach(item => {
      console.log(item.token_info);
    });

    console.log("Native Balance: ", result.nativeBalance);
};

searchAssetsTokenInfo();

Buscar NFTs Drip possuídos por vibhu.sol

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

const searchAssetsDrip = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 'my-id',
      method: 'searchAssets',
      params: {
        ownerAddress: 'BAVjpySHMMGDpq3whU7qaqCCRE8ksCeGwxa53Qv2i8jS',
        grouping: ["collection", "DRiP2Pn2K6fuMLKQmt5rZWyHiUZ6WK3GChEySUpHSS4x"],
        page: 1,
        limit: 1000
      },
    }),
  });
  const { result } = await response.json();
  console.log("Drip Haus Assets: ", result);
};
searchAssetsDrip();

Buscar ativos comprimidos em uma carteira

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

const searchAssetsCompressed = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 'my-id',
      method: 'searchAssets',
      params: {
        ownerAddress: '2k5AXX4guW9XwRQ1AKCpAuUqgWDpQpwFfpVFh3hnm2Ha',
        compressed: true,
      },
    }),
  });
  const { result } = await response.json();
  console.log("Search Assets: ", result);
};
searchAssetsCompressed();

Próximos passos

Paginação

Paginação baseada em página e conjunto de chaves para grandes conjuntos de resultados.

Extensão de Token Fungível

Como o tokenType, saldos, e preços aparecem nos resultados.

referência searchAssets

Esquemas completos de solicitação e resposta.

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

Busca de Ativos Solana: Encontre NFTs, Tokens e Ativos Comprimidos

Visão Geral

Quando usar isso

Referência da API

Início Rápido

Escolhendo um tokenType

Paginação e ordenação

Opções de exibição

Agentes MPL Core, signatários de ativos e grupos MIP-11

Exemplos

Buscar todos os tokens fungíveis em uma carteira

Próximos passos

Paginação

Extensão de Token Fungível

referência searchAssets

​Visão Geral

​Quando usar isso

Referência da API

​Início Rápido

​Escolhendo um tokenType

​Paginação e ordenação

​Opções de exibição

​Agentes MPL Core, signatários de ativos e grupos MIP-11

​Exemplos

​Buscar todos os tokens fungíveis em uma carteira

​Próximos passos

Paginação

Extensão de Token Fungível

referência searchAssets

Visão Geral

Quando usar isso

Início Rápido

Escolhendo um tokenType

Paginação e ordenação

Opções de exibição

Agentes MPL Core, signatários de ativos e grupos MIP-11

Exemplos

Buscar todos os tokens fungíveis em uma carteira

Próximos passos