User inventory

📘
Permissions Required
This feature requires the ITEMS_READ permission.

List user items

The code below shows how to get the ordinals from the connected HandCash wallet inventory:

const { HandCashConnect } = require('@handcash/handcash-connect');
const handCashConnect = new HandCashConnect({ 
   appId: '<app-id>', 
   appSecret: '<secret>',
}); 

const account = handCashConnect.getAccountFromAuthToken(token);
const items = await account.items.getItemsInventory({ from: 0, to: 50 });

console.log(items);

{
    "items": [
        {
            "description": "",
            "collection": {
                "id": "6490ea8acf3da0ed972764c3",
                "description": "",
                "app": {
                    "id": "647a2e8e84940994f6aeb634",
                    "name": "CoOM Battles",
                    "iconUrl": "https://res.cloudinary.com/hn8pdtayf/image/upload/v1686328051/dashboard/fc64p4sintlyvlnrldvx.jpg"
                },
                "origin": "efce1385fde989252e931996f01811cf7ac52ab367f46b5e28c039ad7f5fa9fb_0",
                "name": "CoOM Battles · First Edition",
                "imageUrl": "https://res.cloudinary.com/handcash-iae/image/upload/w_600/v1687638164/nt7cc1gs6nhgmwoyhksi.png",
                "totalQuantity": 0,
                "isFeatured": true,
                "isHandcashCreated": true,
                "isVerified": true
            },
            "user": {
                "alias": "rjseibane",
                "displayName": "Rafa JS",
                "profilePictureUrl": "https://res.cloudinary.com/hn8pdtayf/image/upload/v1660031989/f6ym3hmv38pj1lgs4uyj.png"
            },
            "app": {
                "id": "647a2e8e84940994f6aeb634",
                "name": "CoOM Battles",
                "iconUrl": "https://res.cloudinary.com/hn8pdtayf/image/upload/v1686328051/dashboard/fc64p4sintlyvlnrldvx.jpg"
            },
            "origin": "5e4ea86a2116906941634733cedcab05ac33aeffa7dd8d63df415ec57663ac8d_1",
            "name": "Booboo",
            "imageUrl": "https://res.cloudinary.com/hn8pdtayf/image/upload/v1687218877/items/gsollqebtvv4zwwbwd5s.png",
            "multimediaUrl": "",
            "multimediaType": "",
            "rarity": "Common",
            "color": "#a032ab",
            "attributes": [
                {
                    "name": "Edition",
                    "value": "First",
                    "displayType": "string"
                },
                {
                    "name": "Generation",
                    "value": 1,
                    "displayType": "number"
                },
                {
                    "name": "Champion Number",
                    "value": 12,
                    "displayType": "number"
                },
                {
                    "name": "Evolutions",
                    "value": "Booboo, Phanboo, Phantomb",
                    "displayType": "string"
                },
                {
                    "name": "Skin",
                    "value": "Classic",
                    "displayType": "string"
                },
                {
                    "name": "Element",
                    "value": "Dark",
                    "displayType": "string"
                },
                {
                    "name": "ManaCost",
                    "value": 1,
                    "displayType": "number"
                },
                {
                    "name": "Health",
                    "value": 2,
                    "displayType": "number"
                },
                {
                    "name": "Attack",
                    "value": 1,
                    "displayType": "number"
                }
            ],
            "count": 1,
            "isHandcashCreated": true,
            "isVerified": true,
            "isListing": false,
            "itemListing": {}
        }
    ]
}

Filtering user inventory

You can use the following parameters to filter items:

export type AttributeFilter = {
	name: string;
	displayType: 'string' | 'number';
	operation: 'equal' | 'matches' | 'includes' | 'greater' | 'lower' | 'greaterOrEqual' | 'lowerOrEqual' ;
	value: string | number;
  values: (string | number)[];
};

export const sortableFields = {
	name: 'name',
};

export type GetItemsFilter = {
	from?: number;
	to?: number;
	collectionId?: string;
	searchString?: string;
	groupingValue?: string;
	fetchAttributes?: boolean;
	sort?: keyof typeof sortableFields;
	order?: 'asc' | 'desc';
	attributes?: AttributeFilter[];
	isHandcashCreated?: boolean;
	isVerified?: boolean;
	appId?: string;
	group?: boolean;
	externalId?: string;
};

A few notes

matches operation Used to search by wildcard for example: Fi*
includes operation: This operation is used to filter items that match at least one value from a specified array. When using this operation, you must provide a values array in the attribute filter.
externalId : This field can be assigned to an item upon creation, serving as a mapping between your application's reference and the item in HandCash. It is useful for assigning a unique ID before minting the item, making it easier to locate and manage later, especially since the origin of an item is not known until it is created.
groupingValue : A unique identifier to distinguish items with the same name but different characteristics. For example, a Pokémon card named Charizard could belong to different editions or have a holographic version. This field helps to differentiate between such variations.
group : This field allows returns items grouped by groupingValue. You will be returned each unique item with the count only once. This is useful when it comes to fetching large inventories with many items, fetching inventory with this value true will reduce bandwidth needs and speeds up the process.

Filter items from a given collection and trait value

const params: GetItemsParameters = {
  from: 0,
  to: 20,
  collectionId: '64b93458b3a3a4daa4404455',
  attributes: [
    {
      name: 'element',
      displayType: 'string',
      operation: 'equal',
      value: 'Wind',
    },
    {
      name: 'edition',
      displayType: 'string',
      operation: 'matches',
      value: 'Fi*',
    },
    {
      name: 'color',
      displayType: 'string',
      operation: 'includes',
      values: ['Blue', 'Red'],
    },
    {
      name: 'totalQuantity',
      displayType: 'number',
      operation: 'equal',
      value: 33,
    },
  ],
};

const inventory = await cloudAccount.items.getItemsInventory(params);

Filter items with the searchString "dragon" sorted by name (ascending)

const params: GetItemsParameters = {
  from: 0,
  to: 50,
  searchString: 'dragon',
  order: 'name',
  sort: 'asc',
};
const inventory = await cloudAccount.items.getItemsInventory(params);

📘Permissions Required

List user items

Filtering user inventory

Filter items from a given collection and trait value

Filter items with the searchString "dragon" sorted by name (ascending)

📘
Permissions Required