Bitnodes API v1.0

Total nodes n/a United States n/a AS14618 AMAZON-AES n/a

Bitnodes API v1.0

All API endpoints are available for public use without any authentication required. Requests originating from the same IP address is limited to a maximum of 5000 requests per day.

Available endpoints:

List snapshots
List nodes
Node status
Node latency
Leaderboard
Node ranking
List data propagation
Data propagation
DNS seeder

New snapshot is generally available approximately every 5 minutes, so it is recommended that periodical requests are made at most every 5 minutes. Timestamps used in requests and responses are in Unix time in seconds unless specified otherwise in the documentation below.

List Snapshots

List all snapshots that are available on the server from the latest to oldest snapshot. Snapshots are currently kept on the server for up to 60 days.

GET https://bitnodes.io/api/v1/snapshots/

Parameters:

page (optional) - Current page (1).
limit (optional) - Number of snapshots to return (10). Max. 100.

Example:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/snapshots/
{
    "count": 12015,
    "next": "https://bitnodes.io/api/v1/snapshots/?page=2",
    "previous": null,
    "results": [
        {
            "url": "https://bitnodes.io/api/v1/snapshots/1656292357/",
            "timestamp": 1656292357,
            "total_nodes": 14980,
            "latest_height": 742491
        },
        .
        .
        {
            "url": "https://bitnodes.io/api/v1/snapshots/1656288285/",
            "timestamp": 1656288285,
            "total_nodes": 15456,
            "latest_height": 742484
        }
    ]
}

List Nodes

List all reachable nodes from a snapshot.

GET https://bitnodes.io/api/v1/snapshots/<TIMESTAMP>/

<TIMESTAMP> can be replaced with "latest" to get the list of all reachable nodes from the latest snapshot.

Parameters:

field (optional) - Specify field=coordinates to get the list of unique latitude and longitude pairs or field=user_agents to get the list of unique user agents instead of the full information listed below.

Pagination parameters are not available for this endpoint, as it simply returns the raw snapshot from the export directory used by the crawler. Values in each array in the response represent the following information:

Protocol version
User agent
Connected since
Services
Height
Hostname
City
Country code
Latitude
Longitude
Timezone
ASN
Organization name

Examples:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/snapshots/1656292357/
{
    "timestamp": 1656291918,
    "total_nodes": 15037,
    "latest_height": 742491,
    "nodes": {
        "qp6ro3mnogsi7manj3gdt5xhic43n45fumvg527z5uvtoy3vyp7re6yd.onion:8333": [
            70016,
            "/Satoshi:22.0.0/",
            1656188302,
            1037,
            742491,
            null,
            null,
            null,
            0.0,
            0.0,
            null,
            "TOR",
            "Tor network"
        ],
        .
        .
        "93.138.52.93:8333": [
            70016,
            "/Satoshi:22.0.0/",
            1656217338,
            1032,
            742491,
            "93-138-52-93.adsl.net.t-com.hr",
            "Zagreb",
            "HR",
            45.8293,
            15.9793,
            "Europe/Zagreb",
            "AS5391",
            "Hrvatski Telekom d.d."
        ]
    }
}

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/snapshots/latest/?field=coordinates
{
    "timestamp": 1656292357,
    "total_nodes": 14980,
    "latest_height": 742491,
    "coordinates": [
        [
            38.1,
            -7.5
        ],
        .
        .
        [
            44.3,
            -89.9
        ]
    ]
}

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/snapshots/latest/?field=user_agents
{
    "timestamp": 1656292357,
    "total_nodes": 14980,
    "latest_height": 742491,
    "user_agents": [
        "/Satoshi:22.0.0(FutureBit-Apollo-Node)/",
        .
        .
        "/Classic:1.2.0(EB3.7)/"
    ]
}

Node Status

Get status for an activated node. New node must be activated separately, i.e. from https://bitnodes.io/nodes/<ADDRESS>-<PORT>/, before it can be accessed from this endpoint.

GET https://bitnodes.io/api/v1/nodes/<ADDRESS>-<PORT>/

Status string in the response indicates the status of this node as of the last snapshot. Possible values for status are:

PENDING - The node has just been activated pending availability of a new snapshot.
UP - The node is currently reachable.
DOWN - The node is currently unreachable.

Values in the data array represent the following information:

Protocol version
User agent
Connected since
Services
Height
Hostname
City
Country code
Latitude
Longitude
Timezone
ASN
Organization name

Example:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/nodes/128.65.194.136-8333/
{
    "address": "128.65.194.136",
    "status": "UP",
    "data": [
        70016,
        "/Satoshi:23.0.0/",
        1656292327,
        1033,
        742491,
        "c814.synology.infomaniak.ch",
        null,
        "CH",
        47.1449,
        8.1551,
        "Europe/Zurich",
        "AS29222",
        "Infomaniak Network SA"
    ],
    "mbps": "4.173959"
}

Node Latency

