Skip to main content

Identity

Identity API is used for querying information about an address on the blockchain network. You can retrieve an address's domain name, indexed following & followers list using the GraphQL query shown below.

You can find the step by step instructions on how to set up GraphQL client in your application and write a simple Get Identity query in the Read Identity section.

Structure

The definition of identity query is:

identity(address: String!, network: Network) UserIdentity!
FieldTypeDescriptionRequired/Optional
addressString!The string of the address that you query forRequired
networkNetworkThe blockchain network for the querying addressOptional. Default value is ETH.

With correct input, you can retrieve a UserIdentity object with the following fields:

FieldTypeDescription
addressStringThe address that you are querying
domainStringPrimary ENS domain or Solana domain of the address
avatarStringUser's avatar URL
joinTimeStringThe time of user's first sent transaction on the given blockchain network
twitterTwitterTwitter info bound to the address
githubGithubGithub info bound to the address
followerCountIntHow many followers the user has in the given network and namespace
followingCountIntHow many followings the user has in the given network and namespace
followingsBasicInfoConnectionList of user's followings
followersBasicInfoConnectionList of user's followers
friendsBasicInfoConnectionList of user's friends (mutually followed)
unreadNotificationCountIntHow many unread notifications the user has in the given network and namespaces
notificationsNotificationList of user’s notifications

Retrieve Single Field

If you only need to query one address' ENS, you can run the query below in the Playground:

query QueryForENS {
identity(
address: "0x148d59faf10b52063071eddf4aaf63a395f2d41c"
network: ETH
) {
domain
}
}

You can also use joinTime, avatar, or other fields to get different information about an account.

Retrieve Follower, Following, Friend Lists

Follower, Following, and Friend are endpoints that are implemented with pagination. In order to get the whole dataset of an address, you need to make requests page by page with the correct namespace and pagination input parameters.

For detail, please check Namespace and Pagination page.

Followers Example

You can use this snippet for address' follower list query directly in the Playground:

query FullIdentityQuery {
identity(
address: "0x148d59faf10b52063071eddf4aaf63a395f2d41c"
network: ETH
) {
followerCount(namespace: "CyberConnect")
followers(first: 1) {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
list {
address
domain
avatar
namespace
lastModifiedTime
}
}
}
}

Retrieve Twitter and GitHub Metadata

Twitter Example

You can use this snippet to query an address's Twitter metadata in the Playground:

query TwitterQuery{
identity(address: "0x148d59faf10b52063071eddf4aaf63a395f2d41c", network: ETH) {
twitter {
handle
avatar
verified
tweetId
source
followerCount
}
}
}

Github Example

You can use this snippet to query an address's GitHub metadata in the Playground:

query GithubQuery{
identity(address: "0x9DD481d6C1656816BFd564151E29D57e041D2C8F", network: ETH) {
github {
username
gistId
userId
}
}
}

Retrieve Notifications

UnreadNotificationCount Example

You can use this snippet to query an address’s unread notification count in the Playground:

query QueryForUnreadNotificationCount {
identity(address: "0x148d59faf10b52063071eddf4aaf63a395f2d41c", network: ETH) {
unreadNotificationCount
}
}

Notifications Example

You can use this snippet to query an address’s notification list in the Playground:

{
identity(address: "0x9dd481d6c1656816bfd564151e29d57e041d2c8f", network: ETH) {
notifications {
pageInfo {
hasNextPage
hasPreviousPage
endCursor
startCursor
}
list {
id
toAddress
network
namespace
hasRead
type
timestamp
... on NewConnectionNotification {
fromAddress
connectionType
}
... on BiConnectReceivedNotification {
fromAddress
}
... on BiConnectAcceptedNotification {
fromAddress
}
}
}
}
}

Retrieve All Fields

Full Example

You can try Identity API in the Playground page. Open the page, make sure the URL is correct, copy and paste the following query into the input.

We will take cyberLab.eth as an example on the Ethereum network. To query the information of it, type:

query FullIdentityQuery{
identity(address: "0x148d59faf10b52063071eddf4aaf63a395f2d41c", network: ETH) {
address
domain
avatar
joinTime
twitter {
handle
avatar
verified
tweetId
source
followerCount
}
github {
username
gistId
userId
}
followerCount(namespace: "CyberConnect")
followingCount(namespace: "CyberConnect")
followings(namespace: "CyberConnect", first: 2, after: "-1") {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
list {
address
domain
avatar
alias
namespace
lastModifiedTime
verifiable
}
}
followers(namespace: "CyberConnect", first: 2, after: "-1") {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
list {
address
domain
avatar
alias
namespace
lastModifiedTime
verifiable
}
}
friends(namespace: "CyberConnect", first: 2, after: "-1") {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
list {
address
domain
avatar
alias
namespace
lastModifiedTime
verifiable
}
}
unreadNotificationCount (namespaces: ["CyberConnect"])
notifications (namespaces: ["CyberConnect"], first:2, after: "-1") {
pageInfo {
hasNextPage
hasPreviousPage
endCursor
startCursor
}
list {
id
toAddress
network
namespace
hasRead
type
timestamp
... on NewConnectionNotification {
fromAddress
connectionType
}
... on BiConnectReceivedNotification {
fromAddress
}
... on BiConnectAcceptedNotification {
fromAddress
}
}
}
}
}
Designed by