Claim Free Domains

Unstoppable Domains offers free domain minting to Partners based on specified criteria. Authorized Partners can use the following API endpoints: Get Free Domains Suggestions, Reserve Free Domain Name, and Claim Free Domain.

The diagram below illustrates the general process between a Partner and Unstoppable Domains during the process of minting a free domain.

Step 1: Retrieve Your Reseller ID and Secret API Token

To access your ResellerID and Secret API Token, you must navigate to your Sandbox or Production Partner dashboard. The ResellerID is used to identify the requests as coming from a Partner, while the Secret API Token is used for authentication to ensure that only authorized Partners can access the API.

Step 2: Setup Criteria for Free Domains

Partners work with the Unstoppable Domains team to establish the "allowed free TLDs" and "allowed free tiers" criteria for their account.

Then, the "allowed free TLDs" and "allowed free tiers" list is assigned to the Partner's account, and they can only mint a free domain if it matches the tier and has an appropriate domain ending.

The table below shows how the pricing tiers are structured at Unstoppable Domains. Most free domains will be a Tier 7 or Tier 8 domain with a combination of letters and numbers.

Step 3: Prepare Your Order Security

Unstoppable Domains uses Fingerprint to verify free domain orders and catch sophisticated fraudsters. See the Fingerprint Docs for integration guides and how to generate a Fingerprint Visitor ID for your users.

Integrate Fingerprint Key Generation

Unstoppable Domains provided an API endpoint to fetch Fingerprint public keys, which are needed for generating the Visitor ID. Send a POST request to the Get Fingerprint Public Key endpoint. Here is the URL for our API environments:

Sandbox Environment:

https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/security/fingerprintjs/keys

Production Environment:

https://unstoppabledomains.com/api/v2/resellers/{PARTNER_RESELLERID}/security/fingerprintjs/keys

Here's a sample response from the Get Fingerprint Public Key endpoint:

{
  "key": "qwerty12345"
}

Integrate Fingerprint Subdomain

Unstoppable Domains has a dedicated subdomain for Fingerprint verification to improve integration and user identification. You need to set the endpoint property in your Fingerprint initialization to our subdomain.

Sandbox Environment:

https://fp.ud-sandbox.com

Production Environment:

https://fp.unstoppabledomains.com

Here's a sample code snippet:

// Initialize the agent at application startup.
const fpPromise = import("https://fpcdn.io/v3/{FINGERPRINT_API_KEY}").then(
  (FingerprintJS) =>
    FingerprintJS.load({
      endpoint: "https://fp.unstoppabledomains.com",
    })
);

Tag Your Fingerprint Request

Unstoppable Domains requires you to tag your requests with the linkedId property and your ResellerID when generating the Visitor ID for your users. Here's a sample code snippet:

// Get the visitor identifier when you need it.
fpPromise
  .then((fp) => fp.get({ linkedId: "{PARTNER_RESELLERID}" }))
  .then((result) => console.log(result.visitorId));

The code snippet below shows how to completely integrate Fingerprint verification into your free domain flow:

<script>
  // Initialize the agent at application startup.
  const fpPromise = import('https://fpcdn.io/v3/{FINGERPRINT_API_KEY}')
    .then(FingerprintJS => FingerprintJS.load({
      endpoint: 'https://fp.unstoppabledomains.com'
    }));

  // Get the visitor identifier when you need it.
  fpPromise
    .then(fp => fp.get({linkedId: '{PARTNER_RESELLERID}'}))
    .then(result => console.log(result.visitorId));
</script>

Here's a sample response from the Fingerprint integration:

{
  "requestId": "1669648408882.1kcr2m",
  "confidence": {
    "score": 0.999170944804056
  },
  "meta": {
    "version": "v1.1.971+673281e1"
  },
  "visitorFound": true,
  "visitorId": "qwerty12345"
}

Step 4: Prepare Request Body

When making an order, the body must contain information about your domain order in JSON format with the following structure:

{
  "payment": {
    "method": "free"
  },
  "security": [
    {
      "type": "fingerprintjs",
      "identifier": string // Fingerprint Visitor ID of the user minting the domain
    }
  ],
  "domains": [
    {
      "name": string, // domain name you are minting
      "ownerAddress": string, // wallet address to mint the domain to
      "email": string, // UD email address to link the domain to
      "phone": string, // user's phone number
      "resolution": object, // predefined records to mint the domain with
      "resellerIdentityKey": string // domain reservation ID
    }
  ]
}

• payment : A key-value dictionary with payment information about the order:
  • method : (string) The payment method the API should create. The value should be "free" for free domains.
• security : (array) An array with information about the order security:
  • type : The order security method. The value should be "fingerprintjs" for Fingerprint verification.
  • identifier : The Fingerprint Visitor ID of the user minting the domain.
• domains : (array) An array with information about the domains you want to purchase:
  • name : The domain name you want to purchase. This parameter is required.
  • ownerAddress : The wallet address the domain should be minted to. This parameter is required.
  • email : The email address the domain should be linked to after purchase. The user can mint the domain from their UD dashboard later. This parameter is required.
  • phone : The phone number of the user minting the free domain. This parameter is optional.
  • resolution : A key-value pair of resolution records to configure for the domain after minting. See the Records Reference guide for supported key values. This parameter is optional.
  • resellerIdentityKey : The domain reservation ID. This parameter is required if you reserved the domain before minting.

