Profile API (1.0.0)

Feature Overview

The Profile API allows clients to retrieve and update domain profile details. There are both public and authenticated endpoints available for domain profiles. For authenticated endpoints, the API requires request signatures generated using the domain owner's private key.

Public endpoint overview

These endpoints are available without any authentication.

  • Retrieve public profile data associated with a domain
    • Domain owner controls which fields are public or private
    • Private data is always the default
  • Retrieve NFTs for addresses associated with domain
    • Domain can have any number of blockchain addresses associated for resolution services
    • Resolution addresses are stored on-chain
    • Query on-chain data for NFTs
  • Retrieve badges data for addresses associated with domain

Authenticated endpoint overview

The owner of a domain may use this API to view or edit their private profile data. When managing profile data, authentication headers must be provided using the approach described below.

How to authenticate

  • Determine the message that must be signed by requesting the corresponding message generator endpoint
    • GET or POST to the /api/user/domain.tld/signature endpoint
      • Include all query string parameters to be used in the desired request
      • Include the JSON body for POST requests
    • Response contains the message that must be signed
      • Message is a unique hash value
      • Represents combination of provided request parameters
      • Includes an expiration timestamp
  • User must sign the message returned by the message generator API
    • For example, the Metamask wallet could be used to sign the message
    • Generated signature is used in header of subsequent GET or POST request
  • Construct a request to the corresponding signature required endpoint
    • Request must match parameters signed by domain owner
    • Must include headers
      • x-auth-domain - Must equal the domain in context
      • x-auth-expiration - Must equal the expiration timestamp in the signed message
      • x-auth-signature - Must be set to the value of the user provided signature

Badge endpoints

Retrieves details about a badge

Retrieves details about a badge, including definition and usage statistics.

Request
path Parameters
badge
required
string

The badge code

Example: whale
Responses
200

Badge details

404

Badge not found

get/api/badges/{badge}
Request samples 
Response samples 
application/json
{
  • "badge": {},
  • "sponsorship": {
    },
  • "usage": {
    }
}
Generates a badge based on a provided marketplace link
Creates a badge based on a provided marketplace link, such as OpenSea, Zuse.market, etc. The badge must be purchased to be activated before it can be claimed by other domains.


Request 
Request Body schema: application/json
link
string
Marketplace link to the NFT collection you want to claim a badge (e.g. OpenSea, MagicEden, Zuse.market, etc)


 
Responses 
200
Badge pending payment


400
Invalid marketplace link


404
Collection not found


409
Badge already claimed


post/api/badges/claim
Request samples 
application/json
{}
Response samples 
application/json
{}
Retrieve badge rankings by domain
Generates a list of domains ordered by largest badge collection


Request 
path Parameters
count
number
The number of rankings to retrieve


 
communityOnly
boolean
Include only community sponsored badges


 
Responses 
200
Badge rankings


get/api/badges/rankings/domains
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieve badge rankings
Generates a list of badges ordered by number of holders


Request 
path Parameters
count
number
The number of rankings to retrieve


 
communityOnly
boolean
Include only community sponsored badges


 
Responses 
200
Badge rankings


get/api/badges/rankings
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieve badge rankings by sponsor
Generates a list of sponsors ordered by largest number of sponsored badges


Request 
path Parameters
count
number
The number of rankings to retrieve


 
Responses 
200
Sponsor rankings


get/api/badges/rankings/sponsors
Request samples 
Response samples 
application/json
[
  • {
    }
]
Profile data endpoints
Retrieves badges associated with a domain
Retrieves badge data associated with requested domain.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
query Parameters
partners
boolean
Include available partner badges in response


 
Responses 
200
Domain badge data


404
Domain not found


get/api/public/{domain}/badges
Request samples 
Response samples 
application/json
{}
Retrieves publicly accessible domain profile
Retrieves public domain profile accessible to anyone on the internet. All domain profile data is considered private, unless explicitly authorized by the domain owner. In other words, data shown on the public API is controlled by the domain owner.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
query Parameters
fields
string
Comma separated list of fields to retrieve. Defaults to cryptoVerifications,profile,socialAccounts,referralCode.


 
 Example:  fields=cryptoVerifications,humanityCheck,profile,records,socialAccounts,referralCode
