Skip to content
Partner/
/
Update operation dependen...

Partner API v3 (3.0.0)

Feature Overview

The Partner API v3 provides you with the ability to lookup, register and manage Web3 domains. The API exposes a RESTful interface for interacting with Web3 domains and the Unstoppable Domains registry.

  • Lookup Domains: Search for specific domains or find suggested alternatives, to determine pricing, availability and on-chain details
  • Registering Domains: Secure domains into your dedicated Custody wallets to maintain the domains on the blockchain
  • Manage Domains: Update records on the blockchain or transfer the domain to external owners, all through a simple API interface

Custody Solution

The API takes the hassle of Web3 out of the equation. Unstoppable Domains will handle all blockchain interactions and concepts, while Partners simply use a RESTful API for managing domains.

Since the domains will be in custody of the Partner, through Unstoppable Domains, the Partner is empowered to make any and all changes to the domains on behalf of their users.

Under the hood, Unstoppable Domains will manage dedicated custodial wallets for Partner-owned domains. These wallets are not shared between Partners and will uniquely identify the Partner on the various supported blockchains.

Should the need arise to remove domains from custody, this is supported by changing the owner of domains to external owners.

Payments

The API will keep track of a running balance of charges and Unstoppable Domains will periodically invoice Partners to settle that balance. This empowers Partners to build payment processing in a way that works best for them.

Blockchain Support

Domain details can be viewed across all of our supported blockchains:

  • Ethereum (ETH)
  • Polygon PoS (MATIC)
  • Base (BASE)

Domains can only be managed on Polygon PoS (MATIC) and Base (BASE). Domains on Ethereum (ETH) are readonly, but management support is coming soon.

Important Concepts

The API has some important concepts, in addition to Web3 Domains, that provide added utility, consistency and information.

Domain Ownership Type

Web3 domains exist on the supported Blockchains, and are owned by wallet addresses associated with those Blockchains. We take ownership a step further, to provide improved security and reliability, by including an owner type in our ownership data. The result is that a Domain's owner is defined by two values: address and type

The owner type can be one of the following:

  • NONE: Either the domain has never been owned or belongs to a "burn" address
  • UD: Owned by Unstoppable Domains
  • SELF: Domain belongs to a wallet addressed associated with your account, indicating you are able to manage it via the API
  • EXTERNAL: Owner doesn't qualify as any of the above. Changing to an EXTERNAL owner will result in the domain belonging to an address outside of the management of Unstoppable Domains and we will have no way to recover it.

By defining an owner in two parts (address and type) we ensure any irreversible action, such as transferring ownership, is deliberate and intended by requiring both the address and type in the request.

Operations

All interactions with the API that initiate changes will create an Operation for tracking that change. Operations can complete immediately or run in the background over the course of several minutes, depending on the Operation type and current conditions on the Blockchain.

Operations include dependencies that represent the smaller units of work associated with the overall operation. These dependencies can also be tracked through the API and each have their own status and metadata.

Your integration should properly handle and anticipate all of the following possible statuses for Operations and their dependencies:

  • QUEUED : The Operation has not started processing yet, but should be started shortly
  • PROCESSING : The Operation has started, often involving sending transactions to the Blockchain
  • SIGNATURE_REQUIRED: The operation is awaiting a signature in order to continue processing. This is only relevant to Self-Custody domain management.
  • COMPLETED : The Operation has finished processing successfully
  • FAILED : The Operation has finished processing and has either fully or partially failed
  • CANCELLED : The Operation has been cancelled, usually due to a failure with a sibling dependency

See the Operations API for additional information.

Wallets

Domains ownership on the Blockchain is handled by associating a Domain with an "address". These addresses are typically managed by Wallets (usually in the form of an application on your computer or mobile device) that manage the private key for the public "address".

The API provides endpoints for creating/managing Wallets within your account to enable you to handle Domain ownership distribution in whatever way works for you. Any Domain that is owned by one of your account's Wallets is fully in your control to manage.

See the Wallets API for additional information.

Get Access

See our quickstart guide for getting your Partner API key: Set up Partner API Access

If you have any questions, contact our Partner Engineering Team to help with API access or learn more.

Overview
Unstoppable Domains (Partner Engineering)
partnerengineering@unstoppabledomains.com
Languages
Servers
Production
https://api.unstoppabledomains.com/partner/v3/
Sandbox
https://api.ud-sandbox.com/partner/v3/

Suggestions

