Profile Listings

How to retrieve a user's NFT listings from the Wayup Marketplace

Introduction

This guide demonstrates how to retrieve all active listings for a specific wallet address on the Wayup Marketplace. This endpoint is useful for building user profiles, dashboards, or portfolio trackers that show what NFTs a user currently has listed for sale.

Requirements

• A valid Cardano wallet address

API Request Structure

Configuration

// API endpoint for Wayup Marketplace
const BASE_URL = "https://prod.api.ada-anvil.app/marketplace/api";

// Wallet address to query listings for
const WALLET_ADDRESS = "addr1qx33ycd2ymg02dxh6vnnf8dsk54l8ranr9cfjk9qrlj3309c69jc4n8h3uvnczncaqu2sm03pl99h99n75uvtl3mhv0q3z8s8m";

Type Definitions

interface ProfileListingsRequest {
  address: string;
  limit?: number;
  cursor?: string;
  policyId?: string;
  term?: string;
}

interface AssetResult {
  name: string;
  policyId: string;
  assetName: string;
  media: string;
  listing: {
    txHashIndex: string;
    price: string;
    priceCurrency: string;
    scriptHash: string;
    bundleSize?: number;
    isProcessing: boolean;
    type: string;
    version: string;
    fees: {
      service: {
        pct: number;
      };
      royalty: {
        minLovelace: number;
        pct: number;
        addr: string;
      } | null;
    };
  };
  collection?: {
    policyId: string;
    name: string;
    image?: string;
    royaltyPct?: number;
    royaltyAddress?: string;
  };
  // Additional fields omitted for brevity
}

interface ProfileListingsResponse {
  results: AssetResult[];
  pageState: string | null;
}

Implementation

Step 1: Build the Request URL

Build the URL with the required parameters:

// Step 1: Build the request URL

//Optional parameters
const PAGE_LIMIT = 20; // Number of results to return
const PAGE_CURSOR = null; // Pagination cursor (leave as null for first page)
const POLICY_ID = null; // Optional: filter by policy ID
const SEARCH_TERM = null; // Optional: search term for filtering by name

const requestUrl = `${BASE_URL}/get-profile-listings?address=${WALLET_ADDRESS}`;

// If you want to include additional parameters:
// const requestUrl = `${BASE_URL}/get-profile-listings?address=${WALLET_ADDRESS}&limit=${PAGE_LIMIT}${PAGE_CURSOR ? `&cursor=${PAGE_CURSOR}` : ''}${POLICY_ID ? `&policyId=${POLICY_ID}` : ''}${SEARCH_TERM ? `&term=${encodeURIComponent(SEARCH_TERM)}` : ''}`;

Step 2: Execute the Request

Send the request to the API:

// Step 2: Execute the request
console.log("Fetching user's NFT listings...");
const response = await fetch(requestUrl);

Step 3: Process the Response

Parse the API response:

// Step 3: Process the response
const result = await response.json();
const { results, pageState } = result;

Step 4: Display the Results

Process and display the listings data:

// Step 4: Display the results
console.log(`Found ${results.length} listings for address ${WALLET_ADDRESS}`);
console.log("Listings:");
results.forEach((item, index) => {
  console.log(`\n--- Listing ${index + 1} ---`);
  console.log(`Name: ${item.name}`);
  console.log(`Policy ID: ${item.policyId}`);
  console.log(`Asset Name: ${item.assetName}`);
  console.log(`Price: ${Number(item.listing.price) / 1000000} ADA`);
  console.log(`Tx Hash Index: ${item.listing.txHashIndex}`);
  console.log("\nListing Marketplace: " + item.listing.type);
});

Step 5: Handle Pagination

Handle pagination for large result sets:

// Step 5: Handle pagination
if (pageState) {
  console.log(`\nMore results available. Use this cursor for the next page: ${pageState}`);
}

Running the Example

deno run --allow-net get-profile-listings.ts

Example Output

