openapi: 3.0.0
info:
  title: Unstoppable Partner API
  description: 'The Partner API requires you to be an authorized seller. To register as a partner and integrate our APIs into your applications, check our [Register as a Partner](https://docs.unstoppabledomains.com/partner/) guide.'
  contact:
    email: dev@unstoppabledomains.com
  version: 2.0.0
externalDocs:
  description: Unstoppable Domains Developer Documentation Portal
  url: https://docs.unstoppabledomains.com
servers:
  - url: https://unstoppabledomains.com/api/v2/resellers
tags:
  - name: orders
    description: Create an order and get the status of orders
  - name: domains
    description: Check domain availability and suggestions for purchase or claim
paths:
  /{resellerID}/domains/{domainName}:
    parameters:
      - name: resellerID
        in: path
        description: Resellers ID obtained from UD team after registration as a Partner
        required: true
        schema:
          type: string
          example: udtesting
      - name: domainName
        in: path
        required: true
        schema:
          type: string
          example: beresnev.crypto
    get:
      tags:
        - domains
      summary: Domain name availability
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainAvailabilityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '401':
          description: Partner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResellerNotFound'
  /{resellerID}/domains/suggestions:
    parameters:
      - name: resellerID
        in: path
        description: ID obtained from UD team
        required: true
        schema:
          type: string
          example: udtesting
      - name: search
        in: query
        description: Keywords that will be used to build domain suggestions. Can be TLD or domain name.
        required: false
        style: form
        explode: true
        schema:
          type: array
          example:
            - 'test.crypto'
            - 'hello'
            - 'domains.888'
          items:
            type: string
            example: 'ryan.crypto'
      - name: tlds
        in: query
        description: Limit suggestions output by specific TLDs (crypto, dao, etc.)
        required: false
        style: form
        explode: true
        schema:
          type: array
          example:
            - 'crypto'
            - 'nft'
            - '888'
          items:
            type: string
            example: 'dao'
    get:
      tags:
        - domains
      summary: Get domains suggestions
      description:
        This endpoint is used to provide domains variants based on provided domains and label. Method will provide domains similar to domains provided in domains parameter.
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainSuggestions'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '401':
          description: Partner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResellerNotFound'
  /{resellerID}/domains/suggestions/free:
    parameters:
      - name: resellerID
        in: path
        description: ID obtained from UD team
        required: true
        schema:
          type: string
          example: udtesting
      - name: search
        in: query
        description: Keywords that will be used to build FREE domain suggestions. Can be TLD or domain name.
        required: false
        style: form
        explode: true
        schema:
          type: array
          example:
            - 'fancyfox123.crypto'
            - 'firstname'
            - 'domainsforfree1.888'
          items:
            type: string
            example: 'ryan.crypto'
      - name: tlds
        in: query
        description: Limit suggestions output by specific TLDs (crypto, dao, etc.)
        required: false
        style: form
        explode: true
        schema:
          type: array
          example:
            - 'crypto'
            - 'nft'
            - '888'
          items:
            type: string
            example: 'dao'
    get:
      tags:
        - domains
      summary: Get free domains suggestions
      description:
        This endpoint is used to provide free domains suggestions if a partner is eligible for free domains. If partner isn't eligible for free domains suggestions - endpoint will return error.
      responses:
        '200':
          description: Valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainSuggestions'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '401':
          description: Partner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResellerNotFound'
  /{resellerID}/domains/{domainName}/reserve:
    post:
      summary: Reserve free domain name for period of time
      description: Reserve free domain name for external user identifier. Usually it's a user identifier or email in a partner's system. Domain name becomes unavailable for selling and claiming to anyone except identity that reserved the domain. Only one domain could be reserved per resellerIdentityKey. Reserve time is 168 hours.
      security:
        - ApiSecret: []
      parameters:
      - name: resellerID
        in: path
        description: Resellers ID obtained from UD team after registration as a partner
        required: true
        schema:
          type: string
          example: udtesting
      - name: domainName
        in: path
        required: true
        schema:
          type: string
          example: beresnev.crypto
      tags:
        - domains
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainReverseRequest'
      responses:
        '200':
          description: Valid
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '401':
          description: Partner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResellerNotFound'
  /{resellerID}/orders:
    parameters:
      - name: resellerID
        in: path
        description: ID obtained from UD team
        required: true
        schema:
          type: string
          example: udtesting
    post:
      security:
        - {}
        - ApiSecret: []
      tags:
        - orders
      summary: Buy a domain or claim for free
      description:
        This API endpoint is used for buying domains from UD. The blockchain needs time before a transaction is mined. In rare cases, it is possible for someone to front run your purchase, which would result in an order being cancelled. We expect this to happen in less than 1 out of 10000 cases. Please make sure you are using the 'Order Status' endpoint and wait until the transaction is mined.

        Endpoint requires either email or owner address. If email is provided - domain will be linked to Unstoppable website account. If owner address is provided - domain will be minted right into crypto wallet. Optionally user can specify domain records that will be added to the domain once it's minted (i.e. if owner address is provided)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainOrderRequest'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainOrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
        '401':
          description: Partner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResellerNotFound'
  /{resellerID}/orders/{orderNumber}:
    parameters:
      - name: resellerID
        in: path
        description: ID obtained from UD team
        required: true
        schema:
          type: string
          example: udtesting
      - name: orderNumber
        in: path
        description: ID of the order
        required: true
        schema:
          type: string
          example: -Lm9wiYytgrpf4YCWYv6
    get:
      description: Use this endpoint to pull the status of the order
      summary: Get order status by order number
      tags:
        - orders
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainOrderResponse'
        '401':
          description: Partner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralResellerNotFound'
        '404':
          description: Order Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralNotFoundError'