Suggestions for finding available domains

Operations

Domain Lookup & Registration

Domain details/availability lookups and registration.

Operations

Custody Wallets

Manage custody wallets used for storing and managing domains without any signature collection.

These wallets provide the most streamlined way to interact with domains since the initial management request is the only step needed to make changes.

Operations

Custody Domains

Manage your custody domains.

Operations

Self-Custody Wallets

Manage self-custody wallets to allow for management of self-custody domains.

Operations

Self-Custody Domains

Manage domains that are owned in external, self-custody wallets.

The key difference between Custody and Self-Custody operations is that all Self-Custody operations require a signature from the domain owner.

Before you can initiate self-custody operations, you must verify the self-custody wallet that owns the domain.

Operations

Operations

All asynchronous processes handled by the API are represented as Operations. This includes registering a domain, updating a domain's records, changing a domain's owner, returning a domain and more.

OperationsWebhooks

Get list of operations

Request

Get paginated list of past operations, with the ability to filter based on various criteria.

Results ordered with newest operations first.

Security
bearer
Query
domainArray of strings<= 50 items
statusArray of strings(OperationStatus)
Items Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
typeArray of strings(OperationType)
Items Enum"DOMAIN_CLAIM""DOMAIN_UPDATE""DOMAIN_RETURN""WALLET_CREATE""WALLET_UPDATE""WALLET_VERIFY""ACCOUNT_UPDATE"
$cursorstring

The next.$cursor value from the previous page response

curl -i -X GET \
  'https://api.unstoppabledomains.com/partner/v3/operations?domain=string&status=QUEUED&type=DOMAIN_CLAIM&%24cursor=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Bodyapplication/json
@typestringrequired
Value"unstoppabledomains.com/partner.v3.CursorList"
itemsArray of objects(OperationMinimalResponse)required
items[].​idstringrequired
Example: "op-4abb409c-9283-4589-bd36-d27a757a2165"
items[].​@typestringrequired
Value"unstoppabledomains.com/partner.v3.OperationMinimal"
items[].​statusstring(OperationStatus)required
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
items[].​typestring(OperationType)required
Enum"DOMAIN_CLAIM""DOMAIN_UPDATE""DOMAIN_RETURN""WALLET_CREATE""WALLET_UPDATE""WALLET_VERIFY""ACCOUNT_UPDATE"
items[].​domainstring(DomainName)
items[].​lastUpdatedTimestampnumberrequired
Example: 1684356429790
nextnull or CursorListResponseNext (object)required
One of:
null
Response
application/json
{
  "@type": "unstoppabledomains.com/partner.v3.CursorList",
  "items": [
    { … }
  ],
  "next": {}
}

Check operation status

Request

Use this endpoint to check on the status for any Operation being processed by the API.

Security
bearer
Path
idstringrequired
curl -i -X GET \
  'https://api.unstoppabledomains.com/partner/v3/operations/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Bodyapplication/json
idstringrequired
Example: "op-4abb409c-9283-4589-bd36-d27a757a2165"
@typestringrequired
Value"unstoppabledomains.com/partner.v3.Operation"
statusstring(OperationStatus)required
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
typestring(OperationType)required
Enum"DOMAIN_CLAIM""DOMAIN_UPDATE""DOMAIN_RETURN""WALLET_CREATE""WALLET_UPDATE""WALLET_VERIFY""ACCOUNT_UPDATE"
domainstring(DomainName)
lastUpdatedTimestampnumberrequired
Example: 1684356429790
dependenciesArray of SubOperationResponse (object)required
Any of:
dependencies[].​idstringrequired
Example: "bc-2db427bd-5613-40c7-85b1-ab38beed0ed0"
dependencies[].​statusstringrequired
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
dependencies[].​@typestringrequired
Value"unstoppabledomains.com/partner.v3.BlockchainOperation"
dependencies[].​transactionobject(SubOperationTransactionResponse)
dependencies[].​typestringrequired
Value"MINT"
dependencies[].​parametersobject(MintParametersResponse)required
dependencies[].​parameters.​initialRecordsobject(DomainRecords)
dependencies[].​parameters.​toAddressEvmOwnerAddress (string)(OwnerAddress)required
EvmOwnerAddress (string)(OwnerAddress)
Response
application/json
{
  "id": "op-4abb409c-9283-4589-bd36-d27a757a2165",
  "@type": "unstoppabledomains.com/partner.v3.Operation",
  "status": "QUEUED",
  "type": "DOMAIN_CLAIM",
  "domain": "matt.crypto",
  "lastUpdatedTimestamp": 1684356429790,
  "dependencies": [
    { … }
  ]
}

