User Endpoints

Description of endpoints used to get data related to users and profiles 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 Users Stateless

POST /api/v0/get-users-stateless

Get information about multiple users. This endpoint is used for retrieving data about a user after they log in, so the UI can adjust to the attributes of the user.

Request contains a list of public keys of users to fetch.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Users Stateless - Use GetUsersStateless to retrieve data about users upon login - Use GetUsersStateless to retrieve profiles for the Bithunt community projects leaderboard

Request Body

Name	Type	Description
PublicKeysBase58Check*	String[]	list of public keys
SkipForLeaderBoard	Boolean	Skips fetching all attributes other than the ProfileEntryResponse and PublicKeyBase58Check
GetUnminedBalance	Boolean	If true, get all UTXOs to compute the user's unmined balance. This is slower and not recommended.

200: OK Successfully return all user objects requested, param updater public keys, and the default fee

Sample Response

{
  UserList: [
    {
      PublicKeyBase58Check: "BC1YLg3FS19Syz9h6fqErZEtsKkRxBfkzqp75PiGwMUXJ1fLrytRVVk",
      ProfileEntryResponse: <ProfileEntryResponse>,
      Utxos: [], // Deprecated
      BalanceNanos: 100, // User's balance. If SkipForLeaderboard, 0 is always returned. 
      UnminedBalanceNanos: 5, // User's balance in nanos that has not been mined into a block yet. If SkipForLeaderboard, 0 is always returned.
      PublicKeysBase58CheckFollowedByUser: ["BC1YLianxEsskKYNyL959k6b6UPYtRXfZs4MF3GkbWofdoFQzZCkJRB"], // List of public keys followed by this user. If SkipForLeaderboard, an empty array is always returned.
      UsersYouHODL: [<BalanceEntryResponse>, <BalanceEntryResponse>], // Array of Balance entry responses representing this user's creator coin holdings. If SkipForLeaderboard, an empty array is always returned.
      UsersWhoHODLYou: 2, // Count of the number of unique public keys that own this user's creator coin. If SkipForLeaderboard, 0 is always returned.
      HasPhoneNumber: false, // If true, this user has verified their phone number for free DeSo. If SkipForLeaderboard, 0 is always returned.
      CanCreateProfile: true, // If true, this user is able to create a profile. Either they have enough DeSo to cover the create profile fee OR they've verified their phone number OR verified through the Jumio flow. If SkipForLeaderboard, false is always returned.
      BlockedPubKeys: { // BlockedPubKeys is a map with keys representing Public Keys this user has blocked. Values are empty object with no significance. A map is used to improve look up performance. If SkipForLeaderboard, an empty object is always returned.
        "BC1YLiUt3iQG4QY8KHLPXP8LznyFp3k9vFTg2mhhu76d1Uu2WMw9RVY": {},
      },
      HasEmail: true, // If true, the user has provided an email. If SkipForLeaderboard, false is always returned.
      EmailVerified: true, // If true, the user has verified their email address by clicking on a link sent to them. If SkipForLeaderboard, false is always returned. 
      JumioStartTime: 1908230921, // The time at which this user began the Jumio flow. If SkipForLeaderboard, 0 is always returned.
      JumioFinishedTime: 1908230949, // The time at which the user finished the Jumio flow. If SkipForLeaderboard, 0 is always returned.
      JumioVerified: true, // If true, the user successfully completed the Jumio flow and Jumio verified their identity. If SkipForLeaderboard, false is always returned.
      JumioReturned: true, // If true, Jumio's callback after scanning ID has been received. If SkipForLeaderboard, false is always returned.
      IsAdmin: true, // If true, this user is an admin on this node. If SkipForLeaderboard, false is always returned.
      IsSuperAdmin: true, // If true, this user is a superadmin on this node. If SkipForLeaderboard, false is always returned.
      IsBlacklisted: false, // If true, this user is blacklisted on this node. If SkipForLeaderboard, false is always returned.
      IsGraylisted: false, // If true, this user is graylisted on this node. If SkipForLeaderboard, false is always returned.
      TutorialStatus: "TutorialStarted", // Indicates where in the tutorial the user currently is. If SkipForLeaderboard, the empty string is always returned.
      CreatorPurchasedInTutorialUsername: "LazyNina", // Username of the creator the user purchased during the tutorial flow. If SkipForLeaderboard, the empty string is always returned.
      CreatorCoinPurchasedInTutorial: 1823789, // The amount of Lazy Nina creator coins purchased in the tutorial. If SkipForLeaderboard, 0 is always returned.false
      MustCompleteTutorial: true, // If true, the user must finish the tutorial before they are able to perform basic transfers on this node. If SkipForLeaderboard, false is always returned.
    },
  ], 
  DefaultFeeRateNanosPerKB: 100, // The minimum network fee rate in Nanos Per KB. 
  ParamUpdaters: { // Map of Public key to Param Updaters.
    BC1YLfoSyJWKjHGnj5ZqbSokC3LPDNBMDwHX3ehZDCA3HVkFNiPY5cQ: true,
    BC1YLfz4GH3Gfj6dCtBi8bNdNTbTdcibk8iCZS75toUn4UKZaTJnz9y: true,
    BC1YLg3oh6Boj8e2boCo1vQCYHLk1rjsHF6jthBdvSw79bixQvKK6Qa: true,
    BC1YLgD1f7yw7Ue8qQiW7QMBSm6J7fsieK5rRtyxmWqL2Ypra2BAToc: true,
    BC1YLgGLKjuHUFZZQcNYrdWRrHsDKUofd9MSxDq4NY53x7vGt4H32oZ: true,
    BC1YLiXwGTte8oXEEVzm4zqtDpGRx44Y4rqbeFeAs5MnzsmqT5RcqkW: true,
    BC1YLj8UkNMbCsmTUTx5Z2bhtp8q86csDthRmK6zbYstjjbS5eHoGkr: true,
  } 
}5