Get daily, weekly and monthly latency data for an activated node. New node must be activated separately, i.e. from https://bitnodes.io/nodes/<ADDRESS>-<PORT>/, before it can be accessed from this endpoint.

GET https://bitnodes.io/api/v1/nodes/<ADDRESS>-<PORT>/latency/

The daily_latency array contains the daily average latency for this node formatted as a time series data points with 15-minute interval and up to 1 day retention. The weekly_latency array contains the weekly average latency for this node formatted as a time series data points with 1-hour interval and up to 1 week retention. The monthly_latency array contains the monthly average latency for this node formatted as a time series data points with 1-day interval and up to 1 year retention. Each data point has the following keys:

t - Timestamp of this data point.
v - Average latency of this node in milliseconds; v = -1 (node is unreachable), v = 0 (node is reachable but no latency data is available).

Example:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/nodes/128.65.194.136-8333/latency/
{
    "daily_latency": [
        {
            "t": 1656206100,
            "v": -1
        },
        .
        .
        {
            "t": 1656292500,
            "v": -1
        }
    ],
    "weekly_latency": [
        {
            "t": 1655686800,
            "v": 15
        },
        .
        .
        {
            "t": 1656291600,
            "v": 15
        }
    ],
    "monthly_latency": [
        {
            "t": 1649548800,
            "v": -1
        },
        .
        .
        {
            "t": 1656288000,
            "v": 15
        }
    ]
}

Leaderboard

List all activated nodes according to their Peer Index (PIX) in descending order.

GET https://bitnodes.io/api/v1/nodes/leaderboard/

Parameters:

page (optional) - Current page (1).
limit (optional) - Number of nodes to return (10). Max. 100.

Example:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/nodes/leaderboard/
{
    "count": 10258,
    "next": "https://bitnodes.io/api/v1/nodes/leaderboard/?page=2",
    "previous": null,
    "results": [
        {
            "node": "37.191.249.99:8333",
            "vi": "1.0000",
            "si": "1.0000",
            "hi": "1.0000",
            "ai": "1.0000",
            "pi": "1.0000",
            "dli": "1.0000",
            "dui": "1.0000",
            "wli": "1.0000",
            "wui": "1.0000",
            "mli": "1.0000",
            "mui": "0.9856",
            "nsi": "0.9000",
            "ni": "0.0058",
            "bi": "1.0000",
            "peer_index": "9.2082",
            "rank": 1
        },
        .
        .
        {
            "node": "62.122.173.171:8333",
            "vi": "1.0000",
            "si": "1.0000",
            "hi": "1.0000",
            "ai": "0.9283",
            "pi": "1.0000",
            "dli": "1.0000",
            "dui": "1.0000",
            "wli": "1.0000",
            "wui": "1.0000",
            "mli": "1.0000",
            "mui": "0.9778",
            "nsi": "0.9000",
            "ni": "0.0030",
            "bi": "1.0000",
            "peer_index": "9.1493",
            "rank": 10
        }
    ]
}

Node Ranking

Get ranking and associated Peer Index (PIX) data for an activated node. New node must be activated separately, i.e. from https://bitnodes.io/nodes/<ADDRESS>-<PORT>/, before it can be accessed from this endpoint.

GET https://bitnodes.io/api/v1/nodes/leaderboard/<ADDRESS>-<PORT>/

Example:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/nodes/leaderboard/128.65.194.136-8333/
{
    "node": "128.65.194.136:8333",
    "vi": "1.0000",
    "si": "1.0000",
    "hi": "1.0000",
    "ai": "0.0000",
    "pi": "1.0000",
    "dli": "1.0000",
    "dui": "0.9588",
    "wli": "1.0000",
    "wui": "0.9645",
    "mli": "1.0000",
    "mui": "0.9873",
    "nsi": "0.5000",
    "ni": "0.0013",
    "bi": "0.0000",
    "peer_index": "7.4371",
    "rank": 3619
}

List Data Propagation

List up to 100,000 recent invs (latest to oldest) with propagation stats available through data propagation endpoint. Bitnodes samples at most only 100 transaction invs per block.

GET https://bitnodes.io/api/v1/inv/

Parameters:

page (optional) - Current page (1).
limit (optional) - Number of invs to return (100). Max. 1000.

Example:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/inv/
{
    "count": 100000,
    "next": "https://bitnodes.io/api/v1/inv/?page=2",
    "previous": null,
    "results": [
        {
            "inv_hash": "312a249aeca97a7b1af4a137403e3dce3523daa110507056fb3b447ad0d9706e"
        },
        .
        .
        {
            "inv_hash": "6a9e41523278e727f95c509c02da01fba105d0b274ebad841549588f90527806"
        }
    ]
}

Data Propagation

Get inv propagation stats in milliseconds for a block or transaction broadcasted over 8 hours ago. Stats are calculated based on the inv arrival times (UNIX time in milliseconds) from the first 1000 nodes.

GET https://bitnodes.io/api/v1/inv/<INV_HASH>/

Values in stats represent the following information:

