Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.handcash.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Suggested Prerequisites

  • User authentication completed
  • Items permissions granted
  • Item management system
  • Database for inventory tracking

​
Suggested Prompt

Read this documentation then integrate item inventory from the v3 SDK: https://docs.handcash.io/v3/items/inventory

​
Get Items Inventory

​
Basic Inventory

import { getInstance, Connect } from '@handcash/sdk';

const sdk = getInstance({ appId, appSecret });
const client = sdk.getAccountClient(authToken);

const { data: items } = await Connect.getItemsInventory({
  client,
  body: {}
});

console.log(`User has ${items.length} items`);

​
Search Items

const { data: items } = await Connect.getItemsInventory({
  client,
  body: {
    searchString: 'dragon',
    limit: 20
  }
});

console.log(`Found ${items.length} items matching "dragon"`);

​
Filter by Collection

const { data: items } = await Connect.getItemsInventory({
  client,
  body: {
    collectionId: 'collection-id-here',
    limit: 50
  }
});

console.log(`Found ${items.length} items in collection`);

​
Get All Items Ungrouped

By default, the inventory API groups identical items together. To get all individual items ungrouped (useful for displaying each item instance separately), set group: false: 
const { data: items } = await Connect.getItemsInventory({
  client,
  body: {
    group: false,
    limit: 100
  }
});

console.log(`Found ${items.length} individual items (ungrouped)`);
This is particularly useful when you need to:
  • Display each item instance separately in your UI
  • Track individual item origins or IDs
  • Show the exact count of item instances rather than grouped quantities

​
Advanced Filtering

const { data: items } = await Connect.getItemsInventory({
  client,
  body: {
    searchString: 'legendary',
    collectionId: 'collection-id',
    groupingValue: 'group-id',
    from: 0,
    to: 20,
    sort: 'name',
    order: 'asc'
  }
});

​
Item Data Structure

interface Item {
  id: string;
  origin: string;
  name: string;
  description: string;
  imageUrl: string;
  multimediaUrl?: string;
  rarity: string;
  color: string;
  attributes: ItemAttribute[];
  collection: {
    id: string;
    name: string;
    description: string;
  };
  user: {
    alias: string;
    displayName: string;
    profilePictureUrl: string;
  };
  app: {
    id: string;
    name: string;
    iconUrl: string;
  };
}

interface ItemAttribute {
  name: string;
  value: string | number;
  displayType: 'string' | 'number' | 'date';
}

​
Common Use Cases

​
User’s Item Collection

async function getUserCollection(authToken: string) {
  const client = sdk.getAccountClient(authToken);
  
  const { data: items } = await Connect.getItemsInventory({
    client,
    body: { limit: 100 }
  });
  
  // Group by collection
  const grouped = items.reduce((acc, item) => {
    const collectionName = item.collection.name;
    if (!acc[collectionName]) {
      acc[collectionName] = [];
    }
    acc[collectionName].push(item);
    return acc;
  }, {});
  
  return grouped;
}

​
Search by Rarity

async function getRareItems(authToken: string, rarity: string) {
  const client = sdk.getAccountClient(authToken);
  
  const { data: items } = await Connect.getItemsInventory({
    client,
    body: {
      searchString: rarity,
      limit: 50
    }
  });
  
  return items.filter(item => 
    item.rarity.toLowerCase() === rarity.toLowerCase()
  );
}

​
Item Statistics

async function getItemStats(authToken: string) {
  const client = sdk.getAccountClient(authToken);
  
  const { data: items } = await Connect.getItemsInventory({
    client,
    body: { limit: 1000 }
  });
  
  const stats = {
    total: items.length,
    byRarity: {},
    byCollection: {},
    byApp: {}
  };
  
  items.forEach(item => {
    // Count by rarity
    stats.byRarity[item.rarity] = (stats.byRarity[item.rarity] || 0) + 1;
    
    // Count by collection
    const collectionName = item.collection.name;
    stats.byCollection[collectionName] = (stats.byCollection[collectionName] || 0) + 1;
    
    // Count by app
    const appName = item.app.name;
    stats.byApp[appName] = (stats.byApp[appName] || 0) + 1;
  });
  
  return stats;
}

​
Error Handling

try {
  const { data: items } = await Connect.getItemsInventory({
    client,
    body: { searchString: 'dragon' }
  });
} catch (error) {
  if (error.message.includes('Invalid token')) {
    // Redirect to re-authenticate
    res.redirect(sdk.getRedirectionUrl());
  } else if (error.message.includes('Permission denied')) {
    // Handle insufficient permissions
    console.log('User needs to grant items permission');
  }
}

​
Display Examples

​
Item Card Component

function ItemCard({ item }: { item: Item }) {
  return {
    name: item.name,
    rarity: item.rarity,
    image: item.imageUrl,
    collection: item.collection.name,
    attributes: item.attributes.map(attr => ({
      name: attr.name,
      value: attr.value,
      type: attr.displayType
    }))
  };
}

​
Inventory Grid

function InventoryGrid({ items }: { items: Item[] }) {
  return items.map(item => ({
    id: item.id,
    name: item.name,
    image: item.imageUrl,
    rarity: item.rarity,
    color: item.color
  }));
}