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 through the message generator endpoint
    • Request GET /api/user/{domain}/signature?device=true&expiry={timestamp}
      • Replace '{domain}' with desired domain
      • Replace '{expiry}' with desired Unix epoch timestamp
    • 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 desired endpoint that requires user authentication
    • Must include headers
      • x-auth-domain - Must equal the {domain} in context
      • x-auth-expiration - Must equal the {expiry} timestamp in the signed message
      • x-auth-signature - Must be set to the value of the user generated 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/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/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/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/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


 
badge
required
string
The specific badge code to retrieve rankings for


 
Responses 
200
Badge rankings


get/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/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/badges/rankings/sponsors
Request samples 
Response samples 
application/json
[
  • {
    }
]
Updates badges for a wallet address
Update specific badge visibility if provided in request body. If body has no elements, requests badge refresh for a wallet address. Authentication is required using domain owner signature.


Request 
path Parameters
address
required
string
The EVM address to retrieve wallet information


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


 
active
boolean
Indicates if badge is active


 
Responses 
200
List of badges


400
Invalid address


404
Address not found


409
Badges already recently collected


429
Too many collection requests


post/user/{address}/badges
Request samples 
application/json
[
  • {
    }
]
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/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/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/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/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/followers/rankings
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/public/{domain}/badges
Request samples 
Response samples 
application/json
{}
Retrieves social graph connections for a given domain
Retrieves recommended connections for a given domain, using an on-chain social graph.


Request 
path Parameters
domain
required
string
The domain name to query connections


 
Responses 
200
User connections


404
Domain not found


get/public/{domain}/connections
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/public/{domain}
Request samples 
Response samples 
application/json
{
  • "profile": {},
  • "social": {
    },
  • "humanityCheck": {
    },
  • "cryptoVerifications": [
    ],
  • "records": {
    },
  • "metadata": {
    },
  • "walletBalances": {
    },
  • "market": {
    },
  • "portfolio": {
    },
  • "socialAccounts": {
    },
  • "referralCode": "d83b1155f85f4fc",
  • "isListedForSale": true
}
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/public/{domain}/nfts
Request samples 
Response samples 
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}
Retrieves transaction data associated with blockchain accounts attached to a domain
Retrieves transaction data associated with requested domain. Paging is supported using the cursor query string parameter.


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


 
 Example:  symbols=ETH,MATIC
cursor
string
The paging cursor used in combination with the limit parameter


 
 Example:  cursor=desiredPage
Responses 
200
Transaction data


404
Domain not found


get/public/{domain}/transactions
Request samples 
Response samples 
application/json
[]
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/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
resolutionOrder
string
Comma separated list of naming system resolution preferences


 
 Example:  resolutionOrder=ud,ens,lens
Responses 
200
Resolution successful


get/resolve/{address}
Request samples 
Retrieves a list of all supported resolver keys
Retrieves a list of all supported resolver keys


Responses 
200
Retrieved resolver keys


get/resolve/keys
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/search
Request samples 
Response samples 
application/json
[]
Status
Status probe
This route can be used to determine if the application service is alive


Responses 
200
application is alive


get/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/user/{domain}/address/{symbol}
Request samples 
application/json
{
  • "message": "Unique message to sign",
  • "signature": "cd0dadab45baf9a06ce1279d1342ecc3f44845af"
}
Upload an XMTP or Push Protocol attachment
Upload an XMTP or Push Protocol attachment. Quota enforced per user. 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
object (SerializedDomainProfileImageData) 
 
Responses 
200
Public URL to access the uploaded attachment


400
Invalid attachment


404
Domain not found


409
User quota exceeded


post/user/{domain}/attachment
Request samples 
application/json
{
  • "attachment": {
    }
}
Response samples 
application/json
{}
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/user/{domain}
Request samples 
Response samples 
application/json
{
  • "profile": {
    },
  • "social": {
    },
  • "messaging": {
    },
  • "humanityCheck": {
    },
  • "cryptoVerifications": [
    ],
  • "records": {
    },
  • "storage": {
    },
  • "market": {
    },
  • "portfolio": {
    },
  • "walletBalances": {
    },
  • "socialAccounts": {
    },
  • "referralCode": "d83b1155f85f4fc",
  • "isListedForSale": true
}
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


 
publicDomainSellerEmail
string
Public domain seller email visible to anyone


 
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/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",
  • "publicDomainSellerEmail": "seller@gmail.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": {
    },
  • "social": {
    },
  • "messaging": {
    },
  • "humanityCheck": {
    },
  • "cryptoVerifications": [
    ],
  • "records": {
    },
  • "storage": {
    },
  • "market": {
    },
  • "portfolio": {
    },
  • "walletBalances": {
    },
  • "socialAccounts": {
    },
  • "referralCode": "d83b1155f85f4fc",
  • "isListedForSale": true
}
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/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/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/user/{domain}/notifications/preferences
Request samples 
Confirm an update to a domain's on-chain records
The POST call can be used to complete the process of modifying a domain's on-chain records by submitting a signed transaction hash to confirm an operation. Authentication is required using domain owner signature.