Responses 
200
Domain profile


404
Domain not found


get/api/public/{domain}
Request samples 
Response samples 
application/json
{
  • "profile": {},
  • "humanityCheck": {
    },
  • "cryptoVerifications": [
    ],
  • "records": {
    },
  • "metadata": {
    },
  • "socialAccounts": {
    },
  • "referralCode": "d83b1155f85f4fc"
}
Retrieves NFT data associated with blockchain accounts attached to a domain
Retrieves NFT data associated with requested domain. Paging is supported using the limit and cursor query string parameters.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
query Parameters
symbols
string
Comma separated list of ticker symbols to query NFT data


 
 Example:  symbols=ETH,MATIC,SOL
limit
number
The maximum number of NFT records to retrieve


 
 Example:  limit=50
cursor
string
The paging cursor used in combination with the limit parameter


 
 Example:  cursor=desiredPage
resolve
boolean
Indicate whether off-chain NFT metadata should be retrieved (default, true)


 
Responses 
200
Domain NFT data


404
Domain not found


get/api/public/{domain}/nfts
Request samples 
Response samples 
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}
Profile management endpoints
Verify ownership of a blockchain address
Verify ownership of a blockchain address by signing a message with your private key.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
symbol
required
string
The ticker symbol for the blockchain to verify


 
Request Body schema: application/json
message
string
A custom message that must be signed with the private key of the address


 
signature
string
Signature generated by signing the message with the private key


 
Responses 
200
Address verification successful


400
Request contained invalid parameters


404
Domain not found


post/api/user/{domain}/address/{symbol}
Request samples 
application/json
{
  • "message": "Unique message to sign",
  • "signature": "cd0dadab45baf9a06ce1279d1342ecc3f44845af"
}
Retrieves domain's private profile data
While the public API retrieves only the data identified as shareable by the domain owner, this API returns both public and private data. Authentication is required using domain owner signature.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
query Parameters
fields
string
Comma separated list of fields to retrieve. Defaults to cryptoVerifications,messaging,profile,socialAccounts.


 
 Example:  fields=cryptoVerifications,humanityCheck,messaging,profile,records,socialAccounts,referralCode,referralTier
header Parameters
x-auth-domain
required
string
The domain to authorize


 
 Example:  mydomain.tld
x-auth-expires
required
string
The expiration time of the signature


 
 Example:  1765522015090
x-auth-signature
required
string
The signature generating using domain owner private key


 
 Example:  b62348775da58077591e2d20506371e8d94a5a83031f34b9ac85845d3463e73b0f0a500875830785c093515806e354cda6c217acab0fce5245d662eff4105f5e1c
Responses 
200
Domain profile


404
Domain not found


get/api/user/{domain}
Request samples 
Response samples 
application/json
{
  • "profile": {
    },
  • "messaging": {
    },
  • "humanityCheck": {
    },
  • "cryptoVerifications": [
    ],
  • "records": {
    },
  • "socialAccounts": {
    },
  • "referralCode": "d83b1155f85f4fc"
}
Edit domain's private profile data
The POST call can be used to create a new domain profile or make updates to an existing profile. Authentication is required using domain owner signature.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
header Parameters
x-auth-domain
required
string
The domain to authorize


 
 Example:  mydomain.tld
x-auth-expires
required
string
The expiration time of the signature


 
 Example:  1765522015090
x-auth-signature
required
string
The signature generating using domain owner private key


 
 Example:  0b62348775da58077591e2d20506371e8d94a5a83031f34b9ac85845d3463e73b0f0a500875830785c093515806e354cda6c217acab0fce5245d662eff4105f5e1c
Request Body schema: application/json
displayName
string
Name of domain owner


 
displayNamePublic
boolean
 
description
string
Short biography about the domain


 
descriptionPublic
boolean
 
location
string
Location


 
locationPublic
boolean
 
imagePath
string
URL to the domain profile picture


 
imagePathPublic
boolean
 
coverPath
string
URL to the domain banner image


 
coverPathPublic
boolean
 
