Collection Snapshot

Query all NFTs within a specific collection with advanced filtering capabilities.

Overview

The Collection Snapshot endpoint returns a paginated list of NFTs from a specific collection. It supports advanced field-based filtering, allowing you to query NFTs by attributes, traits, or any custom fields.

Perfect for:

• Building collection browsing interfaces
• Filtering NFTs by rarity or traits
• Analyzing collection composition
• Creating discovery tools

Endpoint

GET /nfts/collection/{type}

Base URL: https://api.surflux.dev

Parameters

Path Parameters

Parameter	Type	Required	Description
type	string	Yes	Full collection type path

Example: 0x41c06da395bc3f0ee621a66082f8f30f376da41a2db7bcce7c087444de200e41::panzerdog::Panzerdog

Query Parameters

Parameter	Type	Required	Default	Description
page	number	No	0	Page number for pagination (starts from 0)
perPage	number	No	10	Number of items per page (max 50)
fields	string	No	-	JSON filter for NFT fields (see below)
api-key	string	Yes	-	API key for authentication

Field Filtering

The fields parameter accepts a JSON string for advanced filtering. You can filter by:

• Simple key-value pairs — {"tag": "common"}
• Array values (OR logic) — {"attributes": ["basic", "common"]}
• Nested fields — {"attributes.contents.0.value": "Lumiray"}
• Multiple conditions (AND logic) — Combine multiple keys

Filter Examples

Filter by single field:

{"tag": "common"}

Filter by array (OR between values):

{"attributes": ["basic", "common"]}

Filter by nested field:

{"attributes.contents.0.value": "Lumiray"}

Combine multiple filters (AND logic):

{
  "tag": "common",
  "attributes": ["basic", "common"],
  "attributes.contents.0.value": "Lumiray"
}

Request Examples

Basic Request

curl "https://api.surflux.dev/nfts/collection/0x41c06da395bc3f0ee621a66082f8f30f376da41a2db7bcce7c087444de200e41::panzerdog::Panzerdog?page=0&perPage=20&api-key=your_api_key_here"

Filtered Request

curl -G "https://api.surflux.dev/nfts/collection/0x41c06da395bc3f0ee621a66082f8f30f376da41a2db7bcce7c087444de200e41::panzerdog::Panzerdog" \
  --data-urlencode 'fields={"tag": "common", "attributes": ["basic", "common"]}' \
  --data-urlencode 'api-key=your_api_key_here'

Response

Response Structure

{
  "items": [
    {
      "object_id": "0xff66767054fe1e7ce030d6a75b013ac1a335c42f9c919491d800756213be0765",
      "object_type": "0xb908f3c6fea6865d32e2048c520cdfe3b5c5bbcebb658117c41bad70f52b7ccc::popkins_nft::Popkins",
      "owner_dynamic_field_object_id": "0x86c2afc9256c25593b043e29602f169a6ee2cad7344a7b73a14d2a563606a748",
      "kiosk_object_id": "0x5fc2d2b2d1aa59b4bc32110f53184205828a961561a03f5ffcce68b642cdf318",
      "checkpoint_id": "198916311",
      "updated_at": "2025-10-09T15:45:40.589Z",
      "created_at": "2025-06-12T11:30:11.340Z",
      "decoded_fields": {
        "id": {
          "id": "0xff66767054fe1e7ce030d6a75b013ac1a335c42f9c919491d800756213be0765"
        },
        "name": "Popkins #21475",
        "creator": "Claynosaurz",
        "image_url": "https://walrus.tusky.io/yShZhFFYkqftacrieitLtmM8VS8dPjCV_3UKo_2emn4",
        "attributes": {
          "contents": [
            {
              "key": "Species",
              "value": "Lumiray"
            },
            {
              "key": "Mutation",
              "value": "Beta"
            }
          ]
        },
        "description": "Who knew so much chaos could come in such a small package?"
      },
      "decoded_display": {
        "name": "Popkins #21475",
        "creator": "Claynosaurz",
        "image_url": "https://walrus.tusky.io/yShZhFFYkqftacrieitLtmM8VS8dPjCV_3UKo_2emn4",
        "description": "Who knew so much chaos could come in such a small package?"
      },
      "owner": null,
      "kiosk": {
        "object_id": "0x5fc2d2b2d1aa59b4bc32110f53184205828a961561a03f5ffcce68b642cdf318",
        "owner_cap_object_id": "0x77f826a49a15720e24bcb8e299736dd1136c301ef56d2fe866337a67ae5b3407",
        "owner": "0xad974fac362dd860864b49bc64d69ca5538837784b0b1dd2a106ec943124ec33",
        "personal_cap_object_id": "0xf8dd662647c5e4396e85d16f95df43b72750b8f8d9e503dbe65a44eab21f8988",
        "checkpoint_id": "198916629",
        "updated_at": "2025-10-09T15:46:51.755Z",
        "created_at": "2025-07-21T04:48:06.863Z"
      }
    }
  ],
  "isLastPage": false,
  "currentPage": 0,
  "perPage": 2
}

Response Fields

Field	Type	Description
items	array	Array of NFT objects matching the filter
isLastPage	boolean	Whether this is the last page of results
currentPage	number	Current page number
perPage	number	Items per page

NFT Object Fields

The response structure is identical to Address NFTs. Each NFT object includes:

Field	Type	Description
object_id	string	Unique NFT object ID
object_type	string	Full type path of the NFT
owner_dynamic_field_object_id	string	Dynamic field object ID for Kiosk ownership
kiosk_object_id	string | null	Kiosk ID if NFT is stored in a Kiosk
owner	string | null	Owner wallet address (null if in Kiosk)
checkpoint_id	string	Checkpoint when NFT was last updated
decoded_fields	object	Decoded on-chain fields including name, description, image, attributes
decoded_display	object	Display metadata formatted for UI rendering
created_at	string	NFT creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)
kiosk	object | null	Kiosk details if NFT is stored in a Kiosk

Use Cases

• Collection Browsers — Build browsing interfaces with filtering by traits
• Rarity Tools — Filter NFTs by rarity attributes
• Marketplace Listings — Show available NFTs from a collection
• Analytics Dashboards — Analyze collection composition and distribution
• Discovery Tools — Help users find NFTs matching specific criteria

Code Examples

JavaScript / TypeScript

const collectionType = "0x41c06da395bc3f0ee621a66082f8f30f376da41a2db7bcce7c087444de200e41::panzerdog::Panzerdog";
const apiKey = "your_api_key_here";

// Filter by attributes
const filters = JSON.stringify({
  tag: "common",
  attributes: ["basic", "common"]
});

const url = new URL(`https://api.surflux.dev/nfts/collection/${collectionType}`);
url.searchParams.set("page", "0");
url.searchParams.set("perPage", "20");
url.searchParams.set("fields", filters);
url.searchParams.set("api-key", apiKey);

const response = await fetch(url.toString());

const data = await response.json();
console.log(`Found ${data.items.length} matching NFTs`);

Related Endpoints

• Address NFTs — Get NFTs owned by a specific address
• Collection Holders — Get holder distribution for a collection