Response Field Descriptions

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

400: Bad Request

{
    // Response
}

Get Profiles

POST /api/v0/get-profiles

Get user profiles for searching by name or for the creator leaderboard.

Default number of returned profiles is 20.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Profiles - Use GetProfiles to search for users by username - Use GetProfiles to get profiles for the creator leaderboard

Request Body

Name	Type	Description
PublicKeyBase58Check	String	When provided, find the profile that contains the public key. The page of results returned by this endpoint will start at the profile that is next in the ordered list.
Username	String	When provided, find the profile that contains this username. The page of results returned by this endpoint will start at the profile that is next in the ordered list.
UsernamePrefix	String	username prefix. When provided, only return profiles with usernames that match this prefix
Descripton	String	Deprecated
OrderBy	String	Ordering method to be used on the result set \ \ Must be one of newest_last_post , newest_last_comment , or influencer_coin_price
NumToFetch	uint32	Number of profiles to fetch. Defaults to 20. \ \ Must be less than 100
ReaderPublicKeyBase58Check	String	Reader public key
ModerationType	String	empty string, unrestricted, or leaderboard. If unrestricted, return all results. If leaderboard, filter out both blacklisted and graylisted users. If empty string, filter out blacklisted users.
FetchUsersThatHODL	Boolean	If single profile is requested, return a list of HODLers
AddGlobalFeedBool	Boolean	If set to true posts in response will contain boolean if they are in global feed

200: OK List of profiles requested and a NextPublicKey to use to get the next page of results

Sample Response

{
    ProfilesFound: [<ProfileEntryResponse>, <ProfileEntryResponse>], // Array of ProfileEntryResponse Objects.
    NextPublicKey: "BC1YLianxEsskKYNyL959k6b6UPYtRXfZs4MF3GkbWofdoFQzZCkJRB", // This is the PublicKeyBase58Check needed to fetch the next page of results. 
}

Response Field Descriptions

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

400: Bad Request

{
    // Response
}