Fetching user's NFT listings...
Found 2 listings for address addr1qx33ycd2ymg02dxh6vnnf8dsk54l8ranr9cfjk9qrlj3309c69jc4n8h3uvnczncaqu2sm03pl99h99n75uvtl3mhv0q3z8s8m
Listings:

--- Listing 1 ---
Name: Serene Power Core
Policy ID: 6fb0ce0d80bce539333b0b16f4a29a0d40c786249f86850d3a36fa01
Asset Name: 4646506f776572436f72657331363630
Price: 25 ADA
Tx Hash Index: daac1d3b80dcab8817c2f02f2d43ab2b33a4e74419679939eb8aa5f70b03f35c#0

Listing Marketplace: wayup

--- Listing 2 ---
Name: Shimmering Power Core
Policy ID: 6fb0ce0d80bce539333b0b16f4a29a0d40c786249f86850d3a36fa01
Asset Name: 4646506f776572436f7265733437
Price: 5 ADA
Tx Hash Index: 4baa167631a62343cc4f37f9313ee05d6149b1fda39fd563e12832c8dd49fac9#0

Listing Marketplace: jpgstore

The Complete File

get-profile-listings.ts

// API endpoint for Wayup Marketplace
const BASE_URL = "https://prod.api.ada-anvil.app/marketplace/api";

// Wallet address to query listings for
const WALLET_ADDRESS = "addr1qx33ycd2ymg02dxh6vnnf8dsk54l8ranr9cfjk9qrlj3309c69jc4n8h3uvnczncaqu2sm03pl99h99n75uvtl3mhv0q3z8s8m";

// Optional parameters
const PAGE_LIMIT = 20; // Number of results to return
const PAGE_CURSOR = null; // Pagination cursor (leave as null for first page)
const POLICY_ID = null; // Optional: filter by policy ID
const SEARCH_TERM = null; // Optional: search term for filtering by name

// Step 1: Build the request URL
const requestUrl = `${BASE_URL}/get-profile-listings?address=${WALLET_ADDRESS}`;

// If you want to include additional parameters:
// const requestUrl = `${BASE_URL}/get-profile-listings?address=${WALLET_ADDRESS}&limit=${PAGE_LIMIT}${PAGE_CURSOR ? `&cursor=${PAGE_CURSOR}` : ''}${POLICY_ID ? `&policyId=${POLICY_ID}` : ''}${SEARCH_TERM ? `&term=${encodeURIComponent(SEARCH_TERM)}` : ''}`;

// Step 2: Execute the request
console.log("Fetching user's NFT listings...");
const response = await fetch(requestUrl);

// Step 3: Process the response
const result = await response.json();
const { results, pageState } = result;

// Step 5: Display the results
console.log(`Found ${results.length} listings for address ${WALLET_ADDRESS}`);
console.log("Listings:");
results.forEach((item, index) => {
  console.log(`\n--- Listing ${index + 1} ---`);
  console.log(`Name: ${item.name}`);
  console.log(`Policy ID: ${item.policyId}`);
  console.log(`Asset Name: ${item.assetName}`);
  console.log(`Price: ${Number(item.listing.price) / 1000000} ADA`);
  console.log(`Tx Hash Index: ${item.listing.txHashIndex}`);
  console.log("\nListing Marketplace: " + item.listing.type);
});

// Step 6: Handle pagination
if (pageState) {
  console.log(`\nMore results available. Use this cursor for the next page: ${pageState}`);
}

// Run this with: deno run --allow-net get-profile-listings.ts

Best Practices

1. Input Validation: Always validate the wallet address before making the API call.

2. Error Handling: Implement proper error handling for network issues or invalid responses.

3. Pagination: Always handle pagination for users with many listings.

4. Filtering: Use the policyId parameter when you want to focus on a specific collection.

5. Search: The term parameter is useful for searching NFTs by name.

End-to-End Flow

1. Obtain a wallet address from your user

2. Query the /get-profile-listings endpoint with the wallet address

3. Display the listing results (name, image, price, etc.)

4. Implement pagination using the returned pageState if there are more results

5. Allow filtering by collection using the policyId parameter

6. Enable searching by name using the term parameter