All API endpoints are available for public use without any authentication required. Requests originating from the same IP address are limited to a maximum of 10 requests per day.
Requests made using authenticated API key are limited to a maximum of 200,000 requests per day. Authenticated API key access is available only to PRO plan users on the hosted btcnodes.io service. This standalone deployment serves the documented local crawler/export endpoints without fabricating hosted account state. Python code sample to perform authenticated API request: sample-bitnodes-auth-api-client.py.
The remaining limit available for the day is included in the ratelimit-remaining response header. Subsequent requests after ratelimit-remaining: 0 return HTTP 429 Too Many Requests with a retry-after response header containing waiting time in seconds before the daily limit is restored.
Available endpoints:
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 that are available in the crawler export directory, latest first. Snapshots at this granularity are kept locally according to the export files mounted in this deployment; long-term historical snapshots are available from the btcnodes.io Archive page.
GET /api/v1/snapshots/
Parameters: page and limit. Limit is capped at 100.
Latest snapshot rows can also be fetched directly:
GET /api/v1/snapshots/latest/ GET /api/v1/snapshots/<TIMESTAMP>/
Use field=coordinates for unique latitude and longitude pairs, field=user_agents for unique user agents, or field=top for top ASNs and top user agents. Default public snapshot responses are keyed by ADDRESS:PORT and use the current 5-field export format: protocol version, user agent, connected since, services, and height. Use /api/v1/nodes/ for the paginated searchable list with location and network metadata.
List reachable nodes from the latest snapshot as a paginated searchable node list with location and network metadata. Use /api/v1/snapshots/latest/ for the raw public 5-field snapshot export.
GET /api/v1/nodes/
Parameters: page, limit, country, and q.
List all IPv4/IPv6/.onion addresses observed by the local btcnodes.io crawler export.
GET /api/v1/addresses/
Parameters: page, limit, and q. Limit is capped at 100 by the public API shape.
Check whether a Bitcoin node is currently accepting incoming connections. This is the same endpoint used by the public Check Your Node form.
POST /api/v1/checknode/
Parameters: address and port. Port must be between 1024 and 65535. The response includes ok, reachable, address, port, optional user_agent, and an error field when the connection cannot be completed.
Get status for a node in the latest crawler export. If a node is not present in the latest snapshot, status is returned as DOWN.
GET /api/v1/nodes/<ADDRESS>-<PORT>/
Values in the data array represent protocol version, user agent, connected since, services, height, hostname, city, country code, latitude, longitude, timezone, ASN, and organization name.
Get daily, weekly and monthly round-trip time (RTT) data for a node. When live RTT samples are available, the response includes public-compatible daily_rtt, weekly_rtt, and monthly_rtt arrays of t/v points derived from real pinger samples, plus local summary windows daily, weekly, and monthly. If no live samples have been observed for the node, the endpoint returns 501 unavailable rather than fabricated values.
GET /api/v1/nodes/<ADDRESS>-<PORT>/rtt/
The local compatibility endpoint /api/v1/nodes/<ADDRESS>-<PORT>/latency/ exposes recent pinger samples when available.
Store operator-submitted Bitcoin address metadata for a node in local Redis. This standalone deployment marks submitted metadata as unverified because it does not include the original hosted ownership-verification service.
POST /api/v1/nodes/<ADDRESS>-<PORT>/
Parameters: bitcoin_address and optional url. At least one metadata field is required. The response echoes submitted values under submitted with verified: false unless an external ownership-verification service has been configured.
List nodes according to a btcnodes.io-style Peer Index derived from live snapshot fields available in this repository.
GET /api/v1/nodes/leaderboard/
Parameters: page, limit, and q. The response includes original field names such as vi, si, hi, ai, pi, dli, dui, wli, wui, mli, mui, nsi, ni, bi, peer_index, and rank.
Get ranking and Peer Index fields for a single node from the latest export.
GET /api/v1/nodes/leaderboard/<ADDRESS>-<PORT>/
List recent inventory announcements with propagation stats available through the data propagation endpoint. btcnodes.io samples transaction and block invs observed by the local pinger.
GET /api/v1/inv/
Parameters: page, limit, and type. Use type=1 for transactions or type=2 for blocks.
Rows include the public-compatible inv_hash field plus local convenience fields such as hash, type, latest_seen, and nodes.
Inspect the nodes that announced a selected transaction or block hash. Responses are generated from Redis tinv:* and binv:* keys; if no live announcements have been observed yet, the index returns 501 unavailable rather than fabricated values.
GET /api/v1/inv/<INV_HASH>/
When live samples are present, the response includes public-compatible stats fields: mean, std, min, 50%, 90%, max, and head.
Get a list of reachable nodes to bootstrap your Bitcoin client connection to the Bitcoin network.
DNS <RECORD> <PREFIX>seed.btcnodes.io
IPv4 nodes are returned via A records, IPv6 nodes are returned via AAAA records and .onion nodes are returned via TXT records.
seed.btcnodes.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, x408.seed.btcnodes.io returns a list of reachable nodes that have both NODE_WITNESS (8) and NODE_NETWORK_LIMITED (1024) enabled; 8 + 1024 = 1032 = 0x408.
Seeder health can also be inspected as JSON:
GET /api/v1/seeders/
The JSON response includes configured seeder names, live A/AAAA resolution counts, ok/failing summary, and the same explicit unavailable history status used by the DNS Seeders Health page when seven-day hosted seeder history is not configured.