Edit this page

Domain Actions API (Legacy) Overview

Partner API v2 Deprecation

Partner API v2 was deprecated on Feb 12, 2024. Please check the v3 specification for integration guides.

The Domain Actions API (Legacy) from Unstoppable Domains is designed to make it easier for Partners to interact with domains on the blockchain. It provides a convenient way to generate the transactions needed to perform various actions, such as updating domain records, configuring reverse resolution, or transferring domain ownership.

This allows Partners to quickly and efficiently perform these actions with a single API request without worrying about the complex details of forming transactions on the client side. For more information about the endpoints, please consult the Partner API v2 (Legacy) endpoint specification.

The diagram below illustrates the general process between a Partner and Unstoppable Domains when utilizing the Domain Actions API.

Domain Actions API success flow

Domain Actions API success flow

Gas Compensation Policies

There are three gas compensation policies that Partners can choose from when creating a domain action draft depending on how they want to make users send and pay for transaction fees.

  • AlwaysCompensate : This policy always assumes the use of meta transactions . It allows the user pay for transactions in USD via Stripe payment intent , rather than in ETH.
  • CompensateFree : This policy allows Unstoppable Domains to pay the transaction fees for a user on the Polygon network.
  • NeverCompensate : This policy should be used if a client wants to make the user send and pay for the transactions themselves and guarantees maximum privacy.

You can only use one gas compensation policy per domain action request based on the user experience you want to provide to your users.

Step 1: Create a Domain Action Draft

There are several functionalities offered by the Domain Actions API to interact with your domains, detailed in the chart below.

Action Name Description Integration Guides
UpdateRecords generate transactions to update resolution records for a domain UpdateRecords Action Guide
Return generate transactions to return a domain to Unstoppable Domains and receive a refund Return Action Guide
SetReverseResolution generate transactions to configure reverse resolution records for a domain SetReverseResolution Action Guide
Transfer generate transactions to transfer a domain name Transfer Action Guide
Deposit or Withdraw generate transactions to bridge domains from Ethereum to Polygon and vice versa Deposit or Withdraw Action Guide

Step 2: Sign the Transaction

When working with a Meta transaction, you must sign the tx.messageToSign obtained from the Domain Actions API using the ethers.js library or a tool such as Etherscan, Polygonscan, or Mumbai Polygonscan. After signing the message, you must send the signature to the Domain Actions API.

For a Regular transaction, the process is slightly different. After signing the message, you must send it to the transaction pool. Once the transaction has been added to the pool, you send the transaction hash to the Domain Actions API.

Signing messages on Etherscan

Signing messages on Etherscan

Step 3: Submit Domain Action Signature

The Domain Actions API (legacy) has an endpoint that allows users to submit the signatures and transaction hashes for their signed transactions. This allows Unstoppable Domains to verify the signatures and confirm that the necessary fees have been paid.

Step 4: Track the Transaction Status

There are several ways to track the status of transactions submitted to the Domain Actions API (Legacy), detailed in the table below.

Endpoint Description Integration Guides
Get Domain Action retrieve the details of a domain action request with its domain action ID Get Domain Action Guide
Get Domain Actions retrieve the domain actions performed by a user, domain or owner address Get Domain Action Guide

Fork Our Postman Collection

Unstoppable Domains offers a Postman collection that you can easily import into your workspace to quickly interact with the Partner and Domain Actions API.

Run in Postman

Help Us Improve

Please take a few moments to answer some questions about your experience with our Partner API. Your feedback will help us improve our services.