components:
  schemas:
    DomainReverseRequest:
      type: object
      properties:
        resellerIdentityKey:
          type: string
          example: 'example@user.com'
          description: 'Unique external identifier of user. Could by ANY string value. Unstoppable will try to match internal and external user id.'
    OrderSecurity:
      type: object
      description: Additional security parameters. Required if the payment method is 'free'.
      required:
        -  type
        -  identifier
      properties:
        type:
          type: string
          description: Security method providers
          enum:
            - 'fingerprintjs'
          example: 'fingerprintjs'
        identifier:
          type: string
          description: The device identifier. In FingerprintJS, it would be the Visitor ID.
          example: 'i2udKSvRFcN1wOqGLk3J'
    OrderPayment:
      type: object
      description: Payment type and parameters
      properties:
        method:
          type: string
          enum:
            - 'free'
            - 'coinbase'
            - 'stripe'
        properties:
          description: Additional payment method properties
          anyOf:
            - $ref: '#/components/schemas/FreePaymentProperties'
            - $ref: '#/components/schemas/StripePaymentProperties'
            - $ref: '#/components/schemas/CoinbasePaymentProperties'
      example:
        method: stripe
        properties:
          tokenId: tok_1FAeVFG8PQyZCUJhJp7emswP
    FreePaymentProperties:
      type: object
      description: Properties for the free payment method
    CoinbasePaymentProperties:
      type: object
      description: Properties for the stripe payment method
    StripePaymentProperties:
      type: object
      description: Properties for the stripe payment method
      example:
        tokenId: tok_1FAeVFG8PQyZCUJhJp7emswP
    DomainOrderRequest:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/OrderPayment'
        security:
          type: array
          items:
            $ref: '#/components/schemas/OrderSecurity'
        domains:
          type: array
          items:
            type: object
            required:
              - 'name'
            properties:
              name:
                type: string
                example: matt.dao
                description: Domain name
              ownerAddress:
                type: string
                example: '0x6EC0DEeD30605Bcd19342f3c30201DB263291589'
                description: Domain recipient wallet address. Email or owner should be provided in order to detect domain receiver. If owner is provided - domain will be minted to the owner address.
                nullable: true
              email:
                type: string
                example: matt@unstoppabledomains.com
                description: Domain recipient email. Email is identifier of Unstoppalbe website account. Email or owner should be provided in order to detect domain receive:. If email is provided - domain will be linked to email address and could be claimed on chain later.
                nullable: true
              resolution:
                description: Mint domain with predefined records. Requires owner field.
                externalDocs:
                  description: Domain records reference
                  url: https://docs.unstoppabledomains.com/domain-registry-essentials/records-reference
                type: object
                nullable: true
                additionalProperties:
                  type: string
                example:
                  crypto.ETH.address: '0x6EC0DEeD30605Bcd19342f3c30201DB263291589'
                  crypto.BTC.address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh'
              resellerIdentityKey:
                type: string
                nullable: true
                description: Field is required if domain was reserved. Value should be the same as it was when domain was reserved.
    DomainOrderResponse:
      type: object
      properties:
        orderNumber:
          type: string
          description: orderID used for later status check
          example: -Lm9wiYytgrpf4YCWYv6
        payment:
          $ref: '#/components/schemas/OrderPayment'
        total:
          type: integer
          description: Total price in USD Cents. For example $10 = 1000.
          example: 0
        items:
          type: array
          items:
            type: object
            properties:
              domain:
                $ref: '#/components/schemas/Domain'
              mintingTransaction:
                type: object
                properties:
                  id:
                    type: number
                    example: 101
                    description: Transaction identifier in Unstoppable system
                  blockchain:
                    $ref: '#/components/schemas/Blockchain'
                  networkId:
                    type: number
                    example: 1
                    description: Id of blockchain network (mainnet or testnet)
                  hash:
                    type: string
                    description: Hash of minting transaction
                    example: '0x5588e089b59458b4b34716c3299418e4ea449efbff35c8810f7c189160b1ed57'
                  blockExplorerUrl:
                    type: string
                    description: A link to track transaction status
                    example: 'https://etherscan.io/tx/0x5698544cecaa05f7d155ff59fea48ef28cbd72068c7c3817987a19816d74fb9b'
                  statusGroup:
                    type: string
                    description: Transaction status
                    example: Pending
                    enum:
                      - Pending
                      - Failed
                      - Completed
    DomainSuggestions:
      type: array
      example:
        - name: thetest.crypto
          price: 20000
        - name: hellos.crypto
          price: 20000
        - name: thedomains.888
          price: 200000
      items:
        type: object
        properties:
          name:
            type: string
            description: Domain name
            example: matt.crypto
            nullable: false
          price:
            description: 'Domain price in USD cents. For example 20000 cents = 200 USD'
            type: integer
            example: 20000
            nullable: false
    Domain:
      type: object
      properties:
        id:
          type: number
          example: 1001
          description: Id of entity
        name:
          type: string
          example: matt.dao
          description: Domain name
        ownerAddress:
          type: string
          description: Recipient address
          example: '0x6EC0DEeD30605Bcd19342f3c30201DB263291589'
          nullable: true
        resolver:
          type: string
          nullable: true
          description: Resolver address
          example: '0x049aba7510f45BA5b64ea9E658E342F904DB358D'
        registryAddress:
          type: string
          description: Registry address
          example: '0x049aba7510f45BA5b64ea9E658E342F904DB358D'
          nullable: true
        networkId:
          type: number
          example: 1
          description: Id of blockchain network (mainnet or testnet)
        resolution:
          description: Mint domain with predefined records. Requires owner field.
          externalDocs:
            description: Domain records reference
            url: https://docs.unstoppabledomains.com/domain-registry-essentials/records-reference
          type: object
          nullable: true
          additionalProperties:
            type: string
          example:
            crypto.ETH.address: '0x6EC0DEeD30605Bcd19342f3c30201DB263291589'
            crypto.BTC.address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh'
        blockchain:
          $ref: '#/components/schemas/Blockchain'
        freeToClaim:
          type: boolean
          example: true
          default: true
          description: 'Whether domain claiming fee will be paid by Unstoppable Domains'
        node:
          type: string
          description: 'Domain name hash'
          example: '0x756e4e998dbffd803c21d23b06cd855cdc7a4b57706c95964a37e24b47c10fc9'
          externalDocs:
            description: 'Namehashing essentials'
            url: https://docs.unstoppabledomains.com/domain-registry-essentials/namehashing

    DomainAvailabilityResponse:
      type: object
      properties:
        domain:
          $ref: '#/components/schemas/Domain'
        availability:
          type: object
          properties:
            registered:
              type: boolean
              description: Information if a domain is registered or not
              example: false
            protected:
              type: boolean
              description: Information if a domain is protected or not
              example: false
            price:
              description: Domain price in USD Cents. For example $10 = 1000. Might be null if domain is not available for sale.
              type: integer
              example: 1000
              nullable: true
            availableForFree:
              description: Whether domain is available for free for the partner
              type: boolean
              example: false
            test:
              description: Whether domain is in test namespace
              type: boolean
              example: true
    Blockchain:
      type: string
      description: Which chain is being used to mint a domain
      example: 'MATIC'
      enum:
        - 'MATIC'
        - 'ETH'
        - 'ZIL'
    GeneralError:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/BasicError'
        constraints:
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/BasicError'
    GeneralResellerNotFound:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ResellerNotFoundError'
    GeneralNotFoundError:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NotFoundError'
    BasicError:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: 'ERROR_CODE'
        message:
          type: string
          description: User friendly description of above code
          example: 'Error code explanation'
        field:
          type: string
          description: Estimate error field
          example: 'some field'
        value:
          description: Value of error field
          example: 'some value'
        status:
          type: number
          description: Status code of the response
          example: 400
    NotFoundError:
      type: object
      properties:
        code:
          type: string
          example: 'NOT_FOUND'
        message:
          type: string
          example: 'Not Found'
        field:
          type: string
          description: Estimate error field
          example: null
        value:
          description: Value of error field
          example: null
        status:
          type: number
          example: 404
    ResellerNotFoundError:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: 'RESELLER_NOT_FOUND'
        message:
          type: string
          description: User friendly description of above code
          example: 'Reseller ID not found'
        field:
          type: string
          description: Estimate error field
          example: null
        value:
          description: Value of error field
          example: null
        status:
          type: number
          description: Status code of the response
          example: 401
  securitySchemes:
    ApiSecret:
      type: http
      scheme: bearer
      bearerFormat: JWT