Partner API v3 (3.0.0)

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

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.

Suggestions

Suggestions for finding available domains

Get suggested domains that are available for registering

All domains returned by this route are available for registration

Securitybearer
Request
query Parameters
tlds
Array of strings
Deprecated

Use ending instead

Example: tlds=crypto
Array of strings or DomainName (string)

TLD or Parent Domain to apply to your query base names

required
Array of strings or DomainName (string)
Responses
200
400
get/suggestions/domains
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.List",
  • "items": [
    ]
}

Domain Lookup & Registration

Domain details/availability lookups and registration.

Lookup multiple domain details and availability

Get domain availability and owner details for multiple domains using the query string search options. Optionally, use the $expand query string to include additional data in the response (ie. ?$expand=records&$expand=registration).

If the domain is available to be registered it will have a availability.status of AVAILABLE and will include an availability.price object.

Securitybearer
Request
query Parameters
$expand
Array of strings

Use $expand options to conditionally include portions of the response

Items Enum: "records" "registration"
tlds
Array of strings
Deprecated

Use ending instead

Example: tlds=crypto
Array of strings or DomainName (string)

TLD or Parent Domain to apply to your query base names

required
Array of strings or DomainName (string)
Responses
200
400
get/domains
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.List",
  • "items": [
    ]
}

Register a domain

If a domain is available, use this route to register it to your account. The domain will be minted or transfered to your custodial wallet where only Unstoppable Domains, on your behalf, will be able to make changes to it.

The price of the domain will be automatically added to your running balance with Unstoppable Domains. The pending balance of your account will be invoiced periodically.

Register to specific owner

If you do not provide an owner in your request, your account's default wallet address will be used as the owner. Use GET /account to confirm your default wallet address.

When providing an owner object in your request, be sure the type aligns with the address. To register to one of your own wallets, the type must be SELF. Use GET /account/wallets to see your list of available wallets.

Subdomains

Registering subdomains requires ownership of the parent domain. There are dedicated routes for subdomain registration:

Securitybearer
Request
query Parameters
$preview
boolean (OperationPreviewParameter)
Default: false

Allows simulating the operation creation (when set to true), without actually starting any processing. This can be used to validate the operation will be permitted and get a preview of the initial outcome.

When used, the operation in the response will have PREVIEW for all id and status values.

Request Body schema: application/json
name
required
string (DomainName)
object (UpdateDomainRecords) <= 500 properties
object (DomainMintRequestBodyOwner)
Responses
201
400
post/domains
Request samples
application/json
{
  • "name": "matt.crypto",
  • "records": {
    },
  • "owner": {
    }
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.DomainOperationResult",
  • "operation": {
    }
}

Get domain details and availability

Get information about the domain's current owner and availability status. Optionally, use the $expand query string to include additional data in the response (ie. ?$expand=records&$expand=registration).

If the domain is available to be registered it will have a availability.status of AVAILABLE and will include an availability.price object.

Securitybearer
Request
path Parameters
name
required
string (DomainName)
Example: matt.crypto
query Parameters
$expand
Array of strings

Use $expand options to conditionally include portions of the response

Items Enum: "records" "registration"
Responses
200
400
get/domains/{name}
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.Domain",
  • "records": { },
  • "name": "matt.crypto",
  • "owner": {
    },
  • "availability": {
    },
  • "registration": { },
  • "blockchain": "MATIC"
}

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.

Get list of account wallets

Any domains held in the wallets of type SELF can be managed by your account without any signature collection. You can use these SELF wallets to distribute domains in whatever way works best for you.

This route will return both custody (SELF) and self-custody (EXTERNAL) wallets associated with your account. To only list custody wallets, simply include the ?type=SELF query string parameter.

Securitybearer
Request
query Parameters
$cursor
string

The next.$cursor value from the previous page response

type
Array of strings
Items Enum: "SELF" "EXTERNAL"
Responses
200

