Network RPCs#
AddNode#
The addnode RPC attempts to add or remove a node from the addnode list, or to try a connection to a node once.
Parameter #1—hostname/IP address and port of node to add or remove
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
string |
Required |
The node to add as a string in the form of |
Parameter #2—whether to add or remove the node, or to try only once to connect
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
string |
Required |
What to do with the IP address above. Options are: |
Result—null plus error on failed remove
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
null |
Required |
Always JSON |
Example from Dash Core 0.12.2
Try connecting to the following node.
dash-cli -testnet addnode 192.0.2.113:19999 onetry
Result (no output from dash-cli because result is set to null).
See also
GetAddedNodeInfo: returns information about the given added node, or all added nodes (except onetry nodes). Only nodes which have been manually added using the
addnodeRPC will have their information displayed.
AddPeerAddress#
The addpeeraddress RPC adds the address
of a potential peer to the address manager. This RPC is for testing only.
Parameter #1—IP address of node to add
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
string |
Required |
The IP address of the peer |
Parameter #2—port of the node to add
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
number |
Required |
The port of the peer |
Result—a list of added nodes
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
object |
Required |
An object describing if the address was successfully added |
→ |
bool |
Required |
Whether the peer address was successfully added to the address manager |
Example from Dash Core 20.0.0
Try connecting to the following node.
dash-cli addpeeraddress "1.2.3.4" 9999
Result:
{
"success": true
}
See also: none
ClearBanned#
Added in Bitcoin Core 0.12.0
The clearbanned RPC clears list of banned nodes.
Parameters: none
Result—null on success
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
null |
Required |
JSON |
Example from Dash Core 0.12.2
Clears the ban list.
dash-cli clearbanned
Result (no output from dash-cli because result is set to null).
See also
ListBanned: lists all manually banned IPs/Subnets.
SetBan: attempts add or remove a IP/Subnet from the banned list.
ClearDiscouraged: clears list of discouraged nodes.
ClearDiscouraged#
Added in Dash Core 19.0.0
The cleardiscouraged RPC clears all discouraged nodes.
Parameters: none
Result—null on success
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
null |
Required |
JSON |
Example from Dash Core 19.0.0
Clears the ban list.
dash-cli cleardiscouraged
Result (no output from dash-cli because result is set to null).
See also
ListBanned: lists all manually banned IPs/Subnets.
ClearBanned: clears list of banned nodes.
SetBan: attempts add or remove a IP/Subnet from the banned list.
DisconnectNode#
Added in Bitcoin Core 0.12.0
The disconnectnode RPC immediately disconnects from a specified node.
Parameter #1—hostname/IP address and port of node to disconnect
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
string |
Required |
The node you want to disconnect from as a string in the form of |
Parameter #2—nodeid
Name |
Type |
Presence |
Description |
|---|---|---|---|
nodeid |
number |
Optional |
The node ID (see |
Result—null on success or error on failed disconnect
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
null |
Required |
JSON |
Example from Dash Core 0.15.0
Disconnects following node by address.
dash-cli -testnet disconnectnode 192.0.2.113:19999
Result (no output from dash-cli because result is set to null).
Disconnects following node by id.
dash-cli -testnet disconnectnode "" 3
Result (no output from dash-cli because result is set to null).
See also
AddNode: attempts to add or remove a node from the addnode list, or to try a connection to a node once.
GetAddedNodeInfo: returns information about the given added node, or all added nodes (except onetry nodes). Only nodes which have been manually added using the
addnodeRPC will have their information displayed.
GetAddedNodeInfo#
The getaddednodeinfo RPC returns information about the given added node, or all added nodes (except onetry nodes). Only nodes which have been manually added using the addnode RPC will have their information displayed.
Prior to Dash Core 0.12.3, this dummy parameter was required for historical purposes but not used:
DEPRECATED Parameter #1—whether to display connection information
Name |
Type |
Presence |
Description |
|---|---|---|---|
Dummy |
bool |
Required |
Removed in Dash Core 0.12.3 |
Beginning with Dash Core 0.12.3, this is the single (optional) parameter:
Parameter #1—what node to display information about
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
string |
Optional |
The node to get information about in the same |
Result—a list of added nodes
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
array |
Required |
An array containing objects describing each added node. If no added nodes are present, the array will be empty. Nodes added with |
→ |
object |
Optional |
An object containing details about a single added node |
→ → |
string |
Required |
An added node in the same |
→ → |
bool |
Optional |
This will be set to |
→ → |
array |
Required |
This will be an array of addresses belonging to the added node |
→ → → |
object |
Optional |
An object describing one of this node’s addresses |
→ → → → |
string |
Required |
An IP address and port number of the node. If the node was added using a DNS address, this will be the resolved IP address |
→ → → → |
string |
Required |
Whether or not the local node is connected to this addnode using this IP address. Valid values are: |
Example from Dash Core 0.12.3
dash-cli getaddednodeinfo
Result (real hostname and IP address replaced with RFC5737 reserved address):
[
{
"addednode": "192.0.2.113:19999",
"connected": true,
"addresses": [
{
"address": "192.0.2.113:19999",
"connected": "outbound"
}
]
}
]
See also
AddNode: attempts to add or remove a node from the addnode list, or to try a connection to a node once.
GetPeerInfo: returns data about each connected network node.
GetConnectionCount#
The getconnectioncount RPC returns the number of connections to other nodes.
Parameters: none
Result—the number of connections to other nodes
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
number (int) |
Required |
The total number of connections to other nodes (both inbound and outbound) |
Example from Dash Core 0.12.2
dash-cli -testnet getconnectioncount
Result:
14
See also
GetNetTotals: returns information about network traffic, including bytes in, bytes out, and the current time.
GetPeerInfo: returns data about each connected network node.
GetNetworkInfo: returns information about the node’s connection to the network.
GetNodeAddresses#
The getnodeaddresses RPC returns the known addresses which can potentially be used to find new nodes in the network.
Parameter #1—count
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
number (int) |
Optional |
The number of addresses to return. Limited to the smaller of 2500 or 23% of all known addresses (default = 1). |
Result—the current bytes in, bytes out, and current time
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
array |
Required |
An array containing information about the known addresses. |
→ |
number (int) |
Required |
The epoch time of when the node was last seen (in Unix) |
→ |
number (int) |
Required |
The services offered |
→ |
string |
Required |
The address of the node |
→ |
number (int) |
Required |
The port of the node |
Example from Dash Core 18.0.0
dash-cli -testnet getnodeaddresses
Result:
[
{
"time": 1634187034,
"services": 1029,
"address": "34.214.102.160",
"port": 19999
}
]
GetNetTotals#
The getnettotals RPC returns information about network traffic, including bytes in, bytes out, and the current time.
Parameters: none
Result—the current bytes in, bytes out, and current time
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
object |
Required |
An object containing information about the node’s network totals |
→ |
number (int) |
Required |
The total number of bytes received since the node was last restarted |
→ |
number (int) |
Required |
The total number of bytes sent since the node was last restarted |
→ |
number (int) |
Required |
Unix epoch time in milliseconds according to the operating system’s clock (not the node adjusted time) |
→ |
string : |
Required |
The upload target information |
→ → |
number (int) |
Required |
Length of the measuring timeframe in seconds (currently set to |
→ → |
number (int) |
Required |
The maximum allowed outbound traffic in bytes (default is |
→ → |
bool |
Required |
Indicates if the target is reached. If the target is reached the node won’t serve SPV and historical block requests anymore |
→ → |
bool |
Required |
Indicates if historical blocks are served |
→ → |
number (int) |
Required |
Amount of bytes left in current time cycle. |
→ → |
number (int) |
Required |
Seconds left in current time cycle. |
Example from Dash Core 0.12.2
dash-cli getnettotals
Result:
{
"totalbytesrecv": 4661588,
"totalbytessent": 2899423,
"timemillis": 1507815162756,
"uploadtarget": {
"timeframe": 86400,
"target": 0,
"target_reached": false,
"serve_historical_blocks": true,
"bytes_left_in_cycle": 0,
"time_left_in_cycle": 0
}
}
See also
GetNetworkInfo: returns information about the node’s connection to the network.
GetPeerInfo: returns data about each connected network node.
GetNetworkInfo#
The getnetworkinfo RPC returns information about the node’s connection to the network.
Parameters: none
Result—information about the node’s connection to the network
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
object |
Required |
Information about this node’s connection to the network |
→ |
number |
Required |
This node’s version of Dash Core in its internal integer format. For example, Dash Core 0.12.2 has the integer version number 120200 |
→ |
string |
Required |
The node’s build version including RC info or commit as relevant |
→ |
string |
Required |
The user agent this node sends in its |
→ |
number (int) |
Required |
The protocol version number used by this node. See the protocol versions section for more information |
→ |
string (hex) |
Required |
The services supported by this node as advertised in its |
→ |
array |
Required |
Added in Dash Core 18.0.0 |
→ → |
string |
Required |
The service name. |
→ |
bool |
Required |
Added in Bitcoin Core 0.13.0 |
→ |
number (int) |
Required |
The offset of the node’s clock from the computer’s clock (both in UTC) in seconds. The offset may be up to 4200 seconds (70 minutes) |
→ |
bool |
Required |
Set to |
→ |
number (int) |
Required |
The total number of open connections (both outgoing and incoming) between this node and other nodes |
→ |
number (int) |
Required |
Added in Dash Core 18.0.0 |
→ |
number (int) |
Required |
Added in Dash Core 18.0.0 |
→ |
number (int) |
Required |
Added in Dash Core 18.0.0 |
→ |
number (int) |
Required |
Added in Dash Core 18.0.0 |
→ |
number (int) |
Required |
Added in Dash Core 18.0.0 |
→ |
string |
Required |
Added in Dash Core 0.16.0 |
→ |
array |
Required |
An array with three objects: one describing the IPv4 connection, one describing the IPv6 connection, and one describing the Tor hidden service (onion) connection |
→ → |
object |
Optional |
An object describing a network. If the network is unroutable, it will not be returned |
→ → → |
string |
Required |
The name of the network. Either |
→ → → |
bool |
Required |
Set to |
→ → → |
bool |
Required |
Set to |
→ → → |
string |
Required |
The hostname and port of any proxy being used for this network. If a proxy is not in use, an empty string |
→ → → |
bool |
Required |
Added in Bitcoin Core 0.11.0 |
→ |
number (DASH) |
Required |
The minimum relay fee per kilobyte for transactions in order for this node to accept it into its memory pool |
→ |
number (DASH) |
Required |
Added in Dash Core 0.12.3 |
→ |
array |
Required |
An array of objects each describing the local addresses this node believes it listens on |
→ → |
object |
Optional |
An object describing a particular address this node believes it listens on |
→ → → |
string |
Required |
An IP address or .onion address this node believes it listens on. This may be manually configured, auto detected, or based on |
→ → → |
number (int) |
Required |
The port number this node believes it listens on for the associated |
→ → → |
number (int) |
Required |
The number of incoming connections during the uptime of this node that have used this |
→ |
string |
Required |
Added in Bitcoin Core 0.11.0 |
Example from Dash Core 18.0.0
dash-cli getnetworkinfo
Result (actual addresses have been replaced with RFC5737 reserved addresses):
{
"version": 170003,
"buildversion": "v0.17.0.3-649273e70",
"subversion": "/Dash Core:0.17.0.3/",
"protocolversion": 70220,
"localservices": "0000000000000445",
"localservicesnames": [
"NETWORK",
"BLOOM",
"COMPACT_FILTERS",
"NETWORK_LIMITED"
],
"localrelay": true,
"timeoffset": 0,
"networkactive": true,
"connections": 8,
"socketevents": "epoll",
"networks": [
{
"name": "ipv4",
"limited": false,
"reachable": true,
"proxy": "",
"proxy_randomize_credentials": false
},
{
"name": "ipv6",
"limited": false,
"reachable": true,
"proxy": "",
"proxy_randomize_credentials": false
},
{
"name": "onion",
"limited": true,
"reachable": false,
"proxy": "",
"proxy_randomize_credentials": false
},
{
"name": "",
"limited": false,
"reachable": true,
"proxy": "",
"proxy_randomize_credentials": false
},
{
"name": "",
"limited": false,
"reachable": true,
"proxy": "",
"proxy_randomize_credentials": false
}
],
"relayfee": 0.00001000,
"incrementalfee": 0.00001000,
"localaddresses": [
],
"warnings": "Warning: unknown new rules activated (versionbit 3)"
}
See also
GetPeerInfo: returns data about each connected network node.
GetNetTotals: returns information about network traffic, including bytes in, bytes out, and the current time.
SetNetworkActive: disables/enables all P2P network activity.
GetPeerInfo#
The getpeerinfo RPC returns data about each connected network node.
Parameters: none
Result—information about each currently-connected network node
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
array |
Required |
An array of objects each describing one connected node. If there are no connections, the array will be empty |
→ |
object |
Optional |
An object describing a particular connected node |
→ → |
number (int) |
Required |
The node’s index number in the local node address database |
→ → |
string |
Required |
The IP address and port number used for the connection to the remote node |
→ → |
string |
Optional |
Our IP address and port number according to the remote node. May be incorrect due to error or lying. Most SPV nodes set this to |
→ → |
string |
Optional |
Added in Dash Core 20.0.0 |
→ → |
string |
Optional |
Added in Dash Core 18.0.0 |
→ → |
string |
Optional |
Bind address of the connection to the peer |
→ → |
string (hex) |
Required |
The services advertised by the remote node in its |
→ → |
array |
Required |
Added in Dash Core 18.0.0 |
→ → → |
string |
Required |
The service name if it is recognised. |
→ → |
string (hex) |
Optional |
The ProRegTx of the masternode |
→ → |
string (hex) |
Optional |
The hashed operator public key of the masternode |
|
bool |
Required |
Whether peer has asked us to relay transactions to it. |
→ → |
number (int) |
Required |
The Unix epoch time when we last successfully sent data to the TCP socket for this node |
→ → |
number (int) |
Required |
The Unix epoch time when we last received data from this node |
|
number (int) |
Required |
Added in Dash Core 20.1.0 |
|
number (int) |
Required |
Added in Dash Core 20.1.0 |
→ → |
number (int) |
Required |
The total number of bytes we’ve sent to this node |
→ → |
number (int) |
Required |
The total number of bytes we’ve received from this node |
→ → |
number (int) |
Required |
The Unix epoch time when we connected to this node |
→ → |
number (int) |
Required |
Added in Bitcoin Core 0.12.0 |
→ → |
number (real) |
Required |
The number of seconds this node took to respond to our last P2P |
→ → |
number (real) |
Optional |
Updated in Bitcoin Core 0.13.0 |
→ → |
number (real) |
Optional |
The number of seconds we’ve been waiting for this node to respond to a P2P |
→ → |
number (int) |
Required |
The protocol version number used by this node. See the protocol versions section for more information |
→ → |
string |
Required |
The user agent this node sends in its |
→ → |
bool |
Required |
Set to |
→ → |
bool |
Required |
Set to |
→ → |
bool |
Required |
Added in Dash Core 0.16.0 |
→ → |
number (int) |
Required |
The height of the remote node’s block chain when it connected to us as reported in its |
→ → |
number (int) |
Required |
The ban score we’ve assigned the node based on any misbehavior it’s made. By default, Dash Core disconnects when the ban score reaches |
→ → |
number (int) |
Required |
The highest-height header we have in common with this node based the last P2P |
→ → |
number (int) |
Required |
The highest-height block we have in common with this node based on P2P |
→ → |
array |
Required |
An array of blocks which have been requested from this peer. May be empty |
→ → → |
number (int) |
Optional |
The height of a block being requested from the remote peer |
→ → |
bool |
Required |
Set to |
→ → |
array |
Required |
Added in Dash Core 18.0.0 |
→ → |
string : |
Required |
Added in Bitcoin Core 0.13.0 |
→ → → |
number (int) |
Required |
Total sent bytes aggregated by message type. One field for every used message type |
→ → |
string : |
Required |
Added in Bitcoin Core 0.13.0 |
→ → → |
number (int) |
Required |
Total received bytes aggregated by message type. One field for every used message type |
|
string |
Required |
Added in Dash Core 20.1.0 |
Example from Dash Core 20.1.0
dash-cli -testnet getpeerinfo
Result (edited to show only a single entry, with IP addresses changed to
RFC5737 reserved IP addresses):
[
{
"id": 0,
"addr": "198.51.100.1:19999",
"addrbind": "192.0.2.1:34896",
"addrlocal": "203.0.113.1:34896",
"network": "ipv4",
"services": "0000000000000c05",
"servicesnames": [
"NETWORK",
"BLOOM",
"NETWORK_LIMITED",
"HEADERS_COMPRESSED"
],
"relaytxes": false,
"lastsend": 1707941906,
"lastrecv": 1707941902,
"last_transaction": 0,
"last_block": 1707934590,
"bytessent": 240367,
"bytesrecv": 252966,
"conntime": 1707934579,
"timeoffset": 0,
"pingtime": 0.09482599999999999,
"minping": 0.093489,
"version": 70230,
"subver": "/Dash Core:20.0.2/",
"inbound": false,
"addnode": false,
"masternode": false,
"startingheight": 970213,
"banscore": 0,
"synced_headers": 970268,
"synced_blocks": 970268,
"inflight": [
],
"whitelisted": false,
"permissions": [
],
"bytessent_per_msg": {
"dsq": 151226,
"getdata": 10361,
"getheaders2": 1053,
"getsporks": 24,
"govsync": 69618,
"headers2": 3180,
"inv": 671,
"ping": 1984,
"pong": 1984,
"sendaddrv2": 24,
"sendcmpct": 33,
"sendheaders2": 24,
"verack": 24,
"version": 161
},
"bytesrecv_per_msg": {
"addrv2": 40,
"block": 209737,
"clsig": 624,
"getheaders2": 1053,
"headers2": 27918,
"inv": 4427,
"mnauth": 152,
"ping": 1984,
"pong": 1984,
"sendaddrv2": 24,
"sendcmpct": 33,
"senddsq": 25,
"sendheaders2": 24,
"spork": 2420,
"ssc": 2336,
"verack": 24,
"version": 161
},
"connection_type": "block-relay-only"
}
}
See also
GetAddedNodeInfo: returns information about the given added node, or all added nodes (except onetry nodes). Only nodes which have been manually added using the
addnodeRPC will have their information displayed.GetNetTotals: returns information about network traffic, including bytes in, bytes out, and the current time.
GetNetworkInfo: returns information about the node’s connection to the network.
ListBanned#
Added in Bitcoin Core 0.12.0
The listbanned RPC lists all manually banned IPs/Subnets.
📘 Changes regarding misbehaving peers
Dash Core 18.1.0 introduced changes to how misbehaving peers are treated. As a result they are no longer included in this RPC response. See the release notes for additional details.
Parameters: none
Result—information about each banned IP/Subnet
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
object |
Required |
An array of objects each describing one entry. If there are no entries in the ban list, the array will be empty |
→ |
object |
Optional |
A ban list entry |
→ → |
string |
Required |
The IP/Subnet of the entry |
→ → |
number |
Required |
The Unix epoch time when the entry was added to the ban list |
→ → |
number |
Required |
The Unix epoch time until the IP/Subnet is banned |
Examples from Dash Core 18.1.0
dash-cli listbanned
Result:
[
{
"address": "192.0.2.201/32",
"banned_until": 1507906175,
"ban_created": 1507819775,
},
{
"address": "192.0.2.101/32",
"banned_until": 1507906199,
"ban_created": 1507819799,
}
]
See also
SetBan: attempts add or remove a IP/Subnet from the banned list.
ClearBanned: clears list of banned nodes.
Ping#
The ping RPC sends a P2P ping message to all connected nodes to measure ping time. Results are provided by the getpeerinfo RPC pingtime and pingwait fields as decimal seconds. The P2P ping message is handled in a queue with all other commands, so it measures processing backlog, not just network ping.
Parameters: none
Result—null
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
null |
Required |
Always JSON |
Example from Dash Core 0.12.2
dash-cli -testnet ping
(Success: no result printed.)
Get the results using the getpeerinfo RPC:
dash-cli -testnet getpeerinfo | grep ping
Results:
"pingtime" : 0.11790800,
"pingtime" : 0.22673400,
"pingtime" : 0.16451900,
"pingtime" : 0.12465200,
"pingtime" : 0.13267900,
"pingtime" : 0.23983300,
"pingtime" : 0.16764700,
"pingtime" : 0.11337300,
See also
GetPeerInfo: returns data about each connected network node.
SetBan#
Added in Bitcoin Core 0.12.0
The setban RPC attempts add or remove a IP/Subnet from the banned list.
Parameter #1—IP/Subnet of the node
Name |
Type |
Presence |
Description |
|---|---|---|---|
IP(/Netmask) |
string |
Required |
The node to add or remove as a string in the form of |
Parameter #2—whether to add or remove the node
Name |
Type |
Presence |
Description |
|---|---|---|---|
Command |
string |
Required |
What to do with the IP/Subnet address above. Options are: |
Parameter #3—time how long the ip is banned
Name |
Type |
Presence |
Description |
|---|---|---|---|
Bantime |
numeric |
Optional |
Time in seconds how long (or until when if |
Parameter #4—whether a relative or absolute timestamp
Name |
Type |
Presence |
Description |
|---|---|---|---|
Absolute |
bool |
Optional |
If set, the bantime must be a absolute timestamp in seconds since epoch (Jan 1 1970 GMT) |
Result—null on success
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
null |
Required |
Always JSON |
Example from Dash Core 0.12.2
Ban the following node.
dash-cli -testnet setban 192.0.2.113 add 2592000
Result (no output from dash-cli because result is set to null).
See also
ListBanned: lists all manually banned IPs/Subnets.
ClearBanned: clears list of banned nodes.
SetNetworkActive#
Added in Bitcoin Core 0.14.0
The setnetworkactive RPC disables/enables all P2P network activity.
Parameter #1—whether to disable or enable all P2P network activity
Name |
Type |
Presence |
Description |
|---|---|---|---|
Activate |
bool |
Required |
Set to |
Result—null or error on failure
Name |
Type |
Presence |
Description |
|---|---|---|---|
|
null |
Required |
JSON |
Example from Dash Core 0.12.2
dash-cli setnetworkactive true
Result (no output from dash-cli because result is set to null).
See also
GetNetworkInfo: returns information about the node’s connection to the network.