These docs are for v0.17.0. Click to read the latest docs for v19.0.0-redirect.

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

NameTypePresenceDescription
nodestringRequired
(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

NameTypePresenceDescription
commandstringRequired
(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

NameTypePresenceDescription
resultnullRequired
(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 addnode RPC 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

NameTypePresenceDescription
resultnullRequired
(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

NameTypePresenceDescription
addressstringRequired
(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

NameTypePresenceDescription
nodeidnumberOptionalThe node ID (see getpeerinfo for node IDs)

Result---null on success or error on failed disconnect

NameTypePresenceDescription
resultnullRequired
(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 addnode RPC 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

NameTypePresenceDescription
DummyboolRequired
(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

NameTypePresenceDescription
nodestringOptional
(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

NameTypePresenceDescription
resultarrayRequired
(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
objectOptional
(0 or more)
An object containing details about a single added node
→ →
addednode
stringRequired
(exactly 1)
An added node in the same <IP address>:<port> format as used in the addnode RPC.
→ →
connected
boolOptional
(0 or 1)
This will be set to true if the node is currently connected and false if it is not
→ →
addresses
arrayRequired
(exactly 1)
This will be an array of addresses belonging to the added node
→ → →
Address
objectOptional
(0 or more)
An object describing one of this node's addresses
→ → → →
address
stringRequired
(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
stringRequired
(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

NameTypePresenceDescription
resultnumber (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

NameTypePresenceDescription
resultobjectRequired
(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
boolRequired
(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
boolRequired
(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

NameTypePresenceDescription
resultobjectRequired
(exactly 1)
Information about this node's connection to the network

version
numberRequired
(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
stringRequired
(exactly 1)
The node's build version including RC info or commit as relevant

subversion
stringRequired
(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
boolRequired
(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
boolRequired
(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
stringRequired
(exactly 1)
Added in Dash Core 0.16.0

The socket events mode, either epoll, poll, or select

networks
arrayRequired
(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
objectOptional
(0 to 3)
An object describing a network. If the network is unroutable, it will not be returned
→ → →
name
stringRequired
(exactly 1)
The name of the network. Either ipv4, ipv6, or onion
→ → →
limited
boolRequired
(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
boolRequired
(exactly 1)
Set to true if connections can be made to or from this network. Otherwise set to false
→ → →
proxy
stringRequired
(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
boolRequired
(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
arrayRequired
(exactly 1)
An array of objects each describing the local addresses this node believes it listens on
→ →
Address
objectOptional
(0 or more)
An object describing a particular address this node believes it listens on
→ → →
address
stringRequired
(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
stringRequired
(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

NameTypePresenceDescription
resultarrayRequired
(exactly 1)
An array of objects each describing one connected node. If there are no connections, the array will be empty

Node
objectOptional
(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
stringRequired
(exactly 1)
The IP address and port number used for the connection to the remote node
→ →
addrlocal
stringOptional
(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
stringOptional
(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
stringRequired
(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
boolRequired
(exactly 1)
Set to true if this node connected to us (inbound); set to false if we connected to this node (outbound)
→ →
addnode
boolRequired
(exactly 1)
Set to true if this node was added via the addnode RPC.
→ →
masternode
boolRequired
(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
arrayRequired
(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
boolRequired
(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 addnode RPC 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

NameTypePresenceDescription
resultobjectRequired
(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
objectOptional
(0 or more)
A ban list entry
→ →
address
stringRequired
(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
stringRequired
(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

NameTypePresenceDescription
resultnullRequiredAlways 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

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

NameTypePresenceDescription
IP(/Netmask)stringRequired
(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

NameTypePresenceDescription
CommandstringRequired
(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

NameTypePresenceDescription
Bantimenumeric
(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

NameTypePresenceDescription
AbsoluteboolOptional
(0 or 1)
If set, the bantime must be a absolute timestamp in seconds since epoch (Jan 1 1970 GMT)

Result---null on success

NameTypePresenceDescription
resultnullRequired
(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

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

NameTypePresenceDescription
ActivateboolRequired
(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

NameTypePresenceDescription
resultnullRequired
(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.