Update operation dependency

Request

Sign operation dependency with status SIGNATURE_REQUIRED so it can continue processing

Security
bearer
Path
idstringrequired
depIdstringrequired
Bodyapplication/jsonrequired
transactionobject(OperationDependencyTransactionUpdateRequestBody)required
transaction.​signaturestring<= 2000 charactersrequired
curl -i -X PATCH \
  'https://api.unstoppabledomains.com/partner/v3/operations/{id}/dependencies/{depId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "signature": "string"
    }
  }'

Responses

Bodyapplication/json
idstringrequired
Example: "op-4abb409c-9283-4589-bd36-d27a757a2165"
@typestringrequired
Value"unstoppabledomains.com/partner.v3.Operation"
statusstring(OperationStatus)required
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
typestring(OperationType)required
Enum"DOMAIN_CLAIM""DOMAIN_UPDATE""DOMAIN_RETURN""WALLET_CREATE""WALLET_UPDATE""WALLET_VERIFY""ACCOUNT_UPDATE"
domainstring(DomainName)
lastUpdatedTimestampnumberrequired
Example: 1684356429790
dependenciesArray of SubOperationResponse (object)required
Any of:
dependencies[].​idstringrequired
Example: "bc-2db427bd-5613-40c7-85b1-ab38beed0ed0"
dependencies[].​statusstringrequired
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
dependencies[].​@typestringrequired
Value"unstoppabledomains.com/partner.v3.BlockchainOperation"
dependencies[].​transactionobject(SubOperationTransactionResponse)
dependencies[].​typestringrequired
Value"MINT"
dependencies[].​parametersobject(MintParametersResponse)required
dependencies[].​parameters.​initialRecordsobject(DomainRecords)
dependencies[].​parameters.​toAddressEvmOwnerAddress (string)(OwnerAddress)required
EvmOwnerAddress (string)(OwnerAddress)
Response
application/json
{
  "id": "op-4abb409c-9283-4589-bd36-d27a757a2165",
  "@type": "unstoppabledomains.com/partner.v3.Operation",
  "status": "QUEUED",
  "type": "DOMAIN_CLAIM",
  "domain": "matt.crypto",
  "lastUpdatedTimestamp": 1684356429790,
  "dependencies": [
    { … }
  ]
}

Pending Operations for a domain

Request

Unlike the operation list route, this endpoint will return a minimal representation of pending operations for a domain across all activity for a given domain.

Since we only allow a single concurrent operation for a domain (across all accounts), this endpoint should be checked before attempting any domain operations. This is particularly important for self-custody domains, as any account (or even the owner themself) can initiate operations.

Security
bearer
Path
namestringrequired
curl -i -X GET \
  'https://api.unstoppabledomains.com/partner/v3/domains/{name}/pending-operations' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Bodyapplication/json
@typestringrequired
Value"unstoppabledomains.com/partner.v3.List"
itemsArray of objects(DomainPendingOperationResponse)required
items[].​@typestringrequired
Value"unstoppabledomains.com/partner.v3.DomainPendingOperation"
items[].​typestring or OperationType (string)required
Example: "DOMAIN_UPDATE"
One of:

Will be UNKNOWN if the operation is a blockchain operation not supported by the API but currently taking place on the blockchain.

string
Value"UNKNOWN"
items[].​idstring

ID of the operation. Will only be included if the operation is associated with your account.

Example: "op-4abb409c-9283-4589-bd36-d27a757a2165"
Response
application/json
{
  "@type": "unstoppabledomains.com/partner.v3.List",
  "items": [
    { … }
  ]
}

Operation FinishedWebhook

Request

Receive a request when an asynchronous operation completes to registered webhooks of type OPERATION_FINISHED

Headers
x-ud-timestampstringrequired

Timestamp when the webhook payload was created

Example: 1686587938683
x-ud-signaturestringrequired

Base64 encoded HMAC-SHA256 of the raw payload body bytes using the account's primary API key as the secret. Used to verify authenticity of the request.

