This guide demonstrates how to manage a user’s digital items inventory using the HandCash SDK. It covers looking up items, retrieving listed items for sale, and transferring items.

​
Prerequisites

  • User must be connected with the ITEMS_READ permission for inventory lookups.
  • ITEMS_WRITE permission is required for item transfers.
  • Your application must be the creator of the item for transfers.

​
Setup

import { HandCashConnect } from '@handcash/handcash-connect';

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

const account = handCashConnect.getAccountFromAuthToken(token);

​
Look Up Items in Inventory

Retrieve items from the user’s inventory: 
const items = await account.items.getItemsInventory({ from: 0, to: 50 });
console.log(items);

​
Filtering Inventory

You can use various parameters to filter items: 
type GetItemsFilter = {
  from?: number;
  to?: number;
  collectionId?: string;
  searchString?: string;
  groupingValue?: string;
  fetchAttributes?: boolean;
  sort?: 'name';
  order?: 'asc' | 'desc';
  attributes?: AttributeFilter[];
  appId?: string;
  group?: boolean;
  externalId?: string;
};

export type AttributeFilter = {
	name: string;
	displayType: 'string' | 'number';
	operation: 'equal' | 'greater' | 'lower';
	value: string | number;
};

// Example: Filter items from a specific collection with attributes
const params: GetItemsFilter = {
  from: 0,
  to: 20,
  collectionId: '64b93458b3a3a4daa4404455',
  attributes: [
    {
      name: 'element',
      displayType: 'string',
      operation: 'equal',
      value: 'Wind',
    },
    {
      name: 'edition',
      displayType: 'string',
      operation: 'matches',
      value: 'Fi*',
    },
  ],
};

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

​
Get Listed Items for Sale

Retrieve items listed in the market: 
const listedItems = await account.items.getItemListings({ from: 0, to: 50 });
console.log(listedItems);

​
Filtering Listed Items

You can use the same filtering parameters as with inventory items: 
const params: GetItemsFilter = {
  from: 0,
  to: 50,
  searchString: 'dragon',
  order: 'asc',
  sort: 'name',
};
const listedInventory = await account.items.getItemListings(params);

​
Transfer Items

Transfer items to another HandCash user or an external wallet: 
// Transfer to another HandCash user via handle
const result = await account.items.transfer({
  destinationsWithOrigins: [
    {
      destination: 'satoshi',
      origins: ['27c02c976adbf0acb212b850ce0c0b1b796de0a646c93304f94f2dc3249cad25_33']
    }
  ]
});

// Transfer to an external wallet via address
const externalResult = await account.items.transfer({
  destinationsWithOrigins: [
    {
      destination: '18jMjdXWXYFNU2waM8wCepTiUzuiQ8gZHt',
      origins: ['27c02c976adbf0acb212b850ce0c0b1b796de0a646c93304f94f2dc3249cad25_33']
    }
  ]
});

console.log('Transaction ID:', result.transactionId);

​
Locking items

You can prevent an item from being transferred by locking it. 
const origin = '0a3eb965a039cb15e731e2b1b2a67b7c024e6a6b59c1f7c32a9cec1d6b5bb7e7_48';
await account.items.lockItems(origin);
Later on, you can unlock it as follows. 
const origin = '0a3eb965a039cb15e731e2b1b2a67b7c024e6a6b59c1f7c32a9cec1d6b5bb7e7_48';
await account.items.unlockItems(origin);
You can also get the list of locked items. 
const lockedItems = await account.items.getLockedItems({
  from: 0, to: 10, fetchAttributes: true,
});

​
Important Notes

  • The group parameter in filters returns items grouped by groupingValue, useful for large inventories.
  • externalId can be used to map items to your application’s reference system.
  • For item transfers, ensure your application has the necessary permissions and is the creator of the item.
For more detailed information on item management and advanced features, refer to the HandCash Items API documentation.