openapi: 3.1.0
info:
  title: Web3 Partner API v3 account Leads 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: Leads
  description: Domain conversations and messaging between buyers and sellers (requires authentication)
paths:
  /mcp/v1/actions/ud_leads_list:
    post:
      operationId: leadsList
      summary: List domain conversation leads
      description: List conversations about domains you own or are interested in. Includes buyer-seller messaging threads.
      tags:
      - Leads
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  type: string
                  description: Filter by specific domain name (e.g., "example.crypto")
                skipEmpty:
                  type: boolean
                  description: 'Skip conversations with no messages (default: true)'
                  default: true
                skip:
                  type: integer
                  description: 'Number of conversations to skip (pagination offset, default: 0)'
                  default: 0
                  minimum: 0
                take:
                  type: integer
                  description: 'Number of conversations to return (1-100, default: 20)'
                  default: 20
                  minimum: 1
                  maximum: 100
      responses:
        '200':
          description: List of conversations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadsListResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_lead_get:
    post:
      operationId: leadGet
      summary: Get or create domain conversation
      description: Start or find an existing conversation with the seller of a domain. Returns existing conversation if one already exists.
      tags:
      - Leads
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              properties:
                domain:
                  type: string
                  description: The domain name to inquire about (e.g., "example.crypto")
                buyerId:
                  type: string
                  description: 'Optional: Encoded buyer ID for sellers responding to offers'
      responses:
        '200':
          description: Conversation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactSellerResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_lead_messages_list:
    post:
      operationId: leadMessagesList
      summary: List messages in a conversation
      description: Get messages in a domain conversation. Messages are returned newest-first with cursor-based pagination.
      tags:
      - Leads
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - conversationId
              properties:
                conversationId:
                  type: number
                  description: The conversation ID
                cursor:
                  type: string
                  description: Pagination cursor for loading older messages
      responses:
        '200':
          description: List of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadMessagesListResponse'
        '401':
          description: Authentication required
  /mcp/v1/actions/ud_lead_message_send:
    post:
      operationId: leadMessageSend
      summary: Send a message in a conversation
      description: Send a message in a domain conversation. Messages are encrypted at rest.
      tags:
      - Leads
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - conversationId
              - content
              properties:
                conversationId:
                  type: number
                  description: The conversation ID
                content:
                  type: string
                  maxLength: 1000
                  description: Message content (1-1000 characters)
      responses:
        '200':
          description: Sent message details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadMessageSendResponse'
        '401':
          description: Authentication required
components:
  schemas:
    LeadMessageSendResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            id:
              type: number
              description: Message ID
            content:
              type: string
            senderUserId:
              type: number
            createdAt:
              type: string
        conversationId:
          type: number
    LeadMessagesListResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            type: object
            properties:
              id:
                type: number
                description: Message ID
              content:
                type: string
              senderUserId:
                type: number
              createdAt:
                type: string
        hasMore:
          type: boolean
        nextCursor:
          type:
          - string
          - 'null'
        conversationId:
          type: number
    LeadsListResponse:
      type: object
      properties:
        leads:
          type: array
          items:
            type: object
            properties:
              id:
                type: number
                description: Conversation ID (use with ud_lead_messages_list)
              domainName:
                type: string
              domainId:
                type: number
              createdAt:
                type: string
                format: date-time
              updatedAt:
                type: string
                format: date-time
              shortLatestMessageContent:
                type: string
                description: Preview of latest message (truncated to 100 chars)
              unreadMessageCount:
                type: number
                description: Number of unread messages
              participants:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Encoded participant ID
                    role:
                      type: string
                      enum:
                      - BUYER
                      - SELLER
        total:
          type: number
          description: Total number of conversations matching filters
        skip:
          type: number
          description: Number of items skipped
        take:
          type: number
          description: Number of items returned
    ContactSellerResponse:
      type: object
      properties:
        conversation:
          type: object
          properties:
            id:
              type: number
              description: Conversation ID
            domainName:
              type: string
            domainId:
              type: number
            createdAt:
              type: string
            participants:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  role:
                    type: string
                    enum:
                    - BUYER
                    - SELLER
            isExisting:
              type: boolean
              description: True if returning existing conversation
        message:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT