Bitnodes API v1.0

Total nodes Loading

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 50 requests per day.

Requests made using authenticated API key is limited to a maximum of 200,000 requests per day. Authenticated API key access is available to users on PRO plan only. Python code sample to perform authenticated API request: sample-bitnodes-auth-api-client.py

The remaining limit you have available for the day is included in the ratelimit-remaining response header. Subsequent request after ratelimit-remaining: 0 will result in HTTP 429 Too Many Requests response with retry-after response header containing waiting time in seconds before your daily limit is restored.

Available endpoints:

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

New snapshot is generally available approximately every 10 minutes, so it is recommended that periodical requests are made at most every 10 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)/"
    ]
}

List Addresses

List all IPv4/IPv6/.onion addresses observed by the Bitnodes crawler in the Bitcoin peer-to-peer network.

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

Parameters:

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

Examples:

$ curl -H "Accept: application/json; indent=4" https://bitnodes.io/api/v1/addresses/
    "count": 3673724,
    "next": "https://bitnodes.io/api/v1/addresses/?page=2",
    "previous": null,
    "results": [
        {
            "address": "2a01:e34:ec76:c9d0:2520:5f4d:852d:3aa2",
            "port": 8333
        },
        .
        .
        {
            "address": "2601:602:8d00:7070:1868:945c:98e6:d35",
            "port": 8333
        }
    ]
}

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 1000 transaction invs per block.

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

Parameters:

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

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": "51b4cc62ca39f7f7d567b8288a5d73aa29e4e059282077b4fe06eb16db882f37"
        },
        .
        .
        {
            "inv_hash": "4cf13b495015d5b2face2a01dd9a02dcbce5cb19ac7b1c00115214e950be01b2"
        }
    ]
}

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/51b4cc62ca39f7f7d567b8288a5d73aa29e4e059282077b4fe06eb16db882f37/
{
    "inv_hash": "51b4cc62ca39f7f7d567b8288a5d73aa29e4e059282077b4fe06eb16db882f37",
    "stats": {
        "min": 145,
        "max": 20010,
        "mean": 8836,
        "std": 4040,
        "50%": 8149,
        "90%": 17970,
        "head": [
            [
                "217.20.131.64:8333",
                1695996990986
            ],
            .
            .
            [
                "168.119.86.22:8333",
                1695997010996
            ]
        ]
    }
}

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 / Checksum: SHA256 (signature)