head - Arrival times for the first 10 (or 1000 for newer inv) nodes in a list of ["<ADDRESS>:<PORT>", <TIMESTAMP>].
min - Delta for earliest arrival time. Value can be 0 if the delta is less than 1 millisecond.
max - Delta for latest arrival time.
mean - Average of deltas.
std - Standard deviation of deltas.
50% - 50th percentile of deltas.
90% - 90th percentile of deltas.

Example:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/inv/312a249aeca97a7b1af4a137403e3dce3523daa110507056fb3b447ad0d9706e/
{
    "inv_hash": "312a249aeca97a7b1af4a137403e3dce3523daa110507056fb3b447ad0d9706e",
    "stats": {
        "std": 938,
        "head": [
            [
                "35.195.234.115:8333",
                1656255140959
            ],
            .
            .
            [
                "90.156.26.148:8333",
                1656255145150
            ]
        ],
        "min": 6,
        "max": 4191,
        "50%": 2736,
        "90%": 4014,
        "mean": 2696
    }
}

DNS Seeder

Get a list of reachable nodes to bootstrap your Bitcoin client connection to the Bitcoin network. The DNS records are generated using seeder.py.

DNS <RECORD> <PREFIX>seed.bitnodes.io

IPv4 nodes are returned via A records, IPv6 nodes are returned via AAAA records and .onion nodes are returned via TXT records.

seed.bitnodes.io returns a list of reachable nodes with NODE_NETWORK (1) service bit set. Prefix x[hex] is accepted to filter nodes by specific services. For example, x409.seed.bitnodes.io returns a list of reachable nodes with services set to 1033 (hex(1033) = '0x409'), i.e. NODE_NETWORK (1), NODE_WITNESS (8), NODE_NETWORK_LIMITED (1024).

Example:

$ dig A seed.bitnodes.io
seed.bitnodes.io.	60	IN	A	24.205.166.100
seed.bitnodes.io.	60	IN	A	31.125.188.214
seed.bitnodes.io.	60	IN	A	31.134.121.223
.
.
seed.bitnodes.io.	60	IN	A	202.239.42.192
seed.bitnodes.io.	60	IN	A	203.94.33.112
seed.bitnodes.io.	60	IN	A	217.73.80.104

$ dig AAAA seed.bitnodes.io
seed.bitnodes.io.	60	IN	AAAA	2001:8d8:939:1900::77:9e09
seed.bitnodes.io.	60	IN	AAAA	2400:2651:4740:3200:28:8248:42a:f007
seed.bitnodes.io.	60	IN	AAAA	240e:38a:8ab6:1e00:c23:65dd:84bf:7dad
.
.
seed.bitnodes.io.	60	IN	AAAA	2a02:7b40:50d0:e6aa::1
seed.bitnodes.io.	60	IN	AAAA	2a03:e2c0:1347::2
seed.bitnodes.io.	60	IN	AAAA	2a04:2180:1:7::7

$ dig A x409.seed.bitnodes.io
x409.seed.bitnodes.io.	60	IN	A	5.95.186.78
x409.seed.bitnodes.io.	60	IN	A	32.215.242.46
x409.seed.bitnodes.io.	60	IN	A	45.154.252.162
.
.
x409.seed.bitnodes.io.	60	IN	A	205.196.146.100
x409.seed.bitnodes.io.	60	IN	A	206.81.96.62
x409.seed.bitnodes.io.	60	IN	A	223.133.84.39

$ dig TXT x409.seed.bitnodes.io
x409.seed.bitnodes.io.	59	IN	TXT	"3gu5fqif5ymac7pejh7k5nm44kinli4dte4z3vdo4qh5xyrnbladmgyd.onion"
x409.seed.bitnodes.io.	59	IN	TXT	"3r73tz653kjr4w7cpjnjor2qrwirkbpslcuc5mbicvf34wbtvn47lpid.onion"
x409.seed.bitnodes.io.	59	IN	TXT	"3rrrzxcb5ep32jphhsol6b54vs746sekmdvdmpe4laowcdfuacn5poid.onion"
.
.
x409.seed.bitnodes.io.	59	IN	TXT	"yxol6pltt3r6voqhd47vaalaezlwuwik3gai2lp645khmu374tlnnsid.onion"
x409.seed.bitnodes.io.	59	IN	TXT	"zmmtddrew2mjtghs7zjiyi2eelmyss7miyj2axzwfgnmvzthx7phevad.onion"
x409.seed.bitnodes.io.	59	IN	TXT	"zuhhv2ityiqumom5zzglxftfrh6aztu5vborgdnx7pivaqcmclyd53id.onion"

Join the Network

Be part of the Bitcoin network by running a Bitcoin full node, e.g. Bitcoin Core.

Use this tool to check if your Bitcoin client is currently accepting incoming connections from other nodes. Port must be between 1024 and 65535.

Start a Bitcoin full node on your computer to help validate and relay Bitcoin blocks and transactions by running this command:

$ curl https://bitnodes.io/install-full-node.sh | sh

Supported systems: Linux, Mac, BSD, Windows