Social Endpoints

Description of endpoints used to get social data on the DeSo blockchain

Please make sure you've read 3️⃣ Data: API so you are familiar with the following types referenced in this documentation:

• ProfileEntryResponse

• PostEntryResponse

• BalanceEntryResponse

• NFTEntryResponse

• NFTCollectionResponse

Get Hodlers For Public Key

POST /api/v0/get-hodlers-for-public-key

Get BalanceEntryResponse objects for users who are holding (or held by) a certain public key's creator coin. Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Hodlers For Public Key - Use GetHodlersForPublicKey to show all the users who are holding a creator's coin or a creator's DAO coin - Use GetHodlersForPublicKey to see all users who hold your DAO coin - Use GetHodlersForPublicKey to see all DAO coins you hold

Request Body

Name	Type	Description
PublicKeyBase58Check	String	Public key for which you want to fetch hodlings or hodlers Required only if Username is not provided
Username	String	Username for which you want to fetch hodlings or hodlers Required only if PublicKeyBase58Check is not provided
LastPublicKeyBase58Check	String	Public key of the last hodler/hodlee from the previous page. Indicates the point at which we want to start returning results.
NumToFetch	uint64	number of records to fetch
FetchHodlings	Boolean	If true, fetch balance entries for hodlings of the user instead of balance entries for hodlers of the user's coin
FetchAll	Boolean	if true, fetch all results. Supercedes NumToFetch.
IsDAOCoin	Boolean	If true, fetch hodlers of DAO coin instead of creator coin

200: OK Successfully retrieved BalanceEntryResponses for each user who are holding/are held by the provided public key/username

Sample Response

{
    Hodlers: [<BalanceEntryResponse>, <BalanceEntryResponse>],
    LastPublicKeyBase58Check: "BC1YLianxEsskKYNyL959k6b6UPYtRXfZs4MF3GkbWofdoFQzZCkJRB" 
}

Response Field Descriptions

Name	Type	Description
Hodlers	[]	Array of objects representing the users who hold (or are held by) the provided public key or username. Each tells you how much that user is holding.
LastPublicKeyBase58Check	String	Public key of the last object from this page of results. Used to fetch the next page of results.

400: Bad Request

{
    // Response
}

Get Diamonds for Public Key

POST /api/v0/get-diamonds-for-public-key

Get a list of objects representing all the diamonds a user has given or received.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Diamonds For Public Key - Use GetDiamondsForPublicKey to show all users who have given a creator a diamond, how many diamonds they've given to that creator, and the highest level of diamond

Request Body

Name	Type	Description
PublicKeyBase58Check*	String	Public key of the user for whom we want to fetch diamonds
FetchYouDiamonded	Boolean	If true, fetch diamonds this user gave out instead of diamond this user received

200: OK Successfully retrieved diamonds a user gave or received

Sample Response

{
    DiamondSenderSummaryResponses: [
        {
            SenderPublicKeyBase58Check: "BC1YLhtBTFXAsKZgoaoYNW8mWAJWdfQjycheAeYjaX46azVrnZfJ94s", // Public Key of the user who sent the diamond
            ReceiverPublicKeyBase58Check: "BC1YLgxLrxvq5mgZUUhJc1gkG6pwrRCTbdT6snwcrsEampjqnSD1vck", // Public key of the user who received the diamond
            TotalDiamonds: 8, // The number of diamonds the sender has sent to the receiver.
            HighestDiamondLevel: 2, // The highest level of diamond the sender has sent to the receiver.
            DiamondLevelMap: { 1: 4, 2: 2 }, // Map of diamond level to the number of times the sender gave that level of diamond to the receiver.
            ProfileEntryResponse: <ProfileEntryResponse>, // If FetchYouDiamonded is true, this will be the profile of the receiver. If false, this will be the profile of the sender.
        },
    ],
    TotalDiamonds: 555 // Total number of diamonds received or given by the profile that matches PublicKeyBase58Check
}

Response Field Descriptions

...coming soon! See comments in sample response for descriptions for now.

400: Bad Request

{
    // Response
}

Get Follows Stateless

POST /api/v0/get-follows-stateless

Get followers of a certain user/public key or get users followed by a certain user/public key and the total number of followers/followees.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Follows Stateless - Use GetFollows to show the total number of users following a creator and the total number of users followed by a creator - Use GetFollows to see all users who follow (or alternatively are followed by) a creator

Request Body

Name	Type	Description
PublicKeyBase58Check	String	Public key for which we want to fetch followers or followees Required only if Username is not provided
Username	String	Username for which we want to fetch followers or following Required only if PublicKeyBase58Check is not provided
GetEntriesFollowingUsername	Boolean	- If true, get entries that are following the specified user. - If false, get entries that are followed by the specified user.
LastPublicKeyBase58Check	String	Public key of the last follower/followee from the previous page. Indicates the point at which we want to start returning results.
NumToFetch	uint64	number of records to fetch

200: OK Successfully retrieved the requested page of followers/followee

Sample Response

{
  PublicKeyToProfileEntry: { // Map of public key to ProfileEntryResponse representing followers or followees
    "BC1YLfuD5AGm2guj3q5wF7WGi3jTUzNhHUHc84GtVsk9kHyxbnk5V1H" : <ProfileEntryResponse>
  }, 
  NumFollowers: 17707 // Total number of followers or followees
}

Response Field Descriptions

...coming soon! See comments in sample response for descriptions for now.

400: Bad Request

{
    // Response
}

Is Following Public Key

POST /api/v0/is-following-public-key

Check if the user is following a public key.

Endpoint implementation in backend.

Request Body

Name	Type	Description
PublicKeyBase58Check*	String	Public key of the user that may be following
IsFollowingPublicKeyBase58Check*	String	Public key of the creator we want to check if the user is following

200: OK Successfully retrieved whether or not the request public key is following IsFollowingPublicKeyBase58Check

Sample Response

{
  IsFollowing: true // true if the user is following the IsFollowingPublicKeyBase58Check. Otherwise, false.
}

Response Field Descriptions

Name	Type	Description
IsFollowing	Boolean	true if the user is following the IsFollowingPublicKeyBase58Check. Otherwise, false

400: Bad Request

{
    // Response
}

Is Hodling Public Key

POST /api/v0/is-hodling-public-key

Check if the user holds the creator coin of a public key. If user is holding some amount of creator coin, we return the BalanceEntryResponse representing how much the user holds.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Is Hodling Public Key - Use IsHodlingPublicKey to check if a user is a DAO member and can be transferred a DAO coin that is restricted to DAO members only.

Request Body

Name	Type	Description
PublicKeyBase58Check*	String	Public key of the user that may be holding the creator coin of IsHodlingPublicKeyBase58Check
IsHodlingPublicKeyBase58Check*	String	Public key of the creator we want to check that the user is holding
IsDAOCoin	Boolean	If true, check if this public key is hodling the DAO coin instead of creator coin

200: OK Successfully retrieved whether PublicKeyBas58Check is hodling the creator coin or DAO coin of IsHodlingPublicKeyBase58Check

Sample Response

{
  IsHodling: true, // true if the user holds the creator coin of IsHodlingPublicKeyBase58Check, Otherwise, false.
  BalanceEntry: <BalanceEntryResponse> // Balance entry that shows the amount of creator coins the user holds.
}

Response Field Descriptions

Name	Type	Description
IsHodling	Boolean	true if the user holds the creator coin of IsHodlingPublicKeyBase58Check, Otherwise, false.
BalanceEntry		that shows the amount of creator coins the user holds.

400: Bad Request

{
    // Response
}