Request 
path Parameters
domain
required
string
The domain name to update on-chain records


 
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
operationId
string
The operation ID returned from a request to update domain records


 
dependencyId
string
The dependency ID returned from a request to update domain records


 
signature
string
The signature created by signing the domain record transaction hash with domain owner's private key


 
txHash
string
A completed transaction hash that specifies the operation to confirm


 
Responses 
200
Successful confirmation of domain record update. The domain records will be updated on the blockchain.


404
Domain not found


post/user/{domain}/records/confirm
Request samples 
application/json
{
  • "operationId": 1234,
  • "dependencyId": 5678,
  • "signature": 4660,
  • "txHash": 4660
}
Response samples 
application/json
{
  • "type": "unstoppabledomains.com/partner.v3.OperationType",
  • "operation": {
    }
}
Retrieves pending on-chain record management operations
Retrieves a list of pending on-chain record operations for this domain. Authentication is required using domain owner signature.


Request 
path Parameters
domain
required
string
The domain name to retrieve pending operations


 
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
Responses 
200
List of pending on-chain operations


400
Request contained invalid parameters


404
Domain not found


get/user/{domain}/records/manage
Request samples 
Response samples 
application/json
{
  • "type": "unstoppabledomains.com/partner.v3.OperationType",
  • "items": [
    ]
}
Request to update a domain's on-chain records
The POST call can be used to start the process of modifying a domain's on-chain records. Authentication is required using domain owner signature.


Request 
path Parameters
domain
required
string
The domain name to update on-chain records


 
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
address
string
The wallet address


 
primaryDomain
boolean
Set this domain to the wallet's primary identity


 
transferToAddress
string
Transfer the domain to the specified address


 
clearRecords
string
Clear all records upon transfer


 
object
Key value pairs of records to be updated


 
Responses 
200
Successful request of domain record update. The transaction hash must be signed and submitted to confirm the record update.


404
Domain not found


post/user/{domain}/records/manage
Request samples 
application/json
{
  • "address": 4660,
  • "primaryDomain": true,
  • "transferToAddress": 291,
  • "clearRecords": true,
  • "records": {
    }
}
Response samples 
application/json
{
  • "type": "unstoppabledomains.com/partner.v3.OperationType",
  • "operation": {
    }
}
Edit domain profile data in bulk
The POST call can be used to create new domain profiles or make updates to existing profiles. All domains in the bulk update list must belong to the same wallet address. Authentication is required using the domain owner signature from one of the domains in the bulk update list.


Request 
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
domains
Array of strings
 
object (SerializedDomainProfilePost) 
 
Responses 
200
Domain profile


400
Invalid request


403
Bulk update not authorized


404
Domain not found


post/user/domains
Request samples 
application/json
{
  • "domains": [
    ],
  • "profile": {
    }
}
Response samples 
application/json
{
  • "success": true,
  • "domains": [
    ]
}
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/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 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/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


 
publicDomainSellerEmail
string
Public domain seller email visible to anyone


 
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/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",
  • "publicDomainSellerEmail": "seller@gmail.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": {
    }
}
Wallet data endpoints
Returns a list of domains owned by a user
Returns a list of domains owned by a user


Request 
path Parameters
address
required
string
The owner address to query


 
query Parameters
take
number
The number of domains to return. Default is 50. Max is 100.


 
cursor
string
The cursor to use for pagination


 
Responses 
200
List of domains


404
Address not found


get/user/{address}/domains
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "relationship_type": "followers",
  • "domain": "string"
}
Retrieves NFT data for a given address
Retrieves NFT data for a given address. Authentication with an API key is required.


Request 
path Parameters
address
required
string
The EVM address to retrieve wallet information


 
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
header Parameters
Authorization
required
string
The JWT access token that authorizes the request


 
 Example:  my-jwt-access-token
Responses 
200
Paginated NFT data


400
Invalid address


