Partner API v2 (Legacy) (2.0.0)

Unstoppable Domains (Partner Engineering): partnerengineering@unstoppabledomains.com

The Partner API v2 requires you to be authorized to access. To access the Partner API v2 and integrate it into your application, check our Set up Partner API Access guide.

orders

Create an order and get the status of orders

Buy a domain or claim for free

This API endpoint is used for buying domains from UD. The blockchain needs time before a transaction is mined. In rare cases, it is possible for someone to front run your purchase, which would result in an order being cancelled. We expect this to happen in less than 1 out of 10000 cases. Please make sure you are using the 'Order Status' endpoint and wait until the transaction is mined. Endpoint requires one of the following: email, owner address, or useResellerCustodialWallet. If email is provided - domain will be linked to Unstoppable website account. If owner address is provided - domain will be minted right into crypto wallet. If ownerAddress is not provided and useResellerCustodialWallet = true, the domain will be minted to the reseller's custodial wallet. Optionally user can specify domain records that will be added to the domain once it's minted (i.e. if owner address is provided).

SecurityApiSecret
Request
Request Body schema: application/json
object (OrderPayment)

Payment type and parameters

Array of objects (OrderSecurity)
Array of objects
Responses
200

Successful

400

Bad Request

401

Partner Not Found

post/orders
Request samples
application/json
{
  • "payment": {
    },
  • "security": [
    ],
  • "domains": [
    ]
}
Response samples
application/json
{
  • "orderNumber": "-Lm9wiYytgrpf4YCWYv6",
  • "payment": {
    },
  • "total": 0,
  • "items": [
    ]
}

Get order status by order number

Use this endpoint to pull the status of the order

Request
path Parameters
orderNumber
required
string

ID of the order

Example: -Lm9wiYytgrpf4YCWYv6
Responses
200

Successful

401

Partner Not Found

404

Order Not Found

get/orders/{orderNumber}
Request samples
Response samples
application/json
{
  • "orderNumber": "-Lm9wiYytgrpf4YCWYv6",
  • "payment": {
    },
  • "total": 0,
  • "items": [
    ]
}

domains

Check domain availability and suggestions for purchase or claim

Check multiple domain names availability

Check multiple domain names availability

SecurityApiSecret
Request
query Parameters
search
required
Array of strings

Keywords that will be used to check domain(s) availability. Can be domain name(s) with or without TLD.

Example: search=fancyfox123.crypto&search=firstname&search=domainsforfree1.888
Responses
200

Successful

400

Bad Request

401

Partner Not Found

get/domains
Request samples
Response samples
application/json
{
  • "domains": [
    ]
}

Check domain name availability

Check domain name availability

Request
path Parameters
domainName
required
string
Example: beresnev.crypto
Responses
200

Successful

400

Bad Request

401

Partner Not Found

get/domains/{domainName}
Request samples
Response samples
application/json
{
  • "domain": {
    },
  • "availability": {
    }
}

Get domains suggestions

This endpoint is used to provide domains variants based on provided domains and label. Method will provide domains similar to domains provided in domains parameter.

Request
query Parameters
search
Array of strings

Keywords that will be used to build FREE domain suggestions. Can be TLD or domain name.

Example: search=fancyfox123.crypto&search=firstname&search=domainsforfree1.888
tlds
Array of strings

Limit suggestions output by specific TLDs (crypto, dao, etc.)

Example: tlds=crypto&tlds=nft&tlds=888
Responses
200

Valid

400

Bad Request

401

Partner Not Found

get/domains/suggestions
Request samples
Response samples
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Get free domains suggestions

This endpoint is used to provide free domains suggestions if a partner is eligible for free domains. If partner isn't eligible for free domains suggestions - endpoint will return error.

Request
query Parameters
search
Array of strings

Keywords that will be used to build FREE domain suggestions. Can be TLD or domain name.

Example: search=fancyfox123.crypto&search=firstname&search=domainsforfree1.888
tlds
Array of strings

Limit suggestions output by specific TLDs (crypto, dao, etc.)

Example: tlds=crypto&tlds=nft&tlds=888
Responses
200

Valid

400

Bad Request

401

Partner Not Found

get/domains/suggestions/free
Request samples
Response samples
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Reserve free domain name for period of time

Reserve free domain name for external user identifier. Usually it's a user identifier or email in a partner's system. Domain name becomes unavailable for selling and claiming to anyone except identity that reserved the domain. Only one domain could be reserved per resellerIdentityKey. Reserve time is 168 hours.

SecurityApiSecret
Request
path Parameters
domainName
required
string
Example: beresnev.crypto
Request Body schema: application/json
resellerIdentityKey
string

Unique external identifier of user. Could by ANY string value. Unstoppable will try to match internal and external user id.

Responses
200

Valid

400

Bad Request

401

Partner Not Found

post/domains/{domainName}/reserve
Request samples
application/json
{
  • "resellerIdentityKey": "example@user.com"
}
Response samples
application/json
{
  • "error": {
    },
  • "constraints": [
    ]
}

security

Prepare security parameters for domain orders

Get Fingerprint Public Key

Use this endpoint to fetch Fingerprint public keys

Responses
200

Successful

post/security/fingerprintjs/keys
Request samples
Response samples
application/json
{
  • "key": "TSveZYwtMdTcHjY9MEPa"
}

actions (blockchain)

Create, sign and check status of blockchain actions

Searches for domain actions made

Search for domain actions by user, domain or owner address.

Request
query Parameters
status
string

Blockchain Action Status

Enum: "InProgress" "Completed" "Failed"
userId
number

User ID

domain
string

Domain Name

Example: domain=bogdangusiev.crypto
ownerAddress
string

Domain Owner Address

page
number

Page Number

Example: page=1
perPage
number

Number of actions per page