Example: awqOJeH/5GSSesvPYgS2z62BFTYurPduEfJjUBTRzPg=
Bodyapplication/jsonrequired
@typestringrequired
Value"unstoppabledomains.com/partner.v3.WebhookDelivery"
typestring(WebhookType)required
Enum"OPERATION_FINISHED""OPERATION_ACTION_REQUIRED"
dataobject(OperationCheckResponse)required
data.​idstringrequired
Example: "op-4abb409c-9283-4589-bd36-d27a757a2165"
data.​@typestringrequired
Value"unstoppabledomains.com/partner.v3.Operation"
data.​statusstring(OperationStatus)required
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
data.​typestring(OperationType)required
Enum"DOMAIN_CLAIM""DOMAIN_UPDATE""DOMAIN_RETURN""WALLET_CREATE""WALLET_UPDATE""WALLET_VERIFY""ACCOUNT_UPDATE"
data.​domainstring(DomainName)
data.​lastUpdatedTimestampnumberrequired
Example: 1684356429790
data.​dependenciesArray of SubOperationResponse (object)required
Any of:
data.​dependencies[].​idstringrequired
Example: "bc-2db427bd-5613-40c7-85b1-ab38beed0ed0"
data.​dependencies[].​statusstringrequired
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
data.​dependencies[].​@typestringrequired
Value"unstoppabledomains.com/partner.v3.BlockchainOperation"
data.​dependencies[].​transactionobject(SubOperationTransactionResponse)
data.​dependencies[].​typestringrequired
Value"MINT"
data.​dependencies[].​parametersobject(MintParametersResponse)required
data.​dependencies[].​parameters.​initialRecordsobject(DomainRecords)
data.​dependencies[].​parameters.​toAddressEvmOwnerAddress (string)(OwnerAddress)required
EvmOwnerAddress (string)(OwnerAddress)

Responses

Success

Operation Action RequiredWebhook

Request

Receive a request when an asynchronous operation reaches a status that requires an action to be taken for it to proceed. For example, when an operation changes to the SIGNATURE_REQUIRED status, a webhook would be delivered since the operation cannot continue with collecting a signature.

Requests are sent to registered webhooks of type OPERATION_ACTION_REQUIRED

Headers
x-ud-timestampstringrequired

Timestamp when the webhook payload was created

Example: 1686587938683
x-ud-signaturestringrequired

Base64 encoded HMAC-SHA256 of the raw payload body bytes using the account's primary API key as the secret. Used to verify authenticity of the request.

Example: awqOJeH/5GSSesvPYgS2z62BFTYurPduEfJjUBTRzPg=
Bodyapplication/jsonrequired
@typestringrequired
Value"unstoppabledomains.com/partner.v3.WebhookDelivery"
typestring(WebhookType)required
Enum"OPERATION_FINISHED""OPERATION_ACTION_REQUIRED"
dataobject(OperationCheckResponse)required
data.​idstringrequired
Example: "op-4abb409c-9283-4589-bd36-d27a757a2165"
data.​@typestringrequired
Value"unstoppabledomains.com/partner.v3.Operation"
data.​statusstring(OperationStatus)required
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
data.​typestring(OperationType)required
Enum"DOMAIN_CLAIM""DOMAIN_UPDATE""DOMAIN_RETURN""WALLET_CREATE""WALLET_UPDATE""WALLET_VERIFY""ACCOUNT_UPDATE"
data.​domainstring(DomainName)
data.​lastUpdatedTimestampnumberrequired
Example: 1684356429790
data.​dependenciesArray of SubOperationResponse (object)required
Any of:
data.​dependencies[].​idstringrequired
Example: "bc-2db427bd-5613-40c7-85b1-ab38beed0ed0"
data.​dependencies[].​statusstringrequired
Enum"QUEUED""SIGNATURE_REQUIRED""PROCESSING""COMPLETED""FAILED""CANCELLED"
data.​dependencies[].​@typestringrequired
Value"unstoppabledomains.com/partner.v3.BlockchainOperation"
data.​dependencies[].​transactionobject(SubOperationTransactionResponse)
data.​dependencies[].​typestringrequired
Value"MINT"
data.​dependencies[].​parametersobject(MintParametersResponse)required
data.​dependencies[].​parameters.​initialRecordsobject(DomainRecords)
data.​dependencies[].​parameters.​toAddressEvmOwnerAddress (string)(OwnerAddress)required
EvmOwnerAddress (string)(OwnerAddress)

Responses

Success

Account

Manage your account details

Operations

Owners

Search for owned domains

Operations

Webhooks

Manage webhooks used for asynchronous updates to your server.

You can follow our getting started guide here: Webhooks in the Partner API

Operations