404
Address not found


get/user/{address}/nfts
Request samples 
Response samples 
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}
Retrieves EVM wallet transactions for a given address
Retrieves EVM wallet transactions for a given address. Authentication with an API key is required.


Request 
path Parameters
address
required
string
The EVM address to retrieve transaction information


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


 
 Example:  symbols=ETH,MATIC
cursor
string
The paging cursor used in combination with the limit parameter


 
 Example:  cursor=desiredPage
forceRefresh
number
Include a timestamp to indicate that caching should be avoided when rendering the response


 
 Example:  forceRefresh=1707491939
header Parameters
Authorization
required
string
The JWT access token that authorizes the request


 
 Example:  my-jwt-access-token
Responses 
200
Transaction data


400
Invalid address


404
Address not found


get/user/{address}/transactions
Request samples 
Response samples 
application/json
[]
RPC proxy
RPC proxy. Authentication with an API key is required.


Request 
path Parameters
address
required
string
The address to retrieve wallet information


 
header Parameters
Authorization
required
string
The JWT access token that authorizes the request


 
 Example:  my-jwt-access-token
Responses 
200
RPC specific success response


403
Not authorized


post/user/{address}/wallet/rpc
Request samples 
Simulate a wallet transaction
Simulate a wallet transaction. Authentication with an API key is required.


Request 
path Parameters
address
required
string
The address to retrieve wallet information


 
header Parameters
Authorization
required
string
The JWT access token that authorizes the request


 
 Example:  my-jwt-access-token
Request Body schema: application/json
serializedTx
string
Serialized transaction request


 
Responses 
200
Simulated transaction results


400
Invalid address


404
Address not found


post/user/{address}/wallet/simulate
Request samples 
application/json
{
  • "serializedTx": 291
}
Response samples 
application/json
[
  • {
    }
]
Retrieves EVM wallet data for a given address
Retrieves EVM wallet data for a given address. Authentication with an API key is required.


Request 
path Parameters
address
required
string
The EVM address to retrieve wallet information


 
query Parameters
verbose
boolean
 
forceRefresh
number
Include a timestamp to indicate that caching should be avoided when rendering the response


 
 Example:  forceRefresh=1707491939
walletFields
string
Comma separated list of wallet data fields to retrieve. Defaults to native,nft,token,tx.


 
 Example:  walletFields=native,nft,stats,token,tx
header Parameters
Authorization
required
string
The JWT access token that authorizes the request


 
 Example:  my-jwt-access-token
Responses 
200
Wallet data


400
Invalid address


404
Address not found


get/user/{address}/wallets
Request samples 
Response samples 
application/json
[
  • {
    }
]
Market data endpoints
Retrieves detailed market data about the domain
Retrieves detailed market data about the domain. API key authentication is required.


Request 
path Parameters
domain
required
string
The domain name to retrieve market data


 
header Parameters
x-api-key
required
string
API key to authorize the request


 
 Example:  my-api-key
Responses 
200
Domain marketplace data


400
Request contained invalid parameters


404
Domain not found


get/user/{domain}/market-data
Request samples 
Response samples 
application/json
{
  • "primary": {
    },
  • "secondary": [
    ]
}
Wallet management endpoints
Retrieves account status for an account specified by an identifier
Retrieves account status for an account specified by an identifier


Request 
path Parameters
identifier
required
string
An account identifier


 
Responses 
200
Account status


404
Account not found


post/user/{identifier}/wallet/account
Request samples 
Response samples 
application/json
{
  • "emailAddress": "myname@email.com",
  • "active": true,
  • "clock": 1722600216741
}
Request to synchronize wallet addresses with tokenized identity
Request to synchronize wallet addresses with tokenized identity


Request 
path Parameters
address
required
string
Any blockchain address associated with the wallet


 
header Parameters
Authorization
required
string
The JWT access token that authorizes the request


 
 Example:  my-jwt-access-token
Responses 
200
Successful request to tokenize the identity


post/user/{address}/wallet/identity
Request samples 
Response samples 
application/json
{
  • "account": "user123xyz",
  • "domain": "22aba33b5d41558729dd176c8727239577562ccd1a939ca8931957b352c8342d.crypto",
  • "status": "ready"
}
Retrieves on-chain record management status
Retrieves the domain management registration status. The owner wallet must be registered to manage on-chain records. Authentication is required using domain owner signature.


Request 
path Parameters
domain
required
string
The domain name to retrieve account registrations state


 
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
Responses 
200
Wallet registration state