web2Url
string
Website URL


 
web2UrlPublic
boolean
 
showDomainSuggestion
boolean
 
showFeaturedCommunity
boolean
 
showFeaturedPartner
boolean
 
phoneNumber
string
Phone number of domain owner


 
phoneNumberPublic
boolean
 
privateEmail
string
Personal email address to contact the domain owner


 
messagingDisabled
boolean
Indicates if messaging feature should be disabled


 
thirdPartyMessagingEnabled
boolean
Indicates if third party messaging should be enabled


 
thirdPartyMessagingConfigType
string
Type of third part messaging


 
object
 
object
 
Responses 
200
Domain profile


404
Domain not found


post/api/user/{domain}
Request samples 
application/json
{
  • "displayName": "John Doe",
  • "displayNamePublic": true,
  • "description": "This is my domain",
  • "descriptionPublic": true,
  • "location": "Metaverse",
  • "locationPublic": true,
  • "imagePath": "https://ipfs.io/ipfs/path/to/pfp",
  • "imagePathPublic": true,
  • "coverPath": "https://ipfs.io/ipfs/path/to/banner",
  • "coverPathPublic": true,
  • "web2Url": "https://www.mywebsite.com",
  • "web2UrlPublic": true,
  • "showDomainSuggestion": true,
  • "showFeaturedCommunity": true,
  • "showFeaturedPartner": true,
  • "phoneNumber": "555-555-5555",
  • "phoneNumberPublic": true,
  • "privateEmail": "me@email.com",
  • "messagingDisabled": true,
  • "thirdPartyMessagingEnabled": true,
  • "thirdPartyMessagingConfigType": "Skiff",
  • "data": {
    },
  • "socialAccounts": {
    }
}
Response samples 
application/json
{
  • "profile": {
    },
  • "messaging": {
    },
  • "humanityCheck": {
    },
  • "cryptoVerifications": [
    ],
  • "records": {
    },
  • "socialAccounts": {
    },
  • "referralCode": "d83b1155f85f4fc"
}
Update NFT preferences for a domain
The POST call can be used to update NFT gallery preferences for addresses resolving to the domain. Authentication is required using domain owner signature.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
header Parameters
x-auth-domain
required
string
The domain to authorize


 
 Example:  mydomain.tld
x-auth-expires
required
string
The expiration time of the signature


 
 Example:  1765522015090
x-auth-signature
required
string
The signature generating using domain owner private key


 
 Example:  0b62348775da58077591e2d20506371e8d94a5a83031f34b9ac85845d3463e73b0f0a500875830785c093515806e354cda6c217acab0fce5245d662eff4105f5e1c
Request Body schema: application/json
 Array 
symbol
string
Crypto symbol associated with the NFT gallery


 
address
string
Wallet address associated with the NFT gallery


 
public
boolean
Indicates whether the NFT gallery is visible to the public


 
showAllItems
boolean
Indicates whether NFTs in the gallery are shown by default


 
order
number
Order preference in relation to other NFT galleries (higher indicates first preference)


 
Array of objects (SerializedDomainNftGalleryItemPost) 
Array of NFT items and their individual preferences


 
Responses 
204
Update successful


400
Request contained invalid parameters


404
Domain not found


post/api/user/{domain}/nfts
Request samples 
application/json
[
  • {
    }
]
Message generator endpoints
Retrieves the message that must be signed to verify ownership of a blockchain address
Retrieves the message that must be signed to verify ownership of a blockchain address. The message must be signed with the blockchain address private key and submitted using the POST call for verification.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
symbol
required
string
The ticker symbol for the blockchain to verify


 
Responses 
200
Message to be signed


400
Address not defined for domain


404
Domain not found


get/api/user/{domain}/address/{symbol}/signature
Request samples 
Response samples 
application/json
{
  • "address": "string",
  • "message": "string",
  • "symbol": "string"
}
Retrieves the message that must be signed to edit domain NFT gallery preferences
Retrieve the required message that must be signed by the domain owner to update a domain. A POST request must include the exact JSON body that will be used to make the update. The entire contents of the JSON body are included in the message hash, to ensure the signature cannot be used in combination with unauthorized modifications to the domain profile.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
query Parameters
expiry
number
Expiry time represented by milliseconds since epoch


 
 Example:  expiry=1765522015090