Paginated list of wallets associated with your account

get/account/wallets
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.CursorList",
  • "items": [
    ],
  • "next": { }
}

Create a new custody wallet

Create an additional custodial wallet in your account.

Securitybearer
Responses
201
400
post/account/wallets
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.InternalWalletCreateResult",
  • "operation": {
    }
}

Get wallet details

Get details for a wallet associated with your account. This route supports both custody (SELF) and self-custody (EXTERNAL) wallets.

Include the ?$expand=primaryDomain to include the wallet's Primary Domain (also known as the Reverse Resolution) in the response.

Securitybearer
Request
path Parameters
address
required
string
query Parameters
$expand
string
Value: "primaryDomain"
Responses
200
404

Wallet does not exist in your account

get/account/wallets/{address}
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WalletMinimal",
  • "address": "0xb4783AeF93923a2d4eEA29C84f347F26E62e4321",
  • "type": "SELF",
  • "primaryDomain": "matt.crypto"
}

Update custody wallet

Update details for a specific custody wallet in your account.

This can be used to set (or clear) the Primary Domain (also known as the Reverse Resolution) for a custody wallet.

To clear the Primary Domain for a wallet, pass a null value for the primaryDomain property within the request body.

Securitybearer
Request
path Parameters
address
required
string
query Parameters
$preview
boolean (OperationPreviewParameter)
Default: false

Allows simulating the operation creation (when set to true), without actually starting any processing. This can be used to validate the operation will be permitted and get a preview of the initial outcome.

When used, the operation in the response will have PREVIEW for all id and status values.

Request Body schema: application/json
required
DomainName (string) or null
Responses
200
400
404

Wallet does not exist in your account

patch/account/wallets/{address}
Request samples
application/json
{
  • "primaryDomain": "matt.crypto"
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WalletUpdateResult",
  • "operation": {
    }
}

Custody Domains

Manage your custody domains. All functionality applies to both second-level domains and subdomains, unless otherwise noted.

Register a subdomain (from parent domain in custody)

If a subdomain is available, and the Parent domain in your account's custody, use this route to register it to your account. The domain will be minted or transfered to your custodial wallet where only Unstoppable Domains, on your behalf, will be able to make changes to it.

The price of the domain will be automatically added to your running balance with Unstoppable Domains. The pending balance of your account will be invoiced periodically.

Register to specific owner

If you do not provide an owner in your request, your account's default wallet address will be used as the owner. Use GET /account to confirm your default wallet address.

When providing an owner object in your request, be sure the type aligns with the address. To register to one of your own wallets, the type must be SELF. Use GET /account/wallets to see your list of available wallets.

After Registering

After successfully registering a subdomain to your account, you can use any of the Domain management APIs to manage it just like any other domain.

While registering subdomains uses a different process, in every other way a subdomain is just like a second-level domain.

Securitybearer
Request
path Parameters
parent
required
string (DomainName)

Parent domain of subdomain being registered

Example: matt.crypto
query Parameters
$preview
boolean (OperationPreviewParameter)
Default: false

Allows simulating the operation creation (when set to true), without actually starting any processing. This can be used to validate the operation will be permitted and get a preview of the initial outcome.

When used, the operation in the response will have PREVIEW for all id and status values.

Request Body schema: application/json
name
required
string (DomainName)
object (UpdateDomainRecords) <= 500 properties
object (DomainMintRequestBodyOwner)
Responses
201
400
post/domains/{parent}/subdomains
Request samples
application/json
{
  • "name": "matt.crypto",
  • "records": {
    },
  • "owner": {
    }
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.DomainOperationResult",
  • "operation": {
    }
}

Update a domain (partial update)

Perform Domain updates while preserving the existing records.

Change Owner with Records Preserved

{
  "owner": {
    "type": "EXTERNAL",
    "address": "0x123"
  }
}

Changes owner to the new owner address without modifying the domain records.

Owner Types

