openapi: 3.1.0 info: title: Web3 Partner API v3 account Portfolio 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: Portfolio description: Manage owned domains (requires authentication) paths: /mcp/v1/actions/ud_portfolio_list: post: operationId: portfolioList summary: List portfolio domains description: List domains in the authenticated user's portfolio with filtering, sorting, and pagination. By default, only ICANN (DNS) domains are returned. Returns 50 domains per page by default. If hasMore is true in the pagination response, increment the page parameter to fetch additional results. tags: - Portfolio security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: page: type: number minimum: 1 description: 'Page number, 1-indexed (default: 1)' example: 1 pageSize: type: number minimum: 1 maximum: 100 description: 'Number of domains per page, 1-100 (default: 50)' example: 50 searchTerm: type: string description: Optional search term to filter domains by name status: type: string enum: - all - for-sale - unlisted description: 'Filter by listing status: "all" (default), "for-sale", or "unlisted"' registryType: type: string enum: - dns - web3 description: 'Filter by registry type: "dns" (ICANN/Web2 domains, default) or "web3" (blockchain domains only)' expiringWithinDays: type: number minimum: 1 maximum: 365 description: Filter domains expiring within the specified number of days (1-365) example: 30 expired: type: boolean description: Filter for domains that have already expired minLength: type: number minimum: 1 description: Filter domains with label length >= this value maxLength: type: number minimum: 1 description: Filter domains with label length <= this value autoRenewal: type: string enum: - 'true' - 'false' description: Filter by auto-renewal status tagFilters: type: array items: type: string description: Filter domains by tag names (e.g., ["personal", "business"]) orderBy: type: string enum: - name - length - purchasedAt - expiresAt - listingPrice - offers - leads - watchlistCount description: 'Sort by: "name", "length", "purchasedAt", "expiresAt", "listingPrice", "offers", "leads", or "watchlistCount"' orderDirection: type: string enum: - asc - desc description: 'Sort direction: "asc" (ascending, default) or "desc" (descending)' responses: '200': description: Portfolio domains list content: application/json: schema: $ref: '#/components/schemas/ListDomainsResponse' '401': description: Authentication required /mcp/v1/actions/ud_domain_get: post: operationId: domainGet summary: Get comprehensive portfolio domain info description: 'Get comprehensive information for specific domains in your portfolio. Returns all data from ud_portfolio_list plus additional detail: renewal pricing, flags, DNS configuration (nameservers, hosting, DNSSEC), marketplace metrics, and pending operations. Supports bulk lookups for up to 50 domains.' tags: - Portfolio security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - domains properties: domains: type: array items: type: string minLength: 1 minItems: 1 maxItems: 50 description: Array of domain names to get info for (e.g., ["example.com", "mysite.io"]) example: - example.com - mysite.io responses: '200': description: Portfolio domain details content: application/json: schema: $ref: '#/components/schemas/GetPortfolioDomainsResponse' '401': description: Authentication required components: schemas: PortfolioDomain: type: object properties: name: type: string description: Full domain name (e.g., "example.com") extension: type: string description: TLD (e.g., "com") label: type: string description: Domain label without TLD sld: type: - string - 'null' description: Second-level domain punycode: type: boolean description: Whether domain uses punycode purchasedAt: type: - string - 'null' description: Purchase date (ISO string) expiresAt: type: - string - 'null' description: Expiration date for DNS domains (ISO string) transferStatus: type: string description: 'Domain transfer status: • "none" - No active transfer • "pending" - Transfer in progress' isExternallyOwned: type: boolean description: Whether domain is externally owned tags: type: array items: type: string description: User-defined tags reverse: type: boolean description: Whether this is set as reverse resolution offersCount: type: number description: Number of active offers on this domain leadsCount: type: number description: Number of buyer inquiries/messages about this domain watchlistCount: type: number description: Number of users watching this domain listing: type: - object - 'null' description: Listing details if domain is for sale properties: id: type: number description: Listing ID price: type: number description: Listing price in cents status: type: string description: 'Listing status: • "open" - Live on marketplace, ready for purchase (user-custodied domains) • "open-not-signed" - Live on marketplace, ready for purchase (UD-custodied domains, no user action needed) • "open-on-request" - Accepting offers only, no fixed price • "draft" - Not yet published • "waiting-for-approval" - Pending wallet signature from owner • "pending-admin-approval" - Under review (high-value listings) • "pending" - Sale in progress • "canceled" - Listing was canceled Note: Both "open" and "open-not-signed" mean the listing is active and purchasable.' createdAt: type: string description: ISO date string updatedAt: type: string description: ISO date string views: type: number description: Number of page views autoRenewal: type: - object - 'null' description: Auto-renewal subscription details if enabled properties: status: type: string description: 'Auto-renewal subscription status: • "active" - Subscription active, will auto-renew • "pending" - Payment collected, waiting for domain registration • "update_required" - Payment method needs updating (card expired/declined) • "expired" - Subscription expired, domain renewal overdue • "cancelled" - Subscription cancelled, will not auto-renew' expiresAt: type: - string - 'null' description: Subscription expiration date (ISO string) ListDomainsResponse: type: object properties: domains: type: array items: $ref: '#/components/schemas/PortfolioDomain' pagination: type: object properties: page: type: number description: Current page number pageSize: type: number description: Items per page totalPages: type: number description: Total number of pages total: type: number description: Total number of domains hasMore: type: boolean description: Whether more pages exist nextPage: type: - number - 'null' description: Next page number if more results exist, null otherwise truncated: type: boolean description: Whether results were truncated due to size limits truncationMessage: type: string GetPortfolioDomainsResponse: type: object properties: domains: type: array description: Comprehensive info for each requested domain items: type: object properties: domain: type: string description: The domain name found: type: boolean description: Whether the domain was found in your portfolio extension: type: string description: TLD (e.g., "com") label: type: string description: Domain label without TLD sld: type: - string - 'null' description: Second-level domain punycode: type: boolean description: Whether domain uses punycode encoding lifecycle: type: object description: 'Domain lifecycle: dates, ownership, renewal, auto-renewal' properties: purchasedAt: type: - string - 'null' description: Purchase date (ISO 8601) expiresAt: type: - string - 'null' description: Expiration date (ISO 8601) transferStatus: type: string description: 'Transfer status: "none" or "pending"' isExternallyOwned: type: boolean description: Whether domain is in registrar custody (externally owned) reverse: type: boolean description: Whether reverse resolution is enabled renewal: type: - object - 'null' description: Renewal eligibility and pricing properties: isEligible: type: boolean description: Whether domain is eligible for renewal period: type: object properties: min: type: number description: Minimum renewal years max: type: number description: Maximum renewal years increments: type: number description: Renewal year increments pricePerYear: type: number description: Renewal price per year in cents (USD) pricePerYearFormatted: type: string description: Formatted price (e.g., "$12.99") autoRenewal: type: - object - 'null' description: Auto-renewal subscription status properties: status: type: string description: Subscription status expiresAt: type: - string - 'null' description: Next renewal date (ISO 8601) flags: type: - object - 'null' description: Domain-level flags (WHOIS privacy, transfer lock, etc.) properties: DNS_TRANSFER_OUT: type: object properties: status: type: string enum: - ENABLED - DISABLED description: Transfer lock status DNS_WHOIS_PROXY: type: object properties: status: type: string enum: - ENABLED - DISABLED description: WHOIS privacy status DNS_RESOLUTION: type: object properties: status: type: string enum: - ENABLED - DISABLED DNS_DELETE: type: object properties: status: type: string enum: - ENABLED - DISABLED DNS_UPDATE: type: object properties: status: type: string enum: - ENABLED - DISABLED DNS_UNS_TOKENIZATION: type: object properties: status: type: string enum: - ENABLED - DISABLED dns: type: object description: DNS configuration from cache (nameservers, hosting, DNSSEC) properties: nameservers: type: - object - 'null' properties: status: type: string enum: - default - custom - none description: 'Nameserver status: default (UD-managed), custom (external), none' nameservers: type: array items: type: string description: Nameserver hostnames hosting: type: - array - 'null' items: type: object properties: subName: type: string description: Subdomain name type: type: string description: Hosting type (REDIRECT_301, REDIRECT_302, UD_PROFILE) targetUrl: type: - string - 'null' description: Target URL for redirect status: type: string description: Hosting status (ACTIVE, INACTIVE, PENDING) description: URL redirects and hosting rules dnssec: type: - object - 'null' properties: enabled: type: boolean description: Whether DNSSEC is enabled valid: type: boolean description: Whether DNSSEC validation passes marketplace: type: object description: Marketplace listing and engagement metrics properties: listing: type: - object - 'null' description: Active listing details properties: id: type: number price: type: number description: Listing price in cents status: type: string createdAt: type: string updatedAt: type: string views: type: number listingSettings: type: - object - 'null' offersCount: type: number description: Number of active offers leadsCount: type: number description: Number of buyer leads watchlistCount: type: number description: Number of users watching this domain tags: type: array items: type: string description: Tags applied to this domain pendingOperations: type: array description: Pending DNS/domain operations items: type: object properties: id: type: string type: type: string status: type: string createdAt: type: string error: type: string description: Error message if retrieval failed availableTags: type: array items: type: string description: All tags you've created (useful for adding tags to other domains) securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT