Manage peers with basectl p2p

View P2P endpoints and peers, test whether your node is reachable, and add, remove, ban, or unban execution-layer and consensus-layer peers on a Base node with basectl p2p.

basectl p2p lets you view and manage the peer connections for both the execution layer (EL) and the consensus layer (CL).

Commands

• basectl p2p info shows your node’s advertised endpoint and peer count for each layer (plus the CL’s configured maximum peer count when the node reports it).
• basectl p2p peers lists the connected peers for each layer.
• basectl p2p reachability <ENODE> asks the Base telemetry service to try connecting to an EL node from the outside, so you can confirm your node is reachable.
• basectl p2p add-peer <TARGET> connects to one peer. An enode://... address connects an EL peer; an enr:... record or a /.../p2p/<peer-id> address connects a CL peer.
• basectl p2p remove-peer <TARGET> disconnects one peer. An enode://... address removes an EL peer; any other value is treated as a CL peer ID.
• basectl p2p ban <TARGET> bans one peer. An enode://... address bans an EL peer; a CL peer ID bans a CL peer. Banning a CL peer also tries to disconnect it right away.
• basectl p2p unban <TARGET> unbans one EL or CL peer using the same rules. It does not reconnect the peer.
• basectl p2p unban-all unbans every peer currently banned on the consensus layer.

Flags

Read-only commands and single-peer actions accept:

Flag	Description
--el-rpc <URL>	Use a specific execution-layer RPC URL instead of the one in your config.
--cl-rpc <URL>	Use a specific consensus-node RPC URL instead of the one in your config.

Read-only commands also accept:

Flag	Description
--json	Print JSON instead of a table.
--raw	Add to --json to print the raw response from the node. Using --raw without --json is an error.

Commands that ban or remove peers also accept:

Flag	Description
--yes	Skip the confirmation prompt. By default these commands print exactly what they’ll do and wait for y or yes; anything else cancels.
--json	Print the result as JSON. Requires --yes so an automated run never waits for input.

Testing reachability

p2p reachability first detects which network your node is on, then asks the hosted Base mainnet or Sepolia telemetry service to connect to the node you name. The command supports --json and exits with an error if the connection doesn’t fully succeed, so you can use it in scripts.

The stage field tells you how far the connection got:

Stage	Meaning
tcp_connect	Opening a TCP connection to the node’s advertised address.
encrypted_handshake	Setting up the encrypted connection using the node’s identity.
devp2p_hello	Exchanging the initial Ethereum P2P handshake message.

What your EL RPC needs to expose

Some P2P actions require an EL RPC with admin methods enabled. When those methods aren’t available, basectl p2p still runs but some fields and actions won’t work.

If your EL RPC doesn’t expose admin methods, peer counts still work, but endpoint details, peer listings, and EL bans do not.

• Peer counts come from net_peerCount, which works on most RPCs, including restricted or public ones.
• Endpoint details and peer listings need the EL admin methods admin_nodeInfo and admin_peers. Without them, the peer count still shows, but endpoint fields and peer lists appear as unavailable.
• EL bans and unbans use admin_banPeer and admin_unbanPeer. In reth, a “trusted” peer can’t be banned until it’s removed from the trusted set; reth silently ignores such bans, so basectl p2p ban checks first and fails clearly if the target is a currently connected trusted peer.
• CL data and bans use the consensus node’s P2P methods (opp2p_*).
• unban-all is CL-only, because the EL admin API has no way to list banned peers.

Examples

View peers

# Endpoint and peer-count summary
basectl -c sepolia p2p info

# List peers as JSON
basectl -c sepolia p2p peers --json | jq '{el: .el | length, cl: .cl | length}'

# Test whether an EL node is reachable from the outside
basectl -c sepolia p2p reachability enode://<node-id>@203.0.113.10:30303 --json

# On a restricted EL RPC, peer count still works but some fields may be unavailable
basectl -c sepolia p2p info --el-rpc https://your-el.example/ --cl-rpc https://your-cl.example/

Manage peers

# Add an EL peer (asks for confirmation first)
basectl -c sepolia p2p add-peer enode://<node-id>@203.0.113.10:30303 --el-rpc https://your-el.example/

# Add a CL peer without a prompt and print JSON
basectl -c sepolia p2p add-peer enr:<record> --cl-rpc https://your-cl.example/ --yes --json | jq .

# Remove a CL peer by its peer ID
basectl -c sepolia p2p remove-peer 16Uiu2HAm... --cl-rpc https://your-cl.example/

# Ban an EL peer (needs an admin-enabled EL RPC)
basectl -c sepolia p2p ban enode://<node-id>@203.0.113.10:30303 --el-rpc https://your-el.example/

# Ban a CL peer and disconnect it immediately
basectl -c sepolia p2p ban 16Uiu2HAm... --cl-rpc https://your-cl.example/

# Unban a CL peer without a prompt and print JSON
basectl -c sepolia p2p unban 16Uiu2HAm... --cl-rpc https://your-cl.example/ --yes --json | jq .

# Unban every currently banned CL peer
basectl -c sepolia p2p unban-all --cl-rpc https://your-cl.example/ --yes

Related

• basectl overview
• Diagnose node health
• Node troubleshooting