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 |
|---|---|---|---|
node | string | Required (exactly 1) | The node to add as a string in the form of <IP address>:<port>. |
Parameter #2---whether to add or remove the node, or to try only once to connect
| Name | Type | Presence | Description |
|---|---|---|---|
command | string | Required (exactly 1) | What to do with the IP address above. Options are: • add to add a node to the addnode list. Up to 8 nodes can be added additional to the default 8 nodes. Not limited by -maxconnections• remove to remove a node from the list. If currently connected, this will disconnect immediately• onetry to immediately attempt connection to the node even if the outgoing connection slots are full; this will only attempt the connection once |
Result---null plus error on failed remove
| Name | Type | Presence | Description |
|---|---|---|---|
result | null | Required (exactly 1) | Always JSON null whether the node was added, removed, tried-and-connected, or tried-and-not-connected. The JSON-RPC error field will be set only if you try adding a node that was already added or removing a node that is not on the addnodes list |
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.
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 |
|---|---|---|---|
result | null | Required (exactly 1) | JSON null when the list was cleared |
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 banned IPs/Subnets.
- 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 |
|---|---|---|---|
address | string | Required (exactly 1) | The node you want to disconnect from as a string in the form of <IP address>:<port>.Updated in Bitcoin Core 0.14.1 |
Parameter #2---nodeid
| Name | Type | Presence | Description |
|---|---|---|---|
| nodeid | number | Optional | The node ID (see getpeerinfo for node IDs) |
Result---null on success or error on failed disconnect
| Name | Type | Presence | Description |
|---|---|---|---|
result | null | Required (exactly 1) | JSON null when the node was disconnected |
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 (exactly 1) | 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 |
|---|---|---|---|
node | string | Optional (0 or 1) | The node to get information about in the same <IP address>:<port> format as the addnode RPC. If this parameter is not provided, information about all added nodes will be returned |
Result---a list of added nodes
| Name | Type | Presence | Description |
|---|---|---|---|
result | array | Required (exactly 1) | An array containing objects describing each added node. If no added nodes are present, the array will be empty. Nodes added with onetry will not be returned |
| → Added Node | object | Optional (0 or more) | An object containing details about a single added node |
→ →addednode | string | Required (exactly 1) | An added node in the same <IP address>:<port> format as used in the addnode RPC. |
→ →connected | bool | Optional (0 or 1) | This will be set to true if the node is currently connected and false if it is not |
→ →addresses | array | Required (exactly 1) | This will be an array of addresses belonging to the added node |
| → → → Address | object | Optional (0 or more) | An object describing one of this node's addresses |
→ → → →address | string | Required (exactly 1) | 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 |
→ → → →connected | string | Required (exactly 1) | Whether or not the local node is connected to this addnode using this IP address. Valid values are: • false for not connected• inbound if the addnode connected to us• outbound if we connected to the addnode |
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 |
|---|---|---|---|
result | number (int) | Required (exactly 1) | 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.
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 |
|---|---|---|---|
result | object | Required (exactly 1) | An object containing information about the node's network totals |
→totalbytesrecv | number (int) | Required (exactly 1) | The total number of bytes received since the node was last restarted |
→totalbytessent | number (int) | Required (exactly 1) | The total number of bytes sent since the node was last restarted |
→timemillis | number (int) | Required (exactly 1) | Unix epoch time in milliseconds according to the operating system's clock (not the node adjusted time) |
→uploadtarget | string : object | Required (exactly 1) | The upload target information |
→ →timeframe | number (int) | Required (exactly 1) | Length of the measuring timeframe in seconds (currently set to 24 hours) |
→ →target | number (int) | Required (exactly 1) | The maximum allowed outbound traffic in bytes (default is 0). Can be changed with -maxuploadtarget |
→ →target_reached | bool | Required (exactly 1) | Indicates if the target is reached. If the target is reached the node won't serve SPV and historical block requests anymore |
→ →serve_historical_blocks | bool | Required (exactly 1) | Indicates if historical blocks are served |
→ →bytes_left_in_cycle | number (int) | Required (exactly 1) | Amount of bytes left in current time cycle. 0 is displayed if no upload target is set |
→ →time_left_in_cycle | number (int) | Required (exactly 1) | Seconds left in current time cycle. 0 is displayed if no upload target is set |
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 |
|---|---|---|---|
result | object | Required (exactly 1) | Information about this node's connection to the network |
→version | number | Required (exactly 1) | 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 |
→buildversion | string | Required (exactly 1) | The node's build version including RC info or commit as relevant |
→subversion | string | Required (exactly 1) | The user agent this node sends in its version message |
→protocolversion | number (int) | Required (exactly 1) | The protocol version number used by this node. See the protocol versions section for more information |
→localservices | string (hex) | Required (exactly 1) | The services supported by this node as advertised in its version message |
→localrelay | bool | Required (exactly 1) | Added in Bitcoin Core 0.13.0 The services supported by this node as advertised in its version message |
→timeoffset | number (int) | Required (exactly 1) | 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) |
→networkactive | bool | Required (exactly 1) | Set to true if P2P networking is enabled. Set to false if P2P networking is disabled. Enabling/disabling done via SetNetworkActive |
→connections | number (int) | Required (exactly 1) | The total number of open connections (both outgoing and incoming) between this node and other nodes |
→socketevents | string | Required (exactly 1) | Added in Dash Core 0.16.0 The socket events mode, either epoll, poll, or select |
→networks | array | Required (exactly 1) | An array with three objects: one describing the IPv4 connection, one describing the IPv6 connection, and one describing the Tor hidden service (onion) connection |
| → → Network | object | Optional (0 to 3) | An object describing a network. If the network is unroutable, it will not be returned |
→ → →name | string | Required (exactly 1) | The name of the network. Either ipv4, ipv6, or onion |
→ → →limited | bool | Required (exactly 1) | Set to true if only connections to this network are allowed according to the -onlynet Dash Core command-line/configuration-file parameter. Otherwise set to false |
→ → →reachable | bool | Required (exactly 1) | Set to true if connections can be made to or from this network. Otherwise set to false |
→ → →proxy | string | Required (exactly 1) | The hostname and port of any proxy being used for this network. If a proxy is not in use, an empty string |
→ → →proxy_randomize_credentials | bool | Required (exactly 1) | Added in Bitcoin Core 0.11.0 Set to true if randomized credentials are set for this proxy. Otherwise set to false |
→relayfee | number (DASH) | Required (exactly 1) | The minimum relay fee per kilobyte for transactions in order for this node to accept it into its memory pool |
→incrementalfee | number (DASH) | Required (exactly 1) | Added in Dash Core 0.12.3 The minimum fee increment for mempool limiting or BIP 125 replacement in DASH/kB |
→localaddresses | array | Required (exactly 1) | An array of objects each describing the local addresses this node believes it listens on |
| → → Address | object | Optional (0 or more) | An object describing a particular address this node believes it listens on |
→ → →address | string | Required (exactly 1) | An IP address or .onion address this node believes it listens on. This may be manually configured, auto detected, or based on version messages this node received from its peers |
→ → →port | number (int) | Required (exactly 1) | The port number this node believes it listens on for the associated address. This may be manually configured, auto detected, or based on version messages this node received from its peers |
→ → →score | number (int) | Required (exactly 1) | The number of incoming connections during the uptime of this node that have used this address in their version message |
→warnings | string | Required (exactly 1) | Added in Bitcoin Core 0.11.0 A plain-text description of any network warnings. If there are no warnings, an empty string will be returned. |
Example from Dash Core 0.17.0
dash-cli getnetworkinfo
Result (actual addresses have been replaced with RFC5737 reserved addresses):
{
"version": 170000,
"buildversion": "v0.17.0.0-79ef4f8de",
"subversion": "/Dash Core:0.17.0.0/",
"protocolversion": 70218,
"localservices": "0000000000000405",
"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
}
],
"relayfee": 0.00001000,
"incrementalfee": 0.00001000,
"localaddresses": [
{
"address": "192.0.2.113",
"port": 18999,
"score": 4
}
],
"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 |
|---|---|---|---|
result | array | Required (exactly 1) | An array of objects each describing one connected node. If there are no connections, the array will be empty |
| → Node | object | Optional (0 or more) | An object describing a particular connected node |
→ →id | number (int) | Required (exactly 1) | The node's index number in the local node address database |
→ →addr | string | Required (exactly 1) | The IP address and port number used for the connection to the remote node |
→ →addrlocal | string | Optional (0 or 1) | 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 127.0.0.1:9999 |
→ →addrbind | string | Optional (0 or 1) | Bind address of the connection to the peer |
→ →services | string (hex) | Required (exactly 1) | The services advertised by the remote node in its version message |
→ →verified_proregtx_hash | string (hex) | Optional (0 or 1) | The ProRegTx of the masternode |
→ →verified_pubkey_hash | string (hex) | Optional (0 or 1) | The hashed operator public key of the masternode |
→ →lastsend | number (int) | Required (exactly 1) | The Unix epoch time when we last successfully sent data to the TCP socket for this node |
→ →lastrecv | number (int) | Required (exactly 1) | The Unix epoch time when we last received data from this node |
→ →bytessent | number (int) | Required (exactly 1) | The total number of bytes we've sent to this node |
→ →bytesrecv | number (int) | Required (exactly 1) | The total number of bytes we've received from this node |
→ →conntime | number (int) | Required (exactly 1) | The Unix epoch time when we connected to this node |
→ →timeoffset | number (int) | Required (exactly 1) | Added in Bitcoin Core 0.12.0 The time offset in seconds |
→ →pingtime | number (real) | Required (exactly 1) | The number of seconds this node took to respond to our last P2P ping message |
→ →minping | number (real) | Optional (0 or 1) | Updated in Bitcoin Core 0.13.0 The minimum observed ping time (if any at all) |
→ →pingwait | number (real) | Optional (0 or 1) | The number of seconds we've been waiting for this node to respond to a P2P ping message. Only shown if there's an outstanding ping message |
→ →version | number (int) | Required (exactly 1) | The protocol version number used by this node. See the protocol versions section for more information |
→ →subver | string | Required (exactly 1) | The user agent this node sends in its version message. This string will have been sanitized to prevent corrupting the JSON results. May be an empty string |
→ →inbound | bool | Required (exactly 1) | Set to true if this node connected to us (inbound); set to false if we connected to this node (outbound) |
→ →addnode | bool | Required (exactly 1) | Set to true if this node was added via the addnode RPC. |
→ →masternode | bool | Required (exactly 1) | Added in Dash Core 0.16.0 Whether connection was due to masternode connection attempt |
→ →startingheight | number (int) | Required (exactly 1) | The height of the remote node's block chain when it connected to us as reported in its version message |
→ →banscore | number (int) | Required (exactly 1) | 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 100 |
→ →synced_headers | number (int) | Required (exactly 1) | The highest-height header we have in common with this node based the last P2P headers message it sent us. If a headers message has not been received, this will be set to -1 |
→ →synced_blocks | number (int) | Required (exactly 1) | The highest-height block we have in common with this node based on P2P inv messages this node sent us. If no block inv messages have been received from this node, this will be set to -1 |
→ →inflight | array | Required (exactly 1) | An array of blocks which have been requested from this peer. May be empty |
| → → → Blocks | number (int) | Optional (0 or more) | The height of a block being requested from the remote peer |
→ →whitelisted | bool | Required (exactly 1) | Set to true if the remote peer has been whitelisted; otherwise, set to false. Whitelisted peers will not be banned if their ban score exceeds the maximum (100 by default). By default, peers connecting from localhost are whitelisted |
→ →bytessent_per_msg | string : object | Required (exactly 1) | Added in Bitcoin Core 0.13.0 Information about total sent bytes aggregated by message type |
| → → → Message Type | number (int) | Required (1 or more) | Total sent bytes aggregated by message type. One field for every used message type |
→ →bytesrecv_per_msg | string : object | Required (exactly 1) | Added in Bitcoin Core 0.13.0 Information about total received bytes aggregated by message type |
| → → → Message Type | number (int) | Required (1 or more) | Total received bytes aggregated by message type. One field for every used message type |
Example from Dash Core 0.12.2
dash-cli getpeerinfo
Result (edited to show only a single entry, with IP addresses changed to
RFC5737 reserved IP addresses):
[
{
"id": 3,
"addr": "192.0.2.113:19999",
"addrlocal": "127.0.0.1:56332",
"addrbind": "192.168.10.111:56332",
"services": "0000000000000405",
"verified_proregtx_hash": "109e45aedfa3b9eeda9bf3a12d392b3db711eb9c248db5fc5c878703496621e9",
"verified_pubkey_hash": "48563ca7b0b42e4447a00578456fad06c5ed0c6965cdba170f7c84be7df204e3",
"relaytxes": true,
"lastsend": 1611582718,
"lastrecv": 1611582718,
"bytessent": 10598,
"bytesrecv": 32442,
"conntime": 1611582087,
"timeoffset": -2,
"pingtime": 0.08229,
"minping": 0.081689,
"version": 70218,
"subver": "/Dash Core:0.17.0/",
"inbound": false,
"addnode": false,
"masternode": false,
"startingheight": 432836,
"banscore": 0,
"synced_headers": 432843,
"synced_blocks": 432843,
"inflight": [
],
"whitelisted": false,
"bytessent_per_msg": {
"addr": 110,
"dsq": 6800,
"getaddr": 24,
"getdata": 926,
"getheaders": 1021,
"getsporks": 24,
"govsync": 66,
"headers": 742,
"inv": 183,
"mempool": 24,
"ping": 192,
"pong": 192,
"qsendrecsigs": 25,
"sendcmpct": 33,
"senddsq": 25,
"sendheaders": 24,
"verack": 24,
"version": 163
},
"bytesrecv_per_msg": {
"*other*": 25,
"addr": 12022,
"clsig": 312,
"dsq": 7310,
"getheaders": 1021,
"headers": 424,
"inv": 4189,
"islock": 378,
"mnauth": 152,
"ping": 192,
"pong": 192,
"qsigrec": 1519,
"sendcmpct": 33,
"senddsq": 25,
"sendheaders": 24,
"spork": 2420,
"ssc": 32,
"tx": 1987,
"verack": 24,
"version": 161
}
}
]
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 banned IPs/Subnets.
Parameters: none
Result---information about each banned IP/Subnet
| Name | Type | Presence | Description |
|---|---|---|---|
result | object | Required (exactly 1) | An array of objects each describing one entry. If there are no entries in the ban list, the array will be empty |
| → Node | object | Optional (0 or more) | A ban list entry |
→ →address | string | Required (exactly 1) | The IP/Subnet of the entry |
→ →banned_until | number (int) | Required (exactly 1) | The Unix epoch time when the entry was added to the ban list |
→ →ban_created | number (int) | Required (exactly 1) | The Unix epoch time until the IP/Subnet is banned |
→ →ban_reason | string | Required (exactly 1) | Set to one of the following reasons: • node misbehaving if the node was banned by the client because of DoS violations• manually added if the node was manually banned by the user |
Examples from Dash Core 0.12.2
The default (false):
dash-cli listbanned
Result:
[
{
"address": "192.0.2.201/32",
"banned_until": 1507906175,
"ban_created": 1507819775,
"ban_reason": "node misbehaving"
},
{
"address": "192.0.2.101/32",
"banned_until": 1507906199,
"ban_created": 1507819799,
"ban_reason": "manually added"
}
]
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 |
|---|---|---|---|
result | null | Required | Always JSON null |
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.
- P2P Ping Message
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 (exactly 1) | The node to add or remove as a string in the form of <IP address>. The IP address may be a hostname resolvable through DNS, an IPv4 address, an IPv4-as-IPv6 address, or an IPv6 address |
Parameter #2---whether to add or remove the node
| Name | Type | Presence | Description |
|---|---|---|---|
| Command | string | Required (exactly 1) | What to do with the IP/Subnet address above. Options are: • add to add a node to the addnode list• remove to remove a node from the list. If currently connected, this will disconnect immediately |
Parameter #3---time how long the ip is banned
| Name | Type | Presence | Description |
|---|---|---|---|
| Bantime | numeric (int) | Optional (0 or 1) | Time in seconds how long (or until when if absolute is set) the entry is banned. The default is 24h which can also be overwritten by the -bantime startup argument |
Parameter #4---whether a relative or absolute timestamp
| Name | Type | Presence | Description |
|---|---|---|---|
| Absolute | bool | Optional (0 or 1) | 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 |
|---|---|---|---|
result | null | Required (exactly 1) | Always JSON null |
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 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 (exactly 1) | Set to true to enable all P2P network activity. Set to false to disable all P2P network activity |
Result---null or error on failure
| Name | Type | Presence | Description |
|---|---|---|---|
result | null | Required (exactly 1) | JSON null. The JSON-RPC error field will be set only if you entered an invalid parameter |
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.
Updated almost 4 years ago
What’s Next