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.

​
Friends

The Friends API allows you to retrieve a list of the user’s friends and their public profiles. This requires the FRIENDS permission.

​
Prerequisites

  • User must have authorized your app with the FRIENDS permission
  • User account must be initialized with an authentication token

​
Setup

import HandcashConnect from '@handcash/handcash-connect';

const handCashConnect = new HandcashConnect({
  appId: 'YOUR_APP_ID',
  appSecret: 'YOUR_APP_SECRET',
});

const account = handCashConnect.getAccountFromAuthToken('<authToken>');

​
Get Friends

Retrieves a list of the user’s friends and their public profiles. 
async getFriends(): Promise<UserPublicProfile[]>
Returns: A promise that resolves to an array of public profiles of the user’s friends. Example: 
const friends = await account.profile.getFriends();
console.log(`You have ${friends.length} friends.`);

friends.forEach(friend => {
  console.log(`Friend: ${friend.displayName} (@${friend.handle})`);
});

​
Response Type

Each friend in the array is a UserPublicProfile object with the following structure:
FieldTypeDescription
idstringUnique identifier for the user
handlestringUser’s HandCash handle
paymailstringUser’s paymail address
displayNamestringUser’s display name
avatarUrlstringURL of the user’s avatar image
createdAtDateDate when the profile was created
Example Response: 
[
  {
    id: "507f1f77bcf86cd799439011",
    handle: "satoshi",
    paymail: "[email protected]",
    displayName: "Satoshi Nakamoto",
    avatarUrl: "https://example.com/avatar.png",
    createdAt: new Date("2023-01-01T00:00:00.000Z")
  },
  {
    id: "507f1f77bcf86cd799439012",
    handle: "alice",
    paymail: "[email protected]",
    displayName: "Alice",
    avatarUrl: "https://example.com/alice.png",
    createdAt: new Date("2023-02-15T00:00:00.000Z")
  }
]

​
Permissions

The getFriends() method requires the FRIENDS permission. Users must grant this permission when authorizing your app. To check if a user has granted the FRIENDS permission: 
const permissionsInfo = await account.profile.getPermissionsInfo();
const hasFriendsPermission = permissionsInfo.items.includes('FRIENDS');

if (hasFriendsPermission) {
  const friends = await account.profile.getFriends();
} else {
  console.log('User has not granted FRIENDS permission');
}

​
Error Handling

try {
  const friends = await account.profile.getFriends();
  // Process friends list
} catch (error) {
  if (error.message.includes('FRIENDS permission')) {
    console.error('User has not granted FRIENDS permission');
    // Redirect user to re-authorize with FRIENDS permission
  } else {
    console.error('Error fetching friends:', error);
  }
}

​
Use Cases

  • Display user’s friends list in your application
  • Show friend activity or status
  • Enable friend-to-friend features
  • Build social features around HandCash connections

​
Important Notes

  • The FRIENDS permission must be requested during the initial authorization flow
  • If a user hasn’t granted the FRIENDS permission, the method will throw an error
  • Friends data is read-only - you cannot add or remove friends through the API
  • The friends list reflects the user’s current HandCash friends