openapi: 3.1.0
info:
  title: Web3 Partner API v3 account Backorders API
  version: 3.0.0
  contact:
    name: Unstoppable Domains (Partner Engineering)
    email: partnerengineering@unstoppabledomains.com
  description: "# Feature Overview\nThe Web3 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.\n- Lookup Domains: Search for specific domains or find suggested alternatives, to determine pricing, availability and on-chain details\n- Registering Domains: Secure domains into your dedicated Custody wallets to maintain the domains on the blockchain\n- Manage Domains: Update records on the blockchain or transfer the domain to external owners, all through a simple API interface\n\n## Custody Solution\nThe 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.\n\nSince 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.\n\nUnder 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.\n\nShould the need arise to remove domains from custody, this is supported by changing the owner of domains to external owners.\n\n## Payments\nThe 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.\n\n\n## Blockchain Support\nDomain details can be viewed across all of our supported blockchains:\n- Ethereum (ETH)\n- Polygon PoS (MATIC)\n- Base (BASE)\n\nDomains can **only be managed on Polygon PoS (MATIC) and Base (BASE)**. Domains on Ethereum (ETH) are readonly, but management support is coming soon.\n\n# Important Concepts\nThe API has some important concepts, in addition to Web3 Domains, that provide added utility, consistency and information.\n\n## Domain Ownership Type\nWeb3 domains exist on the supported Blockchains, and are owned by wallet addresses associated with those Blockchains. \nWe take ownership a step further, to provide improved security and reliability, by including an owner `type` in our ownership data.\nThe result is that a Domain's owner is defined by two values: `address` and `type`\n\nThe owner `type` can be one of the following:\n- `NONE`: Either the domain has never been owned or belongs to a \"burn\" address\n- `UD`: Owned by Unstoppable Domains\n- `SELF`: Domain belongs to a wallet addressed associated with your account, indicating you are able to manage it via the API\n- `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.\n\nBy 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.\n\n## Operations\nAll interactions with the API that initiate changes will create an Operation for tracking that change.\nOperations 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.\n\nOperations 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.\n\nYour integration should properly handle and anticipate all of the following possible statuses for Operations and their dependencies:\n- `QUEUED` : The Operation has not started processing yet, but should be started shortly\n- `PROCESSING` : The Operation has started, often involving sending transactions to the Blockchain\n- `SIGNATURE_REQUIRED`: The operation is awaiting a signature in order to continue processing. This is only relevant to Self-Custody domain management.\n- `COMPLETED` : The Operation has finished processing successfully\n- `FAILED` : The Operation has finished processing and has either fully or partially failed\n- `CANCELLED` : The Operation has been cancelled, usually due to a failure with a sibling dependency\n\nSee the [Operations](/openapi/partner/v3/#tag/operations) API for additional information.\n\n## Wallets\nDomains 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\".\n\nThe 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.\n\nSee the [Wallets](/openapi/partner/v3/#tag/wallets) API for additional information.\n\n# Get Access\nSee our quickstart guide for getting your Partner API key: [Set up Partner API Access](https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/)\n\nIf you have any questions, contact our [Partner Engineering Team](mailto:partnerengineering@unstoppabledomains.com?subject=Partner%20API%20v3%20Inquiry) to help with API access or learn more.\n"
servers:
- url: https://api.unstoppabledomains.com/partner/v3
  description: Production
- url: https://api.ud-sandbox.com/partner/v3
  description: Sandbox
security:
- bearer: []
tags:
- name: Backorders
  description: Create and manage domain backorders, and browse expired or pending-delete domains.
