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