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.
The API is public in this deployment. It serves the documented local crawler/export endpoints without user accounts, API keys, or hosted account state.
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 BTC Nodes 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, I2P, and CJDNS addresses observed by the local BTC Nodes 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 BTC Nodes-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. BTC Nodes 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 native BTC Nodes software and policy distribution data calculated from the current crawler snapshot. The response includes implementation share, Core/Knots release widgets, OP_RETURN policy grouping, BIP-110 node signaling, and optional block signaling status when a local block-version database is configured.
GET /api/software-policy
Parameters: optional snapshot. If omitted, the latest public crawler export is used.
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. I2P and CJDNS nodes are exposed through the JSON APIs rather than DNS bootstrap 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.
