Items
Manage Inventory
Look up and transfer users digital items in HandCash
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);
Important Notes
- The
group
parameter in filters returns items grouped bygroupingValue
, 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.