When changing owner of a domain, you must provide both a type and an address to clearly indicate the intent of the change.

  • NONE: Used when changing the owner to a "burn" address, which will result in nobody owning the domain
    • Valid "burn" addresses are 0x0000000000000000000000000000000000000000 and 0x000000000000000000000000000000000000dEaD
  • UD: Used when changing the owner to an addressed owned by Unstoppable Domains
  • SELF: Used when changing the owner to another address that belongs to your account
  • EXTERNAL: Used when changing the owner to address that doesn't qualify as any of the above.
    • WARNING: This 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.

Update Records with existing Records Preserved

{
  "records": {
    "key2": "value2"
  }
}

When applied to a domain with existing records, or with an existing key2, will result in only the key2 value being set to the new value.

See our documentation for more information on standardized keys.

Securitybearer
Request
path Parameters
name
required
string (DomainName)
Example: matt.crypto
query Parameters
$preview
boolean (OperationPreviewParameter)
Default: false

Allows simulating the operation creation (when set to true), without actually starting any processing. This can be used to validate the operation will be permitted and get a preview of the initial outcome.

When used, the operation in the response will have PREVIEW for all id and status values.

Request Body schema: application/json
object (DomainUpdateRequestBodyOwner)
object (UpdateDomainRecords) <= 500 properties
Responses
200
400

Validation error or bad request due to domain custody, unsupported blockchain, etc.

502
patch/domains/{name}
Request samples
application/json
{
  • "owner": {
    },
  • "records": {
    }
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.DomainOperationResult",
  • "operation": {
    }
}

Update a domain (overwriting update)

Perform Domain updates while doing full resets of the records.

Change Owner with Record Reset

{
  "owner": {
    "type": "EXTERNAL",
    "address": "0x123"
  },
  "records": {}
}

Clears all records from the domain, then changes owner to the new owner address.

NOTE: You must include "records": {} to indicate the intent to clear records.

Owner Types

When changing owner of a domain, you must provide both a type and an address to clearly indicate the intent of the change.

  • NONE: Used when changing the owner to a "burn" address, which will result in nobody owning the domain
    • Valid "burn" addresses are 0x0000000000000000000000000000000000000000 and 0x000000000000000000000000000000000000dEaD
  • UD: Used when changing the owner to an addressed owned by Unstoppable Domains
  • SELF: Used when changing the owner to another address that belongs to your account
  • EXTERNAL: Used when changing the owner to address that doesn't qualify as any of the above.
    • WARNING: This 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.

Update Records with Record Reset

{
  "records": {
    "key2": "value2"
  }
}

When applied to a domain with existing records, only key2 will remain after the update is complete.

See our documentation for more information on standardized keys.

Securitybearer
Request
path Parameters
name
required
string (DomainName)
Example: matt.crypto
query Parameters
$preview
boolean (OperationPreviewParameter)
Default: false

Allows simulating the operation creation (when set to true), without actually starting any processing. This can be used to validate the operation will be permitted and get a preview of the initial outcome.

When used, the operation in the response will have PREVIEW for all id and status values.

Request Body schema: application/json
object (DomainUpdateRequestBodyOwner)
object (UpdateDomainRecords) <= 500 properties
Responses
200
400

Validation error or bad request due to domain custody, unsupported blockchain, etc.

502
put/domains/{name}
Request samples
application/json
{
  • "owner": {
    },
  • "records": {
    }
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.DomainOperationResult",
  • "operation": {
    }
}

Return and refund a domain

Return the domain to Unstoppable Domains so it is once again considered available for registering. The amount previously added to your running balance will be removed after successfully returning a domain.

Returns are only allowed within 14 days of the original registration date, per our return policy.

Securitybearer
Request
path Parameters
name
required
string
query Parameters
$preview
boolean (OperationPreviewParameter)
Default: false

Allows simulating the operation creation (when set to true), without actually starting any processing. This can be used to validate the operation will be permitted and get a preview of the initial outcome.

