Skip to content
Profile/
/
Retrieve badge rankings

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
Languages
Servers
Production
https://api.unstoppabledomains.com/profile/
Staging
https://api.ud-staging.com/profile/

Badge endpoints

Operations

Retrieves holders of the badge

Request

Retrieves a list of addresses that hold the badge

Path
badgestringrequired

The badge code

Example: whale
Headers
x-api-keystringrequired

API key required to authenticate the request

Example: my-api-key
curl -i -X GET \
  https://api.unstoppabledomains.com/profile/badges/whale/holders \
  -H 'x-api-key: my-api-key'

Responses

Badge holder list

Retrieves details about a badge

Request

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

Path
badgestringrequired

The badge code

Example: whale
curl -i -X GET \
  https://api.unstoppabledomains.com/profile/badges/whale

Responses

Badge details

Bodyapplication/json
badgeobject(SerializedBadge)
sponsorshipobject(SerializedBadgeSponsorship)
usageobject(SerializedBadgeUsage)

High level usage details about a specific badge

Response
application/json
{
  "badge": {
    "name": "World of Women",
    "code": "WoWHolder",
    "active": true,
    "logo": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/ud-logo.svg",
    "linkUrl": "https://badge.io/info",
    "videoUrl": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/unstoppabledomains.mp4",
    "coverImage": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/bayc-cover-image.png",
    "type": "default",
    "count": 3,
    "description": "Holds World of Women NFT.",
    "gallery": { … },
    "marketplace": { … }
  },
  "sponsorship": {
    "max": 10,
    "count": 5,
    "latest": "latest.crypto",
    "authorizedAddresses": [ … ],
    "domains": [ … ]
  },
  "usage": {
    "holders": 10000,
    "domains": 10000,
    "featured": [ … ],
    "rank": 1
  }
}

Validates that a given user holds a badge

Request

Validates that a given user holds a badge

Path
addressstringrequired

The user wallet address to validate

Example: 74565
badgestringrequired

The badge code

Example: whale
curl -i -X GET \
  https://api.unstoppabledomains.com/profile/badges/whale/validate/74565

Responses

Badge is held by user

Generates a badge based on a provided marketplace link

Request

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.

Bodyapplication/jsonrequired
linkstring

Marketplace link to the NFT collection you want to claim a badge (e.g. OpenSea, MagicEden, Zuse.market, etc)

Example: "https://opensea.io/collection/unstoppable-domains-polygon"
curl -i -X POST \
  https://api.unstoppabledomains.com/profile/badges/claim \
  -H 'Content-Type: application/json' \
  -d '{
    "link": "https://opensea.io/collection/unstoppable-domains-polygon"
  }'

Responses

Badge pending payment

Bodyapplication/json
namestring

Name of the Badge

Example: "World of Women"
codestring

Unique badge code

Example: "WoWHolder"
activeboolean

Indicates that the badge is active

Example: true
logostring

Badge logo, could be url or emoji

Example: "https://storage.googleapis.com/unstoppable-client-assets/images/badges/ud-logo.svg"
linkUrlstring

Link to external website

Example: "https://badge.io/info"
videoUrlstring

Link to video

Example: "https://storage.googleapis.com/unstoppable-client-assets/images/badges/unstoppabledomains.mp4"
coverImagestring

Link to cover image

Example: "https://storage.googleapis.com/unstoppable-client-assets/images/badges/bayc-cover-image.png"
typestring

Type of badge

Example: "default"
countnumber

Number of items associated with the badge

Example: 3
descriptionstring

Description of the badge

Example: "Holds World of Women NFT."
galleryobject(SerializedPartnerTokenGallery)
marketplaceobject(SerializedMarketplaceData)
Response
application/json
{
  "name": "World of Women",
  "code": "WoWHolder",
  "active": true,
  "logo": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/ud-logo.svg",
  "linkUrl": "https://badge.io/info",
  "videoUrl": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/unstoppabledomains.mp4",
  "coverImage": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/bayc-cover-image.png",
  "type": "default",
  "count": 3,
  "description": "Holds World of Women NFT.",
  "gallery": {
    "enabled": true,
    "featured": [ … ],
    "tier": 1
  },
  "marketplace": {
    "listings": [ … ],
    "avgPrice": { … },
    "floorPrice": { … },
    "supply": 10000,
    "holders": 1000,
    "sales": 3,
    "volume": 3
  }
}

Retrieve badge rankings by domain

Request

Generates a list of domains ordered by largest badge collection

Path
countnumber

The number of rankings to retrieve

communityOnlyboolean

Include only community sponsored badges

badgestringrequired

The specific badge code to retrieve rankings for

curl -i -X GET \
  https://api.unstoppabledomains.com/profile/badges/rankings/domains

Responses