Example: perPage=10
Responses
200

Successful

get/actions
Request samples
Response samples
application/json
{
  • "count": 1,
  • "actions": [
    ]
}

Creates a user request to perform certain action on chain

Receives domain name, operation and parameters that needs to be performed on the blockchain. Example - set 'crypto.ETH.address' record for 'example.crypto' domain to '0xffff' value

Returns the list of transactions that need to be signed by the user in order to perform that operation and optionally a payment invoice in case user wants UD to compensate gas free for those transactions.

Request
Request Body schema: application/json
Any of:

UpdateRecords action that updates domain crypto records

action
string
Enum: "UpdateRecords" "Transfer" "IssueSubdomain" "Deposit" "Withdraw" "SetReverseResolution" "Return" "DotCoinReturn"
object
domain
string or null (DomainName)

Domain name

gasCompensationPolicy
string

Gas Compensation Policy There are three gas compensation policies that clients can choose, depending on how they want make users send and pay for them.

  • AlwaysCompensate - It always assumes using meta transactions. User pays for transactions in USD via stripe payment intent that UD doesn't execute for free (i.e. ETH).
  • CompensateFree - backend will use meta-transactions only for the those transactions that UD executes for free (i.e. MATIC).
  • NeverCompensate - If a client wants to both make users send and pay for the transactions themselves, it’ll use this policy. Guarantees maximum privacy
Enum: "AlwaysCompensate" "CompensateFree" "NeverCompensate"
Responses
200

Successful

401

Partner Not Found

404

Domain Not Found

post/actions
Request samples
application/json
{
  • "action": "UpdateRecords",
  • "parameters": {
    },
  • "domain": "bogdangusiev.crypto",
  • "gasCompensationPolicy": "CompensateFree"
}
Response samples
application/json
{
  • "id": 12882,
  • "action": "UpdateRecords",
  • "status": "Draft",
  • "domain": {
    },
  • "txs": [
    ],
  • "paymentInfo": {
    },
  • "confirmCodes": [
    ]
}

Returns domain action status

Receives domain action id. Returns the list of transactions that need to be signed by the user in order to perform that operation and optionally a payment invoice in case user wants UD to compensate gas free for those transactions.

Request
path Parameters
actionId
required
number

Action ID obtained from POST /actions endpoint

Example: 85530
Responses
200

Successful

401

Partner Not Found

404

Action Not Found

get/actions/{actionId}
Request samples
Response samples
application/json
{
  • "id": 12882,
  • "action": "UpdateRecords",
  • "status": "Draft",
  • "domain": {
    },
  • "txs": [
    ],
  • "paymentInfo": {
    },
  • "confirmCodes": [
    ]
}

Submits required signatures for a blockchain actionDeprecated

Endpoint deprecated in favor of POST /actions/{actionId}/confirm. The new endpoint is fully compatible with the old one.

Request
path Parameters
actionId
required
number

Action ID obtained from POST /actions endpoint

Example: 85530
header Parameters
X-CUSTODIAL-OTP-TOKEN
string

Custom header to provide an OTP token for custodial authentication; used for domain actions on custodial wallets

Example: MN5QR6T
X-CUSTODIAL-EMAIL-CODE
string

Custom header to provide an email code for custodial authentication; used for domain actions on custodial wallets

Example: 453NM3
Request Body schema: application/json
Array
Any of:

Regular transaction type required attributes

type
string
Value: "Regular"
txHash
string (TransactionHash)

Transaction Hash

id
number (TransactionId)

Transaction ID in UD database

Responses
200

Successful

401

Partner Not Found

404

Action Not Found

post/actions/{actionId}/sign
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "error": {
    }
}

Starts created blockchain action; submits signatures if required; supports auto-confirm for custodial wallets

A domain action requires the following to be performed:

  • every transaction with signatureStatus: Required expects
    • a signature for the case of Meta transaction and
    • txHash for the case of meta transaction
  • Paid stripe intent if present

This endpoint is designed to let user submit the required data for an action to be executed.

Request
path Parameters
actionId
required
number

Action ID obtained from POST /actions endpoint

Example: 85530
header Parameters
X-CUSTODIAL-OTP-TOKEN
string

Custom header to provide an OTP token for custodial authentication; used for domain actions on custodial wallets

Example: MN5QR6T
X-CUSTODIAL-EMAIL-CODE
string

Custom header to provide an email code for custodial authentication; used for domain actions on custodial wallets

Example: 453NM3
Request Body schema: application/json
Array
Any of:

Regular transaction type required attributes

type
string
Value: "Regular"
txHash
string (TransactionHash)

Transaction Hash

id
number (TransactionId)

Transaction ID in UD database

Responses
200

Successful

401

Partner Not Found

404

Action Not Found

post/actions/{actionId}/confirm
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "error": {
    }
}

Creates and immediately starts certain action on chain by reseller request

Receives domain name, operation and parameters that needs to be performed on the blockchain. Example - set 'crypto.ETH.address' record for 'example.crypto' domain to '0xffff' value

Returns the list of transactions that will be executed in order to perform that operation.

SecurityApiSecret
Request
Request Body schema: application/json
Any of:

UpdateRecords action that updates domain crypto records

action
string
Value: "UpdateRecords"
object
domain
string or null (DomainName)

Domain name

Responses
200

Successful

401

Partner Not Found

404

Domain Not Found

post/actions/web2
Request samples
application/json
{
  • "action": "UpdateRecords",
  • "parameters": {
    },
  • "domain": "bogdangusiev.crypto"
}
Response samples
application/json
{
  • "id": 12882,
  • "action": "UpdateRecords",
  • "status": "Draft",
  • "domain": {
    },
  • "txs": [
    ],
  • "paymentInfo": {
    },
  • "confirmCodes": [
    ]
}