When used, the operation in the response will have PREVIEW for all id and status values.

Responses
200
400
delete/domains/{name}
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.DomainOperationResult",
  • "operation": {
    }
}

Self-Custody Wallets

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

Verifying Self-Custody Wallets

Before you can initiate self-custody operations, you must first verify the self-custody wallet (only needs to be done once per wallet).

This involves:

  1. Fetching a verification message to sign
  2. Collecting a personal_sign signature from the wallet owner
  3. Submitting the signature to register the verified wallet

After verifying a wallet, it will be returned by the Single-Wallet and Wallet List routes, with the type of EXTERNAL.

Supported Self-Custody Wallets

  • Externally Owned Accounts (EOAs)
  • ERC1271 Smart Contract wallets deployed on Polygon

Get wallet verification to sign

In order to use an self-custody wallet within the API, you must first use it to sign a verification message. This endpoint will provide the specific substring that needs to be signed.

The response message is meant to be included in personal_sign request for the wallet owner to sign. The exact message that is signed simply needs to include the response message, so you can include some human-friendly text, as well.

Securitybearer
Request
path Parameters
address
required
string
Responses
200
400
get/account/wallets/{address}/verification
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WalletUnsignedVerification",
  • "message": "string"
}

Submit signed wallet verification

After signing the verification message, submit the signature to have the self-custody wallet registered as a verified external wallet for management operations.

If the message the owner signed was not the exact message from the verification response, you must also provide the exact message in the request body. It should be the non-hex string used in the personal_sign request.

Securitybearer
Request
path Parameters
address
required
string
Request Body schema: application/json
message
string <= 2000 characters
signature
required
string <= 2000 characters
Responses
201
400
post/account/wallets/{address}/verification
Request samples
application/json
{
  • "message": "string",
  • "signature": "string"
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WalletVerificationResult",
  • "operation": {
    }
}

Get list of self-custody wallets

These wallets are verified EXTERNAL wallets that you can use for initiating self-custody domain operations. Any operation initiated for one of these wallets requires an external signature.

Securitybearer
Request
query Parameters
$cursor
string
type
required
Array of strings
Default: []
Items Enum: "SELF" "EXTERNAL"
$expand
required
string
Default: []
Value: "primarydomain"
Responses
200

Paginated list of EXTERNAL wallets

get/external/wallets
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.CursorList",
  • "items": [
    ],
  • "next": { }
}

Get self-custody wallet

Get details for a single self-custody wallet that has verified for your account.

Include the ?$expand=primaryDomain to include the wallet's Primary Domain (also known as the Reverse Resolution) in the response.

Securitybearer
Request
path Parameters
address
required
string
query Parameters
$expand
string
Value: "primaryDomain"
Responses
200
404

Wallet does not exist in your account

get/external/wallets/{address}
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WalletMinimal",
  • "address": "0xb4783AeF93923a2d4eEA29C84f347F26E62e4321",
  • "type": "SELF",
  • "primaryDomain": "matt.crypto"
}

Update self-custody wallet

Update details for a specific self-custody wallet in your account.

This can be used to set (or clear) the Primary Domain (also known as the Reverse Resolution) for a domain.

To clear the Primary Domain for a wallet, pass a null value for the primaryDomain property within the request body.

Note: This will create an operation that requires a signature from the self-custody wallet owner.

Securitybearer
Request
path Parameters
address
required
string
Request Body schema: application/json
required
DomainName (string) or null
Responses
200
400
404

Wallet does not exist in your account

patch/external/wallets/{address}
Request samples
application/json
{
  • "primaryDomain": "matt.crypto"
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WalletUpdateResult",
  • "operation": {
    }
}

Self-Custody Domains

Manage domains that are owned in external, self-custody wallets. All functionality applies to both second-level domains and subdomains, unless otherwise noted.

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.