400
Request contained invalid parameters


404
Domain not found


get/user/{domain}/wallet
Request samples 
Response samples 
application/json
{
  • "type": "unstoppabledomains.com/partner.v3.WalletVerificationResult",
  • "address": 4660,
  • "message": "Sign this message with wallet private key"
}
Register for on-chain record management
The POST call can be used to enable a wallet to manage a domain's on-chain records. Authentication is required using domain owner signature.


Request 
path Parameters
domain
required
string
The domain name to register for on-chain record management


 
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
address
string
The wallet address


 
message
string
Message to sign


 
signature
string
The signature created by signing the message with domain owner's private key


 
Responses 
200
Wallet registration state


404
Domain not found


post/user/{domain}/wallet
Request samples 
application/json
{
  • "address": 4660,
  • "message": "Sign this message with wallet private key",
  • "signature": 4660
}
Response samples 
application/json
{
  • "type": "unstoppabledomains.com/partner.v3.WalletVerificationResult",
  • "address": 4660,
  • "message": "Sign this message with wallet private key"
}
Sends an Unstoppable Lite Wallet invitation to a specified contact
Sends an Unstoppable Lite Wallet invitation to a specified contact


Request 
path Parameters
address
required
string
A wallet address associated with the invitation sender account


 
Request Body schema: application/json
emailAddress
string
Email address to register


 
otp
string
A one time code to verify ownership of an email address


 
password
string
Password to use when creating new wallet


 
Responses 
200
Account status


404
Sender account not found


409
Invited account already exists


post/user/{address}/wallet/invite
Request samples 
application/json
{
  • "emailAddress": "user@email.com",
  • "otp": "0000-1111-2222",
  • "password": "secret-password"
}
Response samples 
application/json
{
  • "emailAddress": "myname@email.com",
  • "active": true,
  • "clock": 1722600216741
}
An asynchronous request to claim a wallet to self custody
An asynchronous request to claim a wallet to self custody, using a server generated secret.


Request 
header Parameters
x-api-key
required
string
The server generated secret required to authorize the request. This value should be the same one used returned in the POST response when the wallet was created.


 
 Example:  user-provided-secret
Request Body schema: application/json
emailAddress
string
Email address to register


 
otp
string
A one time code to verify ownership of an email address


 
password
string
Password to use when creating new wallet


 
Responses 
200
Successfully requested to claim the wallet to self custody. The status will of the response will always be PROCESSING. Must use the corresponding GET endpoint to check status to determine when claiming is complete.


403
Not authorized


409
Wallet already claimed or email already in use


429
Too many attempts


post/user/wallet/claim
Request samples 
application/json
{
  • "emailAddress": "user@email.com",
  • "otp": "0000-1111-2222",
  • "password": "secret-password"
}
Response samples 
application/json
{
  • "secret": "server-generated-secret",
  • "state": "SELF_CUSTODY",
  • "status": "COMPLETE",
  • "addresses": {
    }
}
Get status of a wallet claim to self custody
Get status of a wallet claim to self custody.


Request 
header Parameters
x-api-key
required
string
The server generated secret required to authorize the request. This value should be the same one used returned in the POST response when the wallet was created.


 
 Example:  user-provided-secret
Responses 
200
Successfully retrieved self custody wallet status


403
Not authorized


404
Not found


429
Too many attempts


get/user/wallet/claim
Request samples 
Response samples 
application/json
{
  • "secret": "server-generated-secret",
  • "state": "SELF_CUSTODY",
  • "status": "COMPLETE",
  • "addresses": {
    }
}
Request a one time code required to setup a new walletDeprecated
If a wallet does not already exist, a one time code will created and sent to the provided email address.


Request 
Request Body schema: application/json
emailAddress
string
Email address to register


 
otp
string
A one time code to verify ownership of an email address


 
password
string
Password to use when creating new wallet


 
Responses 
200
Successfully sent one time code to verify email address


403
Not authorized


409
Account already exists


429
Too many attempts


post/user/wallet
Request samples 
application/json
{
  • "emailAddress": "user@email.com",
  • "otp": "0000-1111-2222",
  • "password": "secret-password"
}
Response samples 
application/json
{
  • "emailAddress": "myname@email.com",
  • "active": true,
  • "clock": 1722600216741
}
An asynchronous request to create a wallet
An asynchronous request to create a wallet. The resulting wallet will be custodial, but the user can claim custody at a later time using the server generated secret provided in the response.


