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
  • Retrieve the following status of two domains

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 holders of the badge

Retrieves a list of addresses that hold the badge

Request
path Parameters
badge
required
string

The badge code

Example: whale
header Parameters
x-api-key
required
string

API key required to authenticate the request

Example: my-api-key
Responses
200

Badge holder list

400

Badge does not support holder listing

404

Badge not found

get/api/badges/{badge}/holders
Request samples

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
{}

Validates that a given user holds a badge

Validates that a given user holds a badge

Request
path Parameters
address
required
string

The user wallet address to validate

Example: 74565
badge
required
string

The badge code

Example: whale
Responses
200

Badge is held by user

404

Badge not held by user

get/api/badges/{badge}/validate/{address}
Request samples

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
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

badge
required
string

The specific badge code to retrieve rankings for

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

badge
string

The specific badge code to retrieve rankings for

Responses
200

Sponsor rankings

get/api/badges/rankings/sponsors
Request samples
Response samples
application/json
[
  • {
    }
]

Follower endpoints

Retrieves the following status of a domain

Retrieves the following status of a domain

Request
path Parameters
domain
required
string

The followee domain

query Parameters
follower-domain
required
string

The follower domain

Responses
200

Follow status

404

Domain not found

get/api/followers/{domain}/follow-status
Request samples
Response samples
application/json
{
  • "isFollowing": true
}

Follow a domain

Follow a domain

Request
path Parameters
domain
required
string

The domain name to follow

header Parameters
x-auth-domain
required
string

The domain to authorize. Should match the domain specified in the body

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
Request Body schema: application/json
domain
string

Name of domain to follow

Responses
200

Follow successful

404

Domain not found

post/api/followers/{domain}
Request samples
application/json
{
  • "domain": "follow.x"
}

Unfollows a domain

Unfollows a domain

Request
path Parameters
domain
required
string

The domain name to unfollow

header Parameters
x-auth-domain
required
string

The domain to authorize. Should match the domain specified in the body

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
Request Body schema: application/json
domain
string

Name of domain to follow

Responses
200

Unfollow successful

404

Domain not found

delete/api/followers/{domain}
Request samples
application/json
{
  • "domain": "follow.x"
}

Returns a list of followers or following for a domain

Returns a list of followers or following for a domain

Request
path Parameters
domain
required
string

The domain name to see followers for

query Parameters
relationship_type
string

The type of relationship to return (followers or following). Default is followers.

Enum: "followers" "following"
Example: relationship_type=followers, following
take
number

The number of followers to return. Default is 50. Max is 100.

cursor
number

The cursor to use for pagination

Responses
200

Follower list

404

Domain not found

get/api/followers/{domain}
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "relationship_type": "followers",
  • "domain": "string"
}

Retrieve follower rankings

Generates a list of domains ordered by number of followers

Request
path Parameters
count
number

The number of rankings to retrieve

Responses
200

Follower rankings

get/api/followers/rankings
Request samples
Response samples
application/json
[
  • {
    }
]

Message generator endpoints

Retrieves the message that must be signed to follow a domain

Retrieves the message that must be signed to follow a domain. 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 follow

Request Body schema: application/json
domain
string

Name of domain to follow

Responses
200

Message to be signed

404

Domain not found

post/api/followers/{domain}/signature
Request samples
application/json
{
  • "domain": "follow.x"
}
Response samples
application/json
{
  • "address": "string",
  • "message": "string",
  • "symbol": "string"
}

Retrieves the message that must be signed to unfollow a domain

Retrieves the message that must be signed to unfollow a domain. The message must be signed with the blockchain address private key and submitted using the DELETE call for verification.

Request
path Parameters
domain
required
string

The domain name to unfollow

Request Body schema: application/json
domain
string

Name of domain to follow

Responses
200

Message to be signed

400

Address not defined for domain

404

Domain not found

delete/api/followers/{domain}/signature
Request samples
application/json
{
  • "domain": "follow.x"
}
Response samples
application/json
{
  • "address": "string",
  • "message": "string",
  • "symbol": "string"
}

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 notification preferences

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
device
boolean

Indicates the user wishes to authorize and remember the device for profile management