Badge rankings

Bodyapplication/jsonArray [
domainstring
Example: "matt.crypto"
ranknumber
Example: 1
countnumber
Example: 100
]
Response
application/json
[
  {
    "domain": "matt.crypto",
    "rank": 1,
    "count": 100
  }
]

Retrieve badge rankings

Request

Generates a list of badges ordered by number of holders

Path
countnumber

The number of rankings to retrieve

communityOnlyboolean

Include only community sponsored badges

curl -i -X GET \
  https://api.unstoppabledomains.com/profile/badges/rankings

Responses

Badge rankings

Bodyapplication/jsonArray [
badgeobject(SerializedBadge)
sponsorshipobject(SerializedBadgeSponsorship)
usageobject(SerializedBadgeUsage)

High level usage details about a specific badge

]
Response
application/json
[
  {
    "badge": { … },
    "sponsorship": { … },
    "usage": { … }
  }
]

Retrieve badge rankings by sponsor

Request

Generates a list of sponsors ordered by largest number of sponsored badges

Path
countnumber

The number of rankings to retrieve

badgestring

The specific badge code to retrieve rankings for

curl -i -X GET \
  https://api.unstoppabledomains.com/profile/badges/rankings/sponsors

Responses

Sponsor rankings

Bodyapplication/jsonArray [
domainstring
Example: "matt.crypto"
ranknumber
Example: 1
countnumber
Example: 100
]
Response
application/json
[
  {
    "domain": "matt.crypto",
    "rank": 1,
    "count": 100
  }
]

Updates badges for a wallet address

Request

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.

Path
addressstringrequired

The EVM address to retrieve wallet information

Headers
x-auth-domainstringrequired

The domain to authorize

Example: mydomain.tld
x-auth-expiresstringrequired

The expiration time of the signature

Example: 1765522015090
x-auth-signaturestringrequired

The signature generating using domain owner private key

Example: b62348775da58077591e2d20506371e8d94a5a83031f34b9ac85845d3463e73b0f0a500875830785c093515806e354cda6c217acab0fce5245d662eff4105f5e1c
Bodyapplication/jsonrequiredArray [
codestring

Badge code

Example: "badge1"
activeboolean

Indicates if badge is active

Example: true
]
curl -i -X POST \
  'https://api.unstoppabledomains.com/profile/user/{address}/badges' \
  -H 'Content-Type: application/json' \
  -H 'x-auth-domain: mydomain.tld' \
  -H 'x-auth-expires: 1765522015090' \
  -H 'x-auth-signature: b62348775da58077591e2d20506371e8d94a5a83031f34b9ac85845d3463e73b0f0a500875830785c093515806e354cda6c217acab0fce5245d662eff4105f5e1c' \
  -d '[
    {
      "code": "badge1",
      "active": true
    }
  ]'

Responses

List of badges

Bodyapplication/jsonArray [
namestring

Name of the Badge

Example: "World of Women"
codestring

Unique badge code

Example: "WoWHolder"
activeboolean

Indicates that the badge is active

Example: true
logostring

Badge logo, could be url or emoji

Example: "https://storage.googleapis.com/unstoppable-client-assets/images/badges/ud-logo.svg"
linkUrlstring

Link to external website

Example: "https://badge.io/info"
videoUrlstring

Link to video

Example: "https://storage.googleapis.com/unstoppable-client-assets/images/badges/unstoppabledomains.mp4"
coverImagestring

Link to cover image

Example: "https://storage.googleapis.com/unstoppable-client-assets/images/badges/bayc-cover-image.png"
typestring

Type of badge

Example: "default"
countnumber

Number of items associated with the badge

Example: 3
descriptionstring

Description of the badge

Example: "Holds World of Women NFT."
galleryobject(SerializedPartnerTokenGallery)
marketplaceobject(SerializedMarketplaceData)
]
Response
application/json
[
  {
    "name": "World of Women",
    "code": "WoWHolder",
    "active": true,
    "logo": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/ud-logo.svg",
    "linkUrl": "https://badge.io/info",
    "videoUrl": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/unstoppabledomains.mp4",
    "coverImage": "https://storage.googleapis.com/unstoppable-client-assets/images/badges/bayc-cover-image.png",
    "type": "default",
    "count": 3,
    "description": "Holds World of Women NFT.",
    "gallery": { … },
    "marketplace": { … }
  }
]

Follower endpoints

Operations

Profile data endpoints

Operations

Swap endpoints

Operations

Search endpoints

Operations

Status

Operations

Profile management endpoints

Operations

Message generator endpoints

Operations

Wallet data endpoints

Operations

Market data endpoints

Operations

Wallet management endpoints

Operations

Solana wallet endpoints

Operations

Wallet storage endpoints

Operations

Identity management endpoints

Operations