Get Single Profile

POST /api/v0/get-single-profile

Get information about single profile.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Single Profile - Use GetSingleProfile to get information to display on a user's profile page - Use GetSingleProfile to search for a profile by public key

Request Body

Name	Type	Description
PublicKeyBase58Check	String	public key of the profile to fetch \ \ required if Username is not provided
Username	String	username of the profile to fetch \ \ required if PublicKeyBase58Check is not provided
NoErrorOnMissing	Boolean	If true, do not throw a 404 error if there is no profile found. Instead, nil will be return for the Profile in the response body.

200: OK

Sample Response

{
   Profile: <ProfileEntryResponse>, // ProfileEntryResponse for the username or public key provided.
   IsBlacklisted: false, // If true, this user is blacklisted on this node.
   IsGraylisted: false,  // If true, this user is graylisted on this node.
}

Response Field Descriptions

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

400: Bad Request

{
    // Response
}

404: Not Found No profile found for the provided username or public key

{
    // Response
}

Get Single Profile Picture

GET /api/v0/get-single-profile-picture/{PublicKeyBase58Check}

Returns the profile picture of the given public key

Endpoint implementation in backend.

Example usage in frontend: - Construct the Get Single Profile Picture URL - Use GetSingleProfilePictureURL to get the profile picture for a user

Path Parameters

Name	Type	Description
PublicKeyBase58Check*	String	Public key of the user for whom we are fetching a profile picture

Query Parameters

Name	Type	Description
fallback	String	URL of the image to be used in the event that there is no profile picture for the public key provided

200: OK Profile picture found

Image file of the profile picture is returned

400: Bad Request

{
    // Response
}

404: Not Found No profile picture found for public key provided

{
    // Response
}

Get User Global Metadata: Email And Phone Number

POST /api/v0/get-user-global-metadata

Get user metadata such as email and phone.

This endpoint requires a JWT, which can be retrieved from Identity.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get User Global Metadata - Use GetUserGlobalMetadata to fetch email address to display on settings page

Note: this data is not stored on-chain.

Request Body

Name	Type	Description
UserPublicKeyBase58Check*	String	user public key
JWT*	String	JSON web token authenticating user

200: OK Successfully retrieved user

Sample Response

{
    Email: "[email protected]",
    PhoneNumber: "123346789"
}

Response Field Descriptions

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

400: Bad Request

{
    // Response
}

Update User Global Metadata: Email and State of Messages Read

POST /api/v0/update-user-global-metadata

Update user's email address and the state of messages that have been read.

This endpoint requires a JWT, which can be retrieved from Identity.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Update User Global Metadata - Use UpdateUserGlobalMetadata to update email address

Request Body

Name	Type	Description
UserPublicKeyBase58Check*	String	user public key
JWT*	String	JSON web token authenticating user
Email	String	new email address. If provided, an email will be sent to verify this email address
MessageReadStateUpdatesByContact	Object with string keys and int values	A map with keys that represent public keys that have messaged this user. The values represent the index of the message read in the conversation between the two users.

200: OK Successfully updated user global metadata

No response body

400: Bad Request

{
    // Response
}

Get User Metadata

GET /api/v0/get-user-metadata/{PublicKeyBase58Check}

Get user metadata. Typically, this endpoint is used when reaching node.deso.org to get user metadata that should be merged with user metadata from one's local node.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get User Metadata - Use GetUserMetadata to get additional data about a user to merge in with user metadata fetch from local node

Path Parameters

Name	Type	Description
PublicKeyBase58Check*	String	Public key of the user for whom we are fetching user metadata

200: OK Successfully retrieved user metadata from this node

Sample Response