Request Body schema: application/json
 Array 
symbol
string
Crypto symbol associated with the NFT gallery


 
address
string
Wallet address associated with the NFT gallery


 
public
boolean
Indicates whether the NFT gallery is visible to the public


 
showAllItems
boolean
Indicates whether NFTs in the gallery are shown by default


 
order
number
Order preference in relation to other NFT galleries (higher indicates first preference)


 
Array of objects (SerializedDomainNftGalleryItemPost) 
Array of NFT items and their individual preferences


 
Responses 
200
Message to be signed


404
Domain not found


post/api/user/{domain}/nfts/signature
Request samples 
application/json
[
  • {
    }
]
Response samples 
application/json
{
  • "message": "string",
  • "headers": {
    }
}
Retrieves the message that must be signed to view private domain profile data
Retrieve the message text that must be signed by the domain owner. The request URL and any request data must match exactly the data that will be used on the signature required endpoint.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
query Parameters
expiry
number
Expiry time represented by milliseconds since epoch


 
 Example:  expiry=1765522015090
Responses 
200
Message to be signed


404
Domain not found


get/api/user/{domain}/signature
Request samples 
Response samples 
application/json
{
  • "message": "string",
  • "headers": {
    }
}
Retrieves the message that must be signed to edit private domain profile data
Retrieve the required message that must be signed by the domain owner to update a domain profile. A POST request must include the exact JSON body that will be used to make the update. The entire contents of the JSON body are included in the message hash, to ensure the signature cannot be used in combination with unauthorized modifications to the domain profile.


Request 
path Parameters
domain
required
string
The domain name to query profile data


 
query Parameters
expiry
number
Expiry time represented by milliseconds since epoch


 
 Example:  expiry=1765522015090
Request Body schema: application/json
displayName
string
Name of domain owner


 
displayNamePublic
boolean
 
description
string
Short biography about the domain


 
descriptionPublic
boolean
 
location
string
Location


 
locationPublic
boolean
 
imagePath
string
URL to the domain profile picture


 
imagePathPublic
boolean
 
coverPath
string
URL to the domain banner image


 
coverPathPublic
boolean
 
web2Url
string
Website URL


 
web2UrlPublic
boolean
 
showDomainSuggestion
boolean
 
showFeaturedCommunity
boolean
 
showFeaturedPartner
boolean
 
phoneNumber
string
Phone number of domain owner


 
phoneNumberPublic
boolean
 
privateEmail
string
Personal email address to contact the domain owner


 
messagingDisabled
boolean
Indicates if messaging feature should be disabled


 
thirdPartyMessagingEnabled
boolean
Indicates if third party messaging should be enabled


 
thirdPartyMessagingConfigType
string
Type of third part messaging


 
object
 
object
 
Responses 
200
Message to be signed


404
Domain not found


post/api/user/{domain}/signature
Request samples 
application/json
{
  • "displayName": "John Doe",
  • "displayNamePublic": true,
  • "description": "This is my domain",
  • "descriptionPublic": true,
  • "location": "Metaverse",
  • "locationPublic": true,
  • "imagePath": "https://ipfs.io/ipfs/path/to/pfp",
  • "imagePathPublic": true,
  • "coverPath": "https://ipfs.io/ipfs/path/to/banner",
  • "coverPathPublic": true,
  • "web2Url": "https://www.mywebsite.com",
  • "web2UrlPublic": true,
  • "showDomainSuggestion": true,
  • "showFeaturedCommunity": true,
  • "showFeaturedPartner": true,
  • "phoneNumber": "555-555-5555",
  • "phoneNumberPublic": true,
  • "privateEmail": "me@email.com",
  • "messagingDisabled": true,
  • "thirdPartyMessagingEnabled": true,
  • "thirdPartyMessagingConfigType": "Skiff",
  • "data": {
    },
  • "socialAccounts": {
    }
}
Response samples 
application/json
{
  • "message": "string",
  • "headers": {
    }
}