Skip to main content
⚠️ Legacy SDK DocumentationThis documentation uses our older SDK (@handcash/handcash-connect), but the v3 SDK does not support this feature yet.

​
Lock and Unlock Items

Prevent items from being transferred by locking them, or unlock them to allow transfers again.

​
Prerequisites

  • User must be connected with the ITEMS_WRITE permission
  • Your application must be the creator of the item

​
Setup

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

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

const account = handCashConnect.getAccountFromAuthToken(token);

​
Lock Items

You can prevent an item from being transferred by locking it: 
const origin = '0a3eb965a039cb15e731e2b1b2a67b7c024e6a6b59c1f7c32a9cec1d6b5bb7e7_48';
await account.items.lockItems(origin);

​
Lock Multiple Items

const origins = [
  'item-origin-1',
  'item-origin-2',
  'item-origin-3'
];

for (const origin of origins) {
  await account.items.lockItems(origin);
}

​
Unlock Items

Later on, you can unlock items to allow transfers again: 
const origin = '0a3eb965a039cb15e731e2b1b2a67b7c024e6a6b59c1f7c32a9cec1d6b5bb7e7_48';
await account.items.unlockItems(origin);

​
Unlock Multiple Items

const origins = [
  'item-origin-1',
  'item-origin-2',
  'item-origin-3'
];

for (const origin of origins) {
  await account.items.unlockItems(origin);
}

​
Get Locked Items

Retrieve a list of locked items: 
const lockedItems = await account.items.getLockedItems({
  from: 0,
  to: 10,
  fetchAttributes: true,
});

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

​
Parameters

  • from: Starting index (default: 0)
  • to: Ending index (default: 10)
  • fetchAttributes: Whether to include item attributes (default: false)

​
Use Cases

​
Lock Valuable Items

async function lockValuableItems() {
  // Get user's inventory (use v3 Connect.getItemsInventory for this)
  // Filter for valuable items
  const valuableOrigins = [
    'legendary-item-origin-1',
    'epic-item-origin-2'
  ];
  
  for (const origin of valuableOrigins) {
    await account.items.lockItems(origin);
  }
  
  console.log(`Locked ${valuableOrigins.length} valuable items`);
}

​
Unlock Before Transfer

async function transferItem(itemOrigin: string, destination: string) {
  // Unlock item first
  await account.items.unlockItems(itemOrigin);
  
  // Then transfer
  const result = await account.items.transfer({
    destinationsWithOrigins: [
      {
        destination: destination,
        origins: [itemOrigin]
      }
    ]
  });
  
  return result.transactionId;
}

​
Important Notes

  • Locked items cannot be transferred until they are unlocked
  • Only the app that created the item can lock/unlock it
  • Locking is useful for preventing accidental transfers of valuable items
  • Use getLockedItems() to check which items are currently locked