Example: device=true
Responses
200

Message to be signed

404

Domain not found

get/api/user/{domain}/notifications/preferences/signature
Request samples
Response samples
application/json
{
  • "message": "string",
  • "headers": {
    }
}

Retrieves the message that must be signed to edit notification preferences

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
object (SerializedNotificationPost)
Responses
200

Message to be signed

404

Domain not found

post/api/user/{domain}/notifications/preferences/signature
Request samples
application/json
{
  • "WEB_NOTIFICATION": true,
  • "MOBILE_NOTIFICATION": true
}
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
device
boolean

Indicates the user wishes to authorize and remember the device for profile management

Example: device=true
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,
  • "imagePathPublic": true,
  • "coverPathPublic": true,
  • "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": {
    }
}

Ordinal endpoints

Retrieves an image for an Ordinal inscription

Retrieves an image for an Ordinal inscription based on the inscribed content. If the Ordinal is a .sats domain, a unique Bitcoin faces background image is rendered. More info on Bitcoin faces at https://bitcoinfaces.xyz.

Request
path Parameters
inscriptionId
required
string

The Ordinal inscription ID

Example: d80093a11ccb528c614bd7ab86c90ce212db12b8d155a20a761e20858c4baaddi0
Responses
200

An image representing the Ordinal inscription

404

Inscription ID not found

get/api/ordinals/preview/{inscriptionId}
Request samples

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": {},
  • "social": {
    },
  • "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": {
    }
}

Retrieves badges associated with a list of domains

Retrieves badge data associated with a list of requested domains.

Request
Request Body schema: application/json
domains
Array of strings

List of domains to query

Responses
200

Domain bulk badge data

404

Domain bulk data not found

post/api/public/badges-bulk
Request samples
application/json
{
  • "domains": [
    ]
}
Response samples
application/json
{}

Search endpoints

Retrieves reverse resolution details for an address

Retrieves reverse resolution details for an address

Request
path Parameters
address
required
string

Address to resolve

Example: 291
query Parameters
resolveOrder
string

Comma separated list of naming system resolution preferences

Example: resolveOrder=ud,ens,lens
Responses
200

Resolution successful

get/api/resolve/{address}
Request samples

Retrieves list of domains based on query

This route retrieves a list of domains that match the query

Request
query Parameters
name
string

Search by domain name

Example: name=matt
profile-required
boolean

Whether domains need have a profile configured

reverse-resolution-required
boolean

Whether domains need to have reverse resolution configured

Responses
200

Search result values

get/api/search
Request samples
Response samples

status liveness

status probe

This route can be used to determine if the application service is alive

Responses
200

application is alive

get/api/status
Request samples
Response samples
application/json
{
  • "status": {
    }
}

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": {
    },
  • "social": {
    },
  • "messaging": {
    },
  • "humanityCheck": {
    },
  • "cryptoVerifications": [
    ],
  • "records": {
    },
  • "storage": {
    },
  • "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,
  • "imagePathPublic": true,
  • "coverPathPublic": true,
  • "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": {
    },
  • "social": {
    },
  • "messaging": {
    },
  • "humanityCheck": {
    },
  • "cryptoVerifications": [
    ],
  • "records": {
    },
  • "storage": {
    },
  • "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
[
  • {
    }
]

Modify domain notification preferences

Modify notifications preferences related to the domain, such as mobile push notifications and email.

Request
path Parameters
domain
required
string

The domain name to query profile data

Request Body schema: application/json
object (SerializedNotificationPost)
Responses
200

Update successful

400

Request contained invalid parameters

404

Domain not found

post/api/user/{domain}/notifications/preferences
Request samples
application/json
{
  • "WEB_NOTIFICATION": true,
  • "MOBILE_NOTIFICATION": true
}

Get domain notification preferences

Get notifications preferences related to the domain, such as mobile push notifications and email.

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: b62348775da58077591e2d20506371e8d94a5a83031f34b9ac85845d3463e73b0f0a500875830785c093515806e354cda6c217acab0fce5245d662eff4105f5e1c
Responses
200

Update successful

400

Request contained invalid parameters

404

Domain not found

get/api/user/{domain}/notifications/preferences
Request samples