fungible_assets

Coming soon: Need support for this? Email support@dwellir.com and we will enable it for you.

Fungible Assets (FA) represent the next generation token standard on Aptos, providing enhanced functionality compared to the legacy Coin standard. The GraphQL API enables comprehensive querying of FA balances, metadata, transfer histories, and analytics, essential for wallets, DEXes, portfolio trackers, and any application working with tokens.

Overview

The Fungible Asset standard improves upon Coins by supporting programmable behaviors, better metadata management, and composability with the Object model. GraphQL queries provide indexed access to all FA data including current balances, historical activities, supply metrics, and token metadata across all fungible assets on Aptos.

Core Queries

Account Balances

graphql

query FaBalances($owner: String!) {
  current_fungible_asset_balances(
    where: { owner_address: { _eq: $owner } }
  ) {
    owner_address
    asset_type
    amount
    last_transaction_version
    metadata {
      name
      symbol
      decimals
      icon_uri
      project_uri
    }
  }
}

Token Metadata

graphql

query TokenInfo($asset_type: String!) {
  fungible_asset_metadata(
    where: { asset_type: { _eq: $asset_type } }
  ) {
    asset_type
    creator_address
    name
    symbol
    decimals
    icon_uri
    project_uri
    supply_aggregator_table_handle
    supply_aggregator_table_key
  }
}

Transfer History

graphql

query TransferHistory($owner: String!, $limit: Int!) {
  fungible_asset_activities(
    where: {
      _or: [
        { owner_address: { _eq: $owner } },
        { to_address: { _eq: $owner } }
      ]
    },
    order_by: { transaction_version: desc },
    limit: $limit
  ) {
    transaction_version
    owner_address
    to_address
    amount
    type
    asset_type
    transaction_timestamp
  }
}

Supply Metrics

graphql

query SupplyMetrics($asset_type: String!) {
  fungible_asset_supply(
    where: { asset_type: { _eq: $asset_type } }
  ) {
    asset_type
    current_supply
    max_supply
    total_minted
    total_burned
  }
}

Top Holders

graphql

query TopHolders($asset_type: String!, $limit: Int!) {
  current_fungible_asset_balances(
    where: {
      asset_type: { _eq: $asset_type },
      amount: { _gt: "0" }
    },
    order_by: { amount: desc },
    limit: $limit
  ) {
    owner_address
    amount
    last_transaction_version
  }
}

Real-World Use Cases

Wallet Applications: Display comprehensive token portfolios with balances, prices, and metadata for all FAs held by users across the Aptos ecosystem.
DEX Interfaces: Query token metadata, verify decimals, fetch logos, and track liquidity for trading pairs on decentralized exchanges.
Portfolio Trackers: Aggregate holdings across multiple wallets, calculate total values, and track historical balance changes over time.
Token Analytics: Analyze holder distribution, supply metrics, transfer volumes, and other statistics for tokens and liquidity pools.
Payment Systems: Verify balances before transactions, fetch current exchange rates, and track payment histories for accounting purposes.
DeFi Dashboards: Monitor staking positions, lending collateral, farming rewards, and other DeFi activities involving fungible assets.

Best Practices

Cache Metadata: Token metadata (name, symbol, decimals, logo) changes rarely - cache it with long TTLs to reduce API calls.

Handle Decimals: Always account for token decimals when displaying amounts - a balance of 1000000 with 6 decimals is actually 1.0 tokens.

Batch Balance Queries: Fetch all balances for an address in a single query rather than separate requests per token.

Track Versions: Use transaction_version to detect balance changes and avoid displaying stale data.

Filter Zero Balances: Exclude zero-balance entries to avoid cluttering portfolio displays with tokens users no longer hold.

Use Aggregations: For analytics, use aggregate queries to compute statistics efficiently rather than fetching all records.

Pagination: Implement proper pagination for transfer histories and holder lists to handle large datasets.

TypeScript Integration

TypeScript

import { ApolloClient, gql } from "@apollo/client";

const client = new ApolloClient({
  uri: "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/graphql"
});

interface TokenBalance {
  asset_type: string;
  amount: string;
  decimals: number;
  symbol: string;
  name: string;
}

async function getPortfolio(address: string): Promise<TokenBalance[]> {
  const { data } = await client.query({
    query: gql`
      query Portfolio($address: String!) {
        current_fungible_asset_balances(
          where: {
            owner_address: { _eq: $address },
            amount: { _gt: "0" }
          }
        ) {
          asset_type
          amount
          metadata {
            name
            symbol
            decimals
          }
        }
      }
    `,
    variables: { address }
  });

  return data.current_fungible_asset_balances.map((balance: any) => ({
    asset_type: balance.asset_type,
    amount: balance.amount,
    decimals: balance.metadata.decimals,
    symbol: balance.metadata.symbol,
    name: balance.metadata.name
  }));
}

function formatTokenAmount(amount: string, decimals: number): string {
  const value = parseInt(amount) / Math.pow(10, decimals);
  return value.toLocaleString(undefined, {
    minimumFractionDigits: 2,
    maximumFractionDigits: decimals
  });
}

Advanced Queries

Portfolio Value Tracking

graphql

query PortfolioWithPrices($owner: String!) {
  balances: current_fungible_asset_balances(
    where: {
      owner_address: { _eq: $owner },
      amount: { _gt: "0" }
    }
  ) {
    asset_type
    amount
    metadata {
      name
      symbol
      decimals
      icon_uri
    }
  }
}

Token Distribution Analysis

graphql

query HolderDistribution($asset_type: String!) {
  total_holders: current_fungible_asset_balances_aggregate(
    where: {
      asset_type: { _eq: $asset_type },
      amount: { _gt: "0" }
    }
  ) {
    aggregate { count }
  }

  large_holders: current_fungible_asset_balances_aggregate(
    where: {
      asset_type: { _eq: $asset_type },
      amount: { _gt: "1000000000" }
    }
  ) {
    aggregate { count }
  }

  total_supply: fungible_asset_supply(
    where: { asset_type: { _eq: $asset_type } }
  ) {
    current_supply
  }
}

Activity Feed

graphql

query RecentActivities($owner: String!, $limit: Int!) {
  fungible_asset_activities(
    where: {
      _or: [
        { owner_address: { _eq: $owner } },
        { to_address: { _eq: $owner } }
      ]
    },
    order_by: { transaction_version: desc },
    limit: $limit
  ) {
    transaction_version
    owner_address
    to_address
    amount
    type
    asset_type
    transaction_timestamp
    metadata {
      symbol
      decimals
    }
  }
}

Fungible Assets vs Coins

The Fungible Asset standard offers several improvements over the legacy Coin standard:

Object Integration: FAs integrate with the Object model for better composability
Metadata Standards: Built-in metadata support with URLs for icons and project info
Programmable Transfers: Support for custom transfer logic and restrictions
Better Events: More comprehensive event emissions for indexing
Future-Proof: Designed for long-term extensibility

GraphQL Overview - GraphQL indexer introduction
Token Activities - NFT and token transfers
Aggregations - Statistical queries
Object Model - Object-based asset design

On this page