paths:
  /mcp/v1/actions/ud_backorder_create:
    post:
      operationId: backorderCreate
      tags:
      - Backorders
      summary: Create domain backorders
      description: Create backorders for one or more expiring DNS domains. The system monitors the domain and automatically registers it when it drops.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                    - name
                    - contactId
                    - availableAfterTimestamp
                    properties:
                      name:
                        type: string
                        description: Domain name to backorder
                      contactId:
                        type: string
                        description: ICANN contact ID for domain registration
                      availableAfterTimestamp:
                        type: number
                        description: Unix timestamp (ms) when the domain becomes available for registration
      responses:
        '200':
          description: Backorder creation results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        success:
                          type: boolean
                        backorderId:
                          type: number
                        price:
                          type: number
                        serviceFee:
                          type: number
                        status:
                          type: string
                        error:
                          type: string
                  successCount:
                    type: number
                  failureCount:
                    type: number
                  message:
                    type: string
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_backorder_cancel:
    post:
      operationId: backorderCancel
      tags:
      - Backorders
      summary: Cancel domain backorders
      description: Cancel one or more pending domain backorders. Refunds the Account Balance hold (minus non-refundable service fee) and removes the scheduled registration job.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - backorderIds
              properties:
                backorderIds:
                  type: array
                  items:
                    type: number
                  minItems: 1
                  maxItems: 50
                  description: Array of backorder IDs to cancel
      responses:
        '200':
          description: Backorder cancellation results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        backorderId:
                          type: number
                        domain:
                          type: string
                        success:
                          type: boolean
                        refundAmount:
                          type: number
                        error:
                          type: string
                  successCount:
                    type: number
                  failureCount:
                    type: number
                  message:
                    type: string
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_backorders_list:
    post:
      operationId: backordersList
      tags:
      - Backorders
      summary: List user's backorders
      description: List the authenticated user's domain backorders with optional status filtering, domain search, and pagination. Status normalization is applied automatically.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: array
                  items:
                    type: string
                    enum:
                    - pending
                    - cancelled
                    - in-progress
                    - registration-pending
                    - completed-success
                    - completed-not-available
                    - completed-payment-failed
                    - completed-user-contact-invalid
                    - failed
                  description: Filter by backorder status
                query:
                  type: string
                  maxLength: 253
                  description: Search by domain name (partial match)
                offset:
                  type: number
                  minimum: 0
                  description: 'Pagination offset (default: 0)'
                limit:
                  type: number
                  minimum: 1
                  maximum: 100
                  description: 'Items per page (1-100, default: 20)'
      responses:
        '200':
          description: List of backorders with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  backorders:
                    type: array
                    items:
                      type: object
                      properties:
                        backorderId:
                          type: number
                        domain:
                          type: string
                        status:
                          type: string
                        price:
                          type: number
                        serviceFee:
                          type: number
                        availableAfter:
                          type: number
                        createdAt:
                          type: number
                        updatedAt:
                          type: number
                  pagination:
                    type: object
                    properties:
                      total:
                        type: number
                      count:
                        type: number
                      offset:
                        type: number
                      limit:
                        type: number
                      hasMore:
                        type: boolean
                      nextOffset:
                        type: number
                        nullable: true
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_expireds_list:
    post:
      operationId: expiredsList
      tags:
      - Backorders
      summary: Browse the expireds/pending-delete domain marketplace
      description: List domains that are approaching expiration or have recently dropped and are available for backorder registration. Supports filtering by status, TLD, label length, backorder count, and watchlist count.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  maxLength: 253
                  description: Search by domain name (exact match if contains dot) or label substring
                status:
                  type: string
                  enum:
                  - COMING_SOON
                  - AVAILABLE_BACKORDER
                  description: 'Filter by drop status: "COMING_SOON" (not yet dropped) or "AVAILABLE_BACKORDER" (already dropped)'
                tlds:
                  type: array
                  items:
                    type: string
                  description: Filter by TLD extensions (e.g., ["com", "net"])
                sortBy:
                  type: string
                  enum:
                  - name
                  - deletionAt
                  - labelLength
                  - watchlistCount
                  - backorderCount
                  description: 'Sort field (default: "deletionAt")'
                sortDirection:
                  type: string
                  enum:
                  - ASC
                  - DESC
                  description: 'Sort direction (default: "ASC")'
                lengthRange:
                  type: array
                  items:
                    type: number
                    minimum: 0
                  minItems: 2
                  maxItems: 2
                  description: Filter by label length range [min, max]. Use max=0 for no upper bound.
                bidsRange:
                  type: array
                  items:
                    type: number
                    minimum: 0
                  minItems: 2
                  maxItems: 2
                  description: Filter by backorder count range [min, max]. Use max=0 for no upper bound.
                watchlistRange:
                  type: array
                  items:
                    type: number
                    minimum: 0
                  minItems: 2
                  maxItems: 2
                  description: Filter by watchlist count range [min, max]. Use max=0 for no upper bound.
                offset:
                  type: number
                  minimum: 0
                  description: 'Number of items to skip for pagination (default: 0)'
                limit:
                  type: number
                  minimum: 1
                  maximum: 500
                  description: 'Maximum number of items to return (1-500, default: 50)'
      responses:
        '200':
          description: List of expiring/dropped domains
          content:
            application/json:
              schema:
                type: object
                properties:
                  domains:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Full domain name
                        deletionTimestamp:
                          type: number
                          description: Unix timestamp in milliseconds when the domain drops/dropped
                        status:
                          type: string
                          enum:
                          - COMING_SOON
                          - AVAILABLE_BACKORDER
                        labelLength:
                          type: number
                          description: Length of the domain label
                        watchlistCount:
                          type: number
                          description: Number of users watching this domain
                        backorderCount:
                          type: number
                          description: Number of active backorders
                  pagination:
                    type: object
                    properties:
                      total:
                        type: number
                      count:
                        type: number
                      offset:
                        type: number
                      limit:
                        type: number
                      hasMore:
                        type: boolean
                      nextOffset:
                        type: number
                  truncated:
                    type: boolean
                    description: Whether the response was truncated to fit within size limits
                  truncationMessage:
                    type: string
                    description: Message indicating how many results were truncated
        '401':
          description: Authentication required
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT