Address NFTs

Get all NFTs owned by a specific wallet address with complete metadata, display properties, and Kiosk information.

Overview

The Address NFTs endpoint returns a paginated list of all NFTs owned by a wallet address, including:

• NFTs held directly in the wallet
• NFTs stored in Kiosks owned by the address
• Decoded metadata and display properties
• Listing information for NFTs in Kiosks

Endpoint

GET /nfts/address/{address}

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

Parameters

Path Parameters

Parameter	Type	Required	Description
address	string	Yes	Owner wallet address

Example: 0xf9c18a383d4f5c293bef82e4daf1ce82306b7b561cbef50d5c456a90d8547a5d

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)
collections	string[]	No	[]	Filter by collection types
api-key	string	Yes	-	API key for authentication

Request Example

curl "https://api.surflux.dev/nfts/address/0xf9c18a383d4f5c293bef82e4daf1ce82306b7b561cbef50d5c456a90d8547a5d?page=0&perPage=10&api-key=your_api_key_here"

Filtering by Collection

curl "https://api.surflux.dev/nfts/address/0xf9c18a383d4f5c293bef82e4daf1ce82306b7b561cbef50d5c456a90d8547a5d?collections=0x41c06da395bc3f0ee621a66082f8f30f376da41a2db7bcce7c087444de200e41::panzerdog::Panzerdog&api-key=your_api_key_here"

Response

Response Structure

{
  "items": [
    {
      "object_id": "0xa534b9c5a824c31c9c4d143580f7ccb3f3a6e544e1afc30ac235c7277d73b7fe",
      "object_type": "0xb908f3c6fea6865d32e2048c520cdfe3b5c5bbcebb658117c41bad70f52b7ccc::popkins_nft::Popkins",
      "owner_dynamic_field_object_id": "0xca96b6c9e52fa706604e2580c9a0cb1fe46e3cb9cdd58616e32f3030459478d4",
      "kiosk_object_id": "0x1d46393125831bdf06b069e9ecbca4a5f7987ee63e45382cc0b0aaf034433e4e",
      "owner": null,
      "checkpoint_id": "187489349",
      "decoded_fields": {
        "id": {
          "id": "0xa534b9c5a824c31c9c4d143580f7ccb3f3a6e544e1afc30ac235c7277d73b7fe"
        },
        "name": "Popkins #11271",
        "image_url": "https://walrus.tusky.io/jbpsuBO5Ug6XMvP4CYhP2PWjwDKxFFI-KHRt0UXCjPE",
        "description": "Who knew so much chaos could come in such a small package?",
        "attributes": {
          "contents": [
            {
              "key": "Species",
              "value": "Cat Slug"
            }
          ]
        }
      },
      "decoded_display": {
        "name": "Popkins #11271",
        "image_url": "https://walrus.tusky.io/jbpsuBO5Ug6XMvP4CYhP2PWjwDKxFFI-KHRt0UXCjPE",
        "description": "Who knew so much chaos could come in such a small package?"
      },
      "updated_at": "2025-09-07T21:03:01.585Z",
      "created_at": "2025-06-05T19:57:09.698Z",
      "kiosk": {
        "object_id": "0x1d46393125831bdf06b069e9ecbca4a5f7987ee63e45382cc0b0aaf034433e4e",
        "owner_cap_object_id": "0x5932f535f36009c9c04de9a68904c259cfe708e3cfa607c274a86d9ddf33019b",
        "owner": "0xa0490f6fe09183700e2af6484b7fb2a09a12f0f691f5b8e5582c4782d6de887e",
        "personal_cap_object_id": null,
        "checkpoint_id": "187489349",
        "updated_at": "2025-09-07T21:03:01.585Z",
        "created_at": "2025-09-07T21:03:01.585Z"
      }
    }
  ],
  "isLastPage": false,
  "currentPage": 0,
  "perPage": 10
}

Response Fields

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

NFT Object Fields

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

Kiosk Object Fields

Field	Type	Description
object_id	string	Kiosk object ID
owner_cap_object_id	string	Owner capability object ID
owner	string	Kiosk owner address
personal_cap_object_id	string | null	Personal capability object ID
checkpoint_id	string	Checkpoint when Kiosk was last updated
created_at	string	Kiosk creation timestamp
updated_at	string	Last update timestamp

Use Cases

• Portfolio Display — Show all NFTs owned by a user in a wallet interface
• Collection Filtering — Display only specific collections from a user's portfolio
• Marketplace Integration — Check NFT ownership before allowing sales
• Analytics — Track NFT holdings across addresses
• Kiosk Detection — Identify which NFTs are stored in Kiosks vs. direct ownership

Code Examples

JavaScript / TypeScript

const address = "0xf9c18a383d4f5c293bef82e4daf1ce82306b7b561cbef50d5c456a90d8547a5d";
const apiKey = "your_api_key_here";

const response = await fetch(
  `https://api.surflux.dev/nfts/address/${address}?page=0&perPage=20&api-key=${apiKey}`
);

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

Related Endpoints

• Collection Snapshot — Get all NFTs in a specific collection
• Kiosks NFTs — Query NFTs in a specific Kiosk