⚠️Blast API (blastapi.io) ends Oct 31. Migrate to Dwellir and skip Alchemy's expensive compute units.
Switch Today →
Skip to main content

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

Fungible Assets

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#

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#

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#

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#

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#

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#

  1. Wallet Applications: Display comprehensive token portfolios with balances, prices, and metadata for all FAs held by users across the Aptos ecosystem.

  2. DEX Interfaces: Query token metadata, verify decimals, fetch logos, and track liquidity for trading pairs on decentralized exchanges.

  3. Portfolio Trackers: Aggregate holdings across multiple wallets, calculate total values, and track historical balance changes over time.

  4. Token Analytics: Analyze holder distribution, supply metrics, transfer volumes, and other statistics for tokens and liquidity pools.

  5. Payment Systems: Verify balances before transactions, fetch current exchange rates, and track payment histories for accounting purposes.

  6. 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#

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#

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#

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#

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