Blockchain-DNS Resolver
This repository will later contain the implementation for a web resolver of BDNS domains.
Right now it contains description of the blockchain-dns.info's public resolver API. This API is used by BDNS browser extensions.
Blockchain-DNS.info API
This document describes API v0, i.e .the basic level that will remain stable and be available for the lifetime of the project. Subsequent versions will be made available under separate paths.
Request
All requests are stateless GET with no authentication built using this URL format:
https://BASE_DOMAIN/FUNC/DOMAIN_TO_RESOLVE?QUERY
BASE_DOMAIN is one of the following API servers (it doesn't matter which one is used):
bdns.at
bdns.by
bdns.co
bdns.im
bdns.io
bdns.link
bdns.nu
bdns.pro
b-dns.se
These domains are no more functional (details): bdns.bz, bdns.name, bdns.us, bdns.ws, bdns.su, bdns.tv, bdns.mn.
There are also several unlisted API servers that you can find by scanning existing bdns.* domains (they might use invalid/self-signed HTTPS certs).
DOMAIN_TO_RESOLVE is the domain name of interest, belonging to one of the supported TLDs:
| TLD | Authority |
|---|---|
| .bit |  Namecoin |
| .emc |  Emercoin |
| .coin | Emercoin |
| .lib | Emercoin |
| .bazar | Emercoin |
| .bbs | OpenNIC |
| .chan | OpenNIC |
| .cyb | OpenNIC |
| .dyn | OpenNIC |
| .geek | OpenNIC |
| .gopher | OpenNIC |
| .indy | OpenNIC |
| .libre | OpenNIC |
| .neo | OpenNIC |
| .null | OpenNIC |
| .o | OpenNIC |
| .oss | OpenNIC |
| .oz | OpenNIC |
| .parody | OpenNIC |
| .pirate | OpenNIC |
| .ku | OpenNIC |
| .te | OpenNIC |
| .ti | OpenNIC |
| .uu | OpenNIC |
QUERY is FUNC-dependent and is the only optional part built using regular URL encoding.
Resolve (r)
FUNC = r.
Recognized QUERY parameters:
| Parameter | Example | Description |
|---|---|---|
| n | 3 | Maximum number of IPs to return (default: all). |
| r | 0 | Shuffle returned IPs (default: yes, 0 to disable and return in DNS order). |
Response
There are three possible responses differentiated by HTTP status code:
| Code | Description |
|---|---|
| 200 | Response contains list of IPs, separated by CR/LF (essentially putting every IP on its own line). |
| 404 | Response contains string nx. This may indicate that the domain doesn't exist, has no IP entries (which is common for Namecoin and Emercoin) |
| 500 | Response is irrelevant. Added 20 Oct 2017 to indicate a server error. Clients should retry at another endpoint. |
First two response types are cached for approximately 10 minutes.
Examples
Simple query: https://bdns.io/r/nx.bit
Query with preserved order of IP entries: https://bdns.at/r/t411.bit?r=0
First IP entry, preserving order: https://bdns.bz/r/rutracker.lib?n=1&r=0
A single random entry: https://bdns.ws/r/register.bbs?n=1
Exists (x)
FUNC = x.
There are no recognized QUERY parameters:
Response
There are three possible responses differentiated by HTTP status code:
| Code | Description |
|---|---|
| 200 | Response contains string xx, indicating that DOMAIN_TO_RESOLVE exists. |
| 404 | Response contains string nx, indicating that there is no record for the given domain name in the blockchain. |
| 500 | Response is irrelevant. Indicates a server error. Clients should retry at another endpoint. |
First two response types are cached for approximately 10 minutes.
r vs x
r expects a domain to exist and to resolve to valid IPs. Even if a domain doesn't resolve (you cannot browse it), it may still exist in the blockchain meaning it cannot be registered.
x only checks for domain existence. If it returns nx then the name can be registered.
Examples
https://bdns.io/x/randomrumble.lib
For a practical application (CORS+XHR) see blockchain-dns.info's own name availability checker.