Skip to content
DocumentationNFT APIsNFT Aggregator API

NFT Aggregator API

The NFT Aggregator API provides a unified GraphQL interface to access normalized NFT marketplace data across the Aptos ecosystem by capturing real-time marketplace events (listings, token offers, and collection-wide offers) from major marketplaces. This enables developers to build NFT marketplaces, portfolio trackers, and analytics applications without handling different data formats manually.

What You Can Build

  • NFT Marketplaces: Display active listings from multiple marketplaces including your own marketplace
  • Portfolio Trackers: Monitor NFT holdings and values
  • Analytics Dashboards: Track marketplace activity and trends
  • Price Discovery Tools: Compare prices across marketplaces

Getting Started

The NFT Aggregator API is currently available on Mainnet only.

Prerequisites

  • Create an Geomi API key.

Authentication

All NFT Aggregator API requests require Geomi API key.

curl "https://api.mainnet.aptoslabs.com/nft-aggregator/v1/graphql" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

API Overview

Base URL

Mainnet: https://api.mainnet.aptoslabs.com/nft-aggregator/v1/graphql

Core Features

  • Real-time marketplace data - Get current active listings
  • Cross-marketplace aggregation - Data from multiple NFT marketplaces
  • Rich metadata - NFT details, collection information, and asset URIs
  • Flexible querying - GraphQL allows precise data fetching

Example Query: Active Marketplace Listings

query GetMarketplaceListings {
  current_nft_marketplace_listings(
    limit: 10
    where: {is_deleted: {_eq: false}}
    order_by: {last_transaction_timestamp: desc}
  ) {
    token_name
    token_data_id
    seller
    price
    marketplace
    listing_id
    last_transaction_timestamp
    collection_id
    collection_data {
      collection_name
      uri
      creator_address
    }
    current_token_data {
      token_uri
      token_name
      description
      cdn_asset_uris {
        cdn_image_uri
        asset_uri
      }
    }
  }
}

TypeScript Integration Example

interface Args {
  nftAggregatorApiUrl: string;
  apiKey: string;
}
 
const main = async ({ nftAggregatorApiUrl, apiKey }: Args) => {
  const query = `
    query GetMarketplaceListings {
      current_nft_marketplace_listings(
        limit: 10
        where: {is_deleted: {_eq: false}}
        order_by: {last_transaction_timestamp: desc}
      ) {
        token_name
        token_data_id
        seller
        price
        marketplace
        listing_id
        collection_data {
          collection_name
        }
      }
    }
  `;
 
  const response = await fetch(nftAggregatorApiUrl, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query })
  });
 
  const result = await response.json();
  console.log("Total listings found:", result.data.current_nft_marketplace_listings.length);
  console.log("First listing token name:", result.data.current_nft_marketplace_listings[0]?.token_name);
}

Filtering and Sorting

Common Filters

where: {
  is_deleted: {_eq: false}                    # Active listings only
  marketplace: {_eq: "wapal"}                 # Specific marketplace
  collection_id: {_eq: "0x123..."}           # Specific collection
  price: {_gte: "100000000"}                  # Minimum price (1 APT)
}

Sorting Options

order_by: {
  last_transaction_timestamp: desc           # Most recent first
  price: asc                                  # Lowest price first
  token_name: asc                            # Alphabetical
}

Rate Limits and Best Practices

⚠️

The NFT Aggregator API has rate limits to ensure fair usage + timeouts. Monitor your usage through the dashboard and implement appropriate caching strategies.

Best Practices

  1. Use specific queries - Only request fields you need
  2. Implement pagination - Use limit and offset for large datasets
  3. Cache responses - Store frequently accessed data locally
  4. Handle errors gracefully - Implement retry logic with exponential backoff
  5. Filter efficiently - Use where clauses to reduce data transfer

Troubleshooting

Common Issues

403 Unauthorized: Check that your API key is correct

GraphQL Errors: Validate your query syntax and field names

Empty Results: Verify your where filters and ensure data exists

Rate Limiting: Implement exponential backoff and respect rate limits

Learn more about API keys and authentication here.

Support

For additional support with the NFT Aggregator API:

  • Review the interactive sample code in your dashboard
  • Test queries with GraphQL tools
  • Contact support for specific integration questions
NFT APIsNFT Analytics API