Edit this page

Resolution Service API

Resolution service provides an API for getting domain data and metadata regardless of that domain's location, whether it is stored on Ethereum, Zilliqa, Polygon, or any other blockchain. The service is used to cache blockchain events in a database for easy retrieval without accessing blockchain APIs.

Important

Unstoppable Domains periodically releases new domain endings, and our Resolution libraries and APIs will automatically detect and support any new domain endings. It is imperative for future proofing your resolution integration to allow all domain inputs to pass through rather than implementing a front end filter (e.g. avoid hard coding domains or placing a regex filter for just .crypto, .nft, etc.).

Alchemy Hosted API

We have partnered with Alchemy to offer UD developers an Alchemy-hosted Resolution Service API. Developers will sign-up for Alchemy's API service and retrieve API keys directly from Alchemy.

For Alchemy API documentation, endpoints, and support videos, visit Alchemy's dedicated page for Unstoppable Domains APIs.

Supported Domains for Resolution Service API

The Resolution Service API supports decentralized domains across two main zones:

Name Service Supported Domains
Zilliqa Name Service (ZNS) .zil
Unstoppable Name Service (UNS) .crypto, .nft, .blockchain, .bitcoin, .coin, .wallet, .888, .dao, .x

Error Codes

Below is a list of all the error codes you might encounter when using the Resolution Service API. The errors are in JSON format.

Copy
Copied
{
    code: string, // one of our custom error names
    message: string, // human-readable error summary
    errors: [
        {
            httpCode: number, // error status code
            name: string, // one of our custom error names
            message: string // human-readable error summary
        }
    ]
}

The resolution service will not return an error in the case of an invalid domain or unsupported domain ending to simplify communication.

400 Error: Bad Request

Error Message Description
each value in owners should not be empty There is no domain name provided to the /domains/ endpoint.
owners should not be empty There is no domain name provided to the /domains/ endpoint.
perPage must not be greater than 200 The provided perPage parameter is a value greater than 200.
perPage must not be less than 1 The provided perPage parameter is a value less than 1.
perPage must be an integer number The provided perPage parameter is not an integer value.
sortDirection must be one of the following values: ASC, DESC The provided sortDirection parameter value is not ASC or DESC.
sortBy must be one of the following values: id, name, created_at The provided sortBy parameter value has to be either id, name or created_at.
Invalid TLD list provided The Resolution Service API does not support the provided list of domain endings.
Invalid resolution records provided The provided resolution parameter value contains records not supported by the resolution service API. See the Records Reference guide for supported key values.

403 Error: Forbidden

Error Message Description
This API requires an auth token provided in an Authorization header in the form "Bearer <auth-token>". There is no Alchemy API key provided in the API request
Invalid API key The provided Alchemy API key is invalid or has expired.

404 Error: Not Found

Error Message Description
Not Found Could not find the requested resource(s).

Asking For Help

Please don't be shy; we're here to help. Join our Discord channel for real-time support from UD and the community if you need assistance integrating your app.