Signing Self-Custody Operations

After you successfully initiate a self-custody operation, it will have a status of SIGNATURE_REQUIRED. You then need to collect a signature of the messageToSign from the operation.dependencies[].transaction object.

After the owner has signed the message, you use the dependency update route to submit the signature and continue processing the operation.

Update a self-custody domain (overwriting update)

Perform Self-Custody Domain updates while doing full resets of the records. Usage is the same as the custody variant.

Securitybearer
Request
path Parameters
name
required
string (DomainName)
Example: matt.crypto
Request Body schema: application/json
object (DomainUpdateRequestBodyOwner)
object (UpdateDomainRecords) <= 500 properties
Responses
200
400
502

Blockchain access is currently degraded

put/external/domains/{name}
Request samples
application/json
{
  • "owner": {
    },
  • "records": {
    }
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.DomainOperationResult",
  • "operation": {
    }
}

Update a self-custody domain (partial update)

Perform Self-Custody Domain updates while preserving the existing records. Usage is the same as the custody variant.

Securitybearer
Request
path Parameters
name
required
string (DomainName)
Example: matt.crypto
Request Body schema: application/json
object (DomainUpdateRequestBodyOwner)
object (UpdateDomainRecords) <= 500 properties
Responses
200
400
502

Blockchain access is currently degraded

patch/external/domains/{name}
Request samples
application/json
{
  • "owner": {
    },
  • "records": {
    }
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.DomainOperationResult",
  • "operation": {
    }
}

Register a subdomain from a self-custody parent domain

The parent domain must belong to a wallet that has been verified. Usage is the same as the custody variant.

Securitybearer
Request
path Parameters
parent
required
string (DomainName)
Example: matt.crypto
Request Body schema: application/json
name
required
string (DomainName)
object (UpdateDomainRecords) <= 500 properties
object (DomainMintRequestBodyOwner)
Responses
201
400
502

Blockchain access is currently degraded

post/external/domains/{parent}/subdomains
Request samples
application/json
{
  • "name": "matt.crypto",
  • "records": {
    },
  • "owner": {
    }
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.DomainOperationResult",
  • "operation": {
    }
}

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.

Get list of operations

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

Results ordered with newest operations first.

Securitybearer
Request
query Parameters
domain
Array of strings <= 50 items
status
Array of strings (OperationStatus)
Items Enum: "QUEUED" "SIGNATURE_REQUIRED" "PROCESSING" "COMPLETED" "FAILED" "CANCELLED"
type
Array of strings (OperationType)
Items Enum: "DOMAIN_CLAIM" "DOMAIN_UPDATE" "DOMAIN_RETURN" "WALLET_CREATE" "WALLET_UPDATE" "WALLET_VERIFY" "ACCOUNT_UPDATE"
$cursor
string

The next.$cursor value from the previous page response

Responses
200
400
get/operations
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.CursorList",
  • "items": [
    ],
  • "next": { }
}

Check operation status

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

Securitybearer
Request
path Parameters
id
required
string
Responses
200
400
404
get/operations/{id}
Request samples
Response samples
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

Sign operation dependency with status SIGNATURE_REQUIRED so it can continue processing

Securitybearer
Request
path Parameters
id
required
string
depId
required
string
Request Body schema: application/json
required
object (OperationDependencyTransactionUpdateRequestBody)
Responses
200
400
404
patch/operations/{id}/dependencies/{depId}
Request samples
application/json
{
  • "transaction": {
    }
}
Response samples
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

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.

Securitybearer
Request
path Parameters
name
required
string
Responses
200
403

Access to the resource or the ability to perform the requested operation is not allowed for your account.

get/domains/{name}/pending-operations
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.List",
  • "items": [
    ]
}

Operation FinishedWebhook

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

Request
header Parameters
x-ud-timestamp
required
string

Timestamp when the webhook payload was created