Request 
header Parameters
x-api-key
required
string
Required to authorize the request for a new wallet


 
 Example:  wallet-creation-secret
Responses 
200
Successfully requested to create a custody wallet. The status will of the response will always be PROCESSING with an empty list of addresses. Must use the corresponding GET endpoint to check status and address metadata, using the provided server generated secret as authentication.


403
Not authorized


409
Account already exists


429
Too many attempts


post/user/wallet/launch
Request samples 
Response samples 
application/json
{
  • "secret": "server-generated-secret",
  • "state": "SELF_CUSTODY",
  • "status": "COMPLETE",
  • "addresses": {
    }
}
Get status of a wallet
Get status of a wallet associated with a server generated secret. The secret is provided to the client at wallet create time.


Request 
header Parameters
x-api-key
required
string
The server generated secret required to authorize the request. This value should be the same one used returned in the POST response when the wallet was created.


 
 Example:  user-provided-secret
Responses 
200
Successfully retrieved custody wallet status


403
Not authorized


404
Not found


429
Too many attempts


get/user/wallet/launch
Request samples 
Response samples 
application/json
{
  • "secret": "server-generated-secret",
  • "state": "SELF_CUSTODY",
  • "status": "COMPLETE",
  • "addresses": {
    }
}
Create a wallet with a verified email addressDeprecated
The one time code generated with the associated POST request must be provided in the request body.


Request 
Request Body schema: application/json
emailAddress
string
Email address to register


 
otp
string
A one time code to verify ownership of an email address


 
password
string
Password to use when creating new wallet


 
Responses 
200
Successfully submitted request to create wallet


403
Not authorized


409
Account already exists


429
Too many attempts


post/user/wallet/register
Request samples 
application/json
{
  • "emailAddress": "user@email.com",
  • "otp": "0000-1111-2222",
  • "password": "secret-password"
}
Response samples 
application/json
{
  • "emailAddress": "myname@email.com",
  • "active": true,
  • "clock": 1722600216741
}
Identity management endpoints
Request tokenization status of a user identity
Request tokenization status of a user identity


Request 
header Parameters
Authorization
required
string
The JWT access token that authorizes the request


 
 Example:  my-jwt-access-token
x-auth-subject
required
string
The user identity associated with request for tokenization


 
 Example:  user123xyz
Responses 
200
Successful request to tokenize the identity


get/user/identity
Request samples 
Response samples 
application/json
{
  • "account": "user123xyz",
  • "domain": "22aba33b5d41558729dd176c8727239577562ccd1a939ca8931957b352c8342d.crypto",
  • "status": "ready"
}
Request tokenization of user identity
Request tokenization of user identity


Request 
header Parameters
Authorization
required
string
The JWT access token that authorizes the request


 
 Example:  my-jwt-access-token
x-auth-subject
required
string
The user identity associated with request for tokenization


 
 Example:  user123xyz
Responses 
200
Successful request to tokenize the identity


400
Invalid request


409
Identity already tokenized


post/user/identity
Request samples 
Response samples 
application/json
{
  • "account": "user123xyz",
  • "domain": "22aba33b5d41558729dd176c8727239577562ccd1a939ca8931957b352c8342d.crypto",
  • "status": "ready"
}
Request a one time code to verify access to an account
Request a one time code to verify access to an account


Request 
Request Body schema: application/json
account
string
Identifier of the account


 
otp
string
One time code to validate the account


 
type
string
Type of account


 
Responses 
200
One time password successfully sent


400
Invalid request


post/user/otp
Request samples 
application/json
{
  • "account": "user@email.com",
  • "otp": 123456,
  • "type": "email"
}
Verify a one time code and receive a JWT access token
Verify a one time code and receive a JWT access token


Request 
Request Body schema: application/json
account
string
Identifier of the account


 
otp
string
One time code to validate the account


 
type
string
Type of account


 
Responses 
200
One time password successfully verified


400
Invalid request


post/user/otp/verify
Request samples 
application/json
{
  • "account": "user@email.com",
  • "otp": 123456,
  • "type": "email"
}
Response samples 
application/json
{
  • "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXRhIjp7ImRvbWFpbiI6InRlc3QuZG9tYWluIn0sIm5vbmNlIjoiVERDOUZEIiwiaWF0IjoxNzE4MjgyNDQzLCJpc3MiOiJ1YXV0aCIsInN1YiI6InRlc3QxLmRvbWFpbiJ9.tXuHUczDzkTqmwkUhC2I16nWjiHnFOKRBsnzrMWOctk"
}