{
  "HasPhoneNumber": false, // Whether the user verified a phone number. Used to know whether to allow user to launch identity to get free DeSo for verifying their phone number 
  "CanCreateProfile": true, // Whether or not this user is capable of creating a profile. Even if a user does not have enough DeSo to create a profile, they may be able to create a profile since it will be comped by the node to which this request was made. Usually profile creation will be comped if a user verified either their phone number or went through the Jumio flow.
  "BlockedPubKeys": { // Map of public keys that are blocked by the user.
    "BC1YLhtBTFXAsKZgoaoYNW8mWAJWdfQjycheAeYjaX46azVrnZfJ94s": {},
  },
  "HasEmail": false, // Whether the user provided an email to the node to which this request was made.
  "EmailVerified": false, // Whether the user verified their email address.
  "JumioFinishedTime": 1629943843752943900, // Time user finished the jumio flow
  "JumioVerified": true, // Whether the user was verified by Jumio
  "JumioReturned": true // Whether Jumio returned a callback for this user.
}

Response Field Descriptions

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

400: Bad Request

{
    // Response
}

404: Not Found Node does not expose its global state so you are unable to get user metadata from the requested node

{
    // Response
}

Delete PII - Personal Identifiable Information

POST /api/v0/delete-pii

Deletes email address and phone number associated with this user from the node's global state.

This endpoint requires a JWT, which can be retrieved from Identity.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Delete PII - Use DeletePII to remove user's personal information at the user's request

Request Body

Name	Type	Description
PublicKeyBase58Check*	String	user public key that wants to delete their PII
JWT*	String	JSON web token authenticating user

200: OK Successfully deleted personal identifiable information including phone number and email address

No response body

400: Bad Request

{
    // Response
}

Block Public Key

POST /api/v0/block-public-key

Block another user. Blocking a user hides that user from everything you see and the blocked user's comments on your posts will be hidden for all other users.

Note: Blocks are not currently stored on chain and thus a block only applies to the node on which a user is blocked.

This endpoint requires a JWT, which can be retrieved from Identity.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Block Public Key - Use BlockPublicKey to block a user as described above - Use BlockPublicKey to unblock a user

Request Body

Name	Type	Description
PublicKeyBase58Check*	String	user public key
JWT*	String	JSON web token authenticating user
BlockPublicKeyBase58Check*	String	blocked user public key
Unblock	Boolean	false if block, true if unblock

200: OK Successfully blocked public key and return all public keys currently blocked by this user

Sample Response

{
    BlockedPublicKeys: {
        "BC1YLhqEhWvNnwW9TBqXURFqwkdpUYKrMVgTHQzopF5rRBDcD1LLSUp": {}, // Every key in the map is a blocked pulic key.
    }
}

Response Field Descriptions

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

400: Bad Request

{
    // Response
}

Get User Derived Keys

POST /api/v0/get-user-derived-keys

Get a map of derived public keys to metadata about that derived key for a given master public key.

Endpoint implementation in backend.

Request Body

Name	Type	Description
PublicKeyBase58Check*	String	Public key for which we want to query derived keys

200: OK Successfully retrieved derived keys for user

Sample Response

{
  DerivedKeys: {
    BC1YLhqEhWvNnwW9TBqXURFqwkdpUYKrMVgTHQzopF5rRBDcD1LLSUp: { // Key is a derived key
      OwnerPublicKeyBase58Check: "BC1YLfuD5AGm2guj3q5wF7WGi3jTUzNhHUHc84GtVsk9kHyxbnk5V1H", // Owner of the derived key.
      DerivedPublicKeyBase58Check: "BC1YLhqEhWvNnwW9TBqXURFqwkdpUYKrMVgTHQzopF5rRBDcD1LLSUp", // The derived key itself.
      ExpirationBlock: 1000000, // THe block height at which the derived key expires.
      IsValid: true // If true, this derived key can still perform actions on behalf of the owner.
    } 
  }
}

Response Field Descriptions

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

400: Bad Request

{
    // Response
}

Delete Identities

POST /api/v0/delete-identities

Temporary route to wipe seedinfo cookies. This endpoint relies on identity api.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Delete Identities - Use DeleteIdentities to clean up legacy seedinfo storage

200: OK Successfully deleted cookies

{
    // Response
}