Example: 1686587938683
x-ud-signature
required
string

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=
Request Body schema: application/json
@type
required
string
Value: "unstoppabledomains.com/partner.v3.WebhookDelivery"
type
required
string (WebhookType)
Enum: "OPERATION_FINISHED" "OPERATION_ACTION_REQUIRED"
required
object (OperationCheckResponse)
Responses
200

Success

Request samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WebhookDelivery",
  • "type": "OPERATION_FINISHED",
  • "data": {
    }
}

Operation Action RequiredWebhook

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

Request
header Parameters
x-ud-timestamp
required
string

Timestamp when the webhook payload was created

Example: 1686587938683
x-ud-signature
required
string

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=
Request Body schema: application/json
@type
required
string
Value: "unstoppabledomains.com/partner.v3.WebhookDelivery"
type
required
string (WebhookType)
Enum: "OPERATION_FINISHED" "OPERATION_ACTION_REQUIRED"
required
object (OperationCheckResponse)
Responses
200

Success

Request samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WebhookDelivery",
  • "type": "OPERATION_FINISHED",
  • "data": {
    }
}

Account

Manage your account details

Get account details

Securitybearer
Responses
200
get/account
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.AccountSummary",
  • "id": "string",
  • "defaultWalletAddress": "string"
}

Update account details

Change your default wallet address, which is used when no wallet address is specified during domain registration.

Securitybearer
Request
Request Body schema: application/json
required
string (OwnerAddress)
Responses
200
400
patch/account
Request samples
application/json
{
  • "defaultWalletAddress": "0xb4783AeF93923a2d4eEA29C84f347F26E62e4321"
}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.AccountUpdateResult",
  • "operation": {
    }
}

Owners

Search for owned domains

Search for domains owned by an address

Securitybearer
Request
path Parameters
address
required
string
query Parameters
$expand
Array of strings

Use $expand options to conditionally include portions of the response

Items Enum: "records" "registration" "owner" "availability"
$cursor
string

The next.$cursor value from the previous page response

Responses
200
get/owners/{address}/domains
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.CursorList",
  • "items": [
    ],
  • "next": { }
}

Search

Search for owned entities

Search for owned domains by one or more addresses

Securitybearer
Request
query Parameters
$expand
Array of strings

Use $expand options to conditionally include portions of the response

Items Enum: "records" "registration" "owner" "availability"
owner.address
required
Array of strings

Addresses to search by

$cursor
string

The next.$cursor value from the previous page response

Responses
200
get/search/owners/domains
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.CursorList",
  • "items": [
    ],
  • "next": { }
}

Webhooks

Manage webhooks used for asynchronous updates to your server.

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

Get list of your webhooks

Securitybearer
Responses
200
get/account/webhooks
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.CursorList",
  • "items": [
    ],
  • "next": { }
}

Register new webhook

Register a new webhook for a given webhook event type. You are limited to 3 webhook registrations per webhook type.

All webhook url values should be complete, valid URLs, using either http or https procotols. All webhook deliveries will be POST requests and sent to the registered URL exactly as provided.

Securitybearer
Request
Request Body schema: application/json
url
required
string <uri>
type
required
string (WebhookType)
Enum: "OPERATION_FINISHED" "OPERATION_ACTION_REQUIRED"
Responses
201
400
post/account/webhooks
Request samples
application/json
{}
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WebhookCreateResult",
  • "operation": {
    }
}

Get webhook details

Securitybearer
Request
path Parameters
id
required
string
Responses
200
404

Webhook with provided ID does not exist in your account

get/account/webhooks/{id}
Request samples
Response samples
application/json
{}

Deregister existing webhook

Securitybearer
Request
path Parameters
id
required
string
Responses
200
404

Webhook with provided ID does not exist in your account

delete/account/webhooks/{id}
Request samples
Response samples
application/json
{
  • "@type": "unstoppabledomains.com/partner.v3.WebhookDeleteResult",
  • "operation": {
    }
}