Step 5: Prepare Authorization Headers

The Partner API uses bearer tokens to authorize requests with the Secret API Token from your Partner credentials.

Step 6: Use the Orders Endpoint

Send a POST request with the authorization headers and request body you have prepared to the Buy a Domain or Claim Free Domain endpoint. Here is the URL for our API environments:

Sandbox Environment:

https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/orders/

Production Environment:

https://unstoppabledomains.com/api/v2/resellers/{PARTNER_RESELLERID}/orders/

Example

Here is an example request to mint a free domain with the following details:

curl --location --request POST 'https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/orders/' \
--header 'Authorization: Bearer {SECRET_API_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "payment": {
    "method": "free"
  },
  "security": [
    {
      "type": "fingerprintjs",
      "identifier": "qwerty12345"
    }
  ],
  "domains": [
    {
      "name": "partner-test-67687986466875.wallet",
      "ownerAddress": "0x6EC0DEeD30605Bcd19342f3c30201DB263291589",
      "email": "sandbox-test@unstoppabledomains.com",
      "resolution": {
          "crypto.ETH.address": "0x6EC0DEeD30605Bcd19342f3c30201DB263291589",
          "crypto.BTC.address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
      }
    }
  ]
}'

{
  "orderNumber": "78023",
  "total": 0,
  "payment": {
    "method": "free"
  },
  "items": [
    {
      "domain": {
        "id": 966210,
        "name": "partner-test-67687986466875.wallet",
        "ownerAddress": null,
        "resolver": null,
        "resolution": {},
        "blockchain": "MATIC",
        "registryAddress": "0x2a93c52e7b6e7054870758e15a1446e769edfb93",
        "networkId": 80001,
        "freeToClaim": true,
        "node": "0xeb55b00b50af99d760b002c6d855532658c332d059dcd69eb167fec5ec97d0fa"
      },
      "mintingTransaction": {
        "id": 44958,
        "type": "MaticTx",
        "operation": "MintDomain",
        "statusGroup": "Pending",
        "hash": null,
        "blockchain": "MATIC",
        "blockExplorerUrl": null
      }
    }
  ]
}

Considerations

The following considerations apply to minting free domains:

• The Reseller ID will be allowed to provide specified domain endings for free.
• If the Reseller ID doesn't have an allowance to provide free domains, then they will not be permitted to mint free domains.
• The domain is available for sale (e.g., it's not restricted, protected, trademarked, claimed, etc.)
• The domain does not have a custom price set.
• It has 8+ characters, at least one letter, and one number.
• If a wallet or email already has a free domain, then a second free domain is not permitted.
• The Fingerprint Visitor ID provided must be generated within the past 30 seconds and have a confidence score of at least 90%.

Reserve Free Domain Name

The Partner API offers an endpoint that allows Partners to reserve free and available domains so they'll be minted at a later date. Reserved domains become unavailable to be claimed and minted by anyone except the Partner that reserved it for 168 hours (7 days).

Step 1: Retrieve Your Reseller ID and Secret API Token

To access your ResellerID and Secret API Token, you must navigate to your Sandbox or Production Partner dashboard. The ResellerID is used to identify the requests as coming from a Partner, while the Secret API Token is used for authentication to ensure that only authorized Partners can access the API.

Step 2: Prepare Request Body

When reserving a domain, the body must contain information about your reservation in JSON format with the following structure:

{
  "resellerIdentityKey": string // unique domain reservation identifier
}

To reserve a free and available domain, the partner must provide a unique user identifier (this could be an email or some other internal user identifier). The same identifier must be provided in the resellerIdentityKey parameter when minting the domain (using the Buy a Domain or Claim Free Domain endpoint).

Step 3: Prepare Authorization Headers

The Partner API uses bearer tokens to authorize requests with the Secret API Token from your Partner credentials.

Step 4: Use the Reserve Free Domain Name Endpoint

Send a POST request with the authorization headers and request body you have prepared to check to the Reserve Free Domain Name endpoint. Here is the URL for our API environments:

Sandbox Environment:

https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/domains/{DOMAIN_NAME}/reserve/

Production Environment:

https://unstoppabledomains.com/api/v2/resellers/{PARTNER_RESELLERID}/domains/{DOMAIN_NAME}/reserve/

Example

Here is an example request to reserve a domain name with the following parameters:

curl --location --request POST 'https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/domains/partner-test-67687986466871.crypto/reserve/' \
--header 'Authorization: Bearer {SECRET_API_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "resellerIdentityKey": "test-reservation-id"
}'

Minting a Reserved Domain Name

To mint a domain you have reserved, you need to fill the resellerIdentityKey request body parameter in the Buy a Domain or Claim Free Domain endpoint with the domain reservation identifier.

curl --location --request POST 'https://api.ud-sandbox.com/api/v2/resellers/{PARTNER_RESELLERID}/orders/' \
--header 'Authorization: Bearer {SECRET_API_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "payment": {
    "method": "free"
  },
  "security": "{ORDER_SECURITY}",
  "domains": [
    {
      "name": "{DOMAIN_TO_PURCHASE}",
      "ownerAddress": "{DOMAIN_OWNER_ADDRESS}",
      "resellerIdentityKey": "{DOMAIN_RESERVATION_ID}"
    }
  ]
}'