Skip to main content

​
Overview

Returns the list of GossipSub topics the SSV node is subscribed to, along with the peers subscribed to each topic. This is useful for debugging P2P connectivity and verifying proper topic subscription.

​
Endpoint

GET /v1/node/topics

​
Authentication

No authentication required.

​
Response

​
all_peers
array
Array of all peer IDs connected to the node
​
peers_by_topic
array
Array of topic subscription information

​
Example Request

cURL
curl http://localhost:16000/v1/node/topics

​
Example Response

{
  "all_peers": [
    "16Uiu2HAm...",
    "16Uiu2HAk...",
    "16Uiu2HAj..."
  ],
  "peers_by_topic": [
    {
      "topic_name": "ssv.v2.mainnet.0x8e01234...",
      "peers": [
        "16Uiu2HAm...",
        "16Uiu2HAk..."
      ]
    },
    {
      "topic_name": "ssv.v2.mainnet.0x9f56789...",
      "peers": [
        "16Uiu2HAj...",
        "16Uiu2HAk..."
      ]
    }
  ]
}

​
Use Cases

​
Verify Topic Subscription

Check that your node is subscribed to the correct topics for your validators: 
curl -s http://localhost:16000/v1/node/topics | jq '.peers_by_topic[].topic_name'

​
Monitor Peer Distribution

Ensure peers are distributed across your validator topics: 
curl -s http://localhost:16000/v1/node/topics | \
  jq '.peers_by_topic[] | "\(.topic_name): \(.peers | length) peers"'

​
Debug Connectivity Issues

If a validator isn’t receiving duties, check if peers are subscribed to its topic: 
curl -s http://localhost:16000/v1/node/topics | \
  jq '.peers_by_topic[] | select(.topic_name | contains("0x8e01234")) | .peers | length'

​
Topic Name Format

SSV uses a hierarchical topic naming scheme: 
ssv.v2.<network>.<validator_pubkey>
Where:
  • v2 - SSV protocol version
  • <network> - Ethereum network name (mainnet, holesky, etc.)
  • <validator_pubkey> - Validator public key (first 8 characters)

​
Troubleshooting

​
No Topics Listed

If peers_by_topic is empty:
  • Node hasn’t loaded validator shares yet
  • Check that validator share files are in the correct location
  • Verify the node has synced contract events

​
Low Peer Count per Topic

If topics have fewer than 3-4 peers:
  • Check network connectivity and firewall rules
  • Verify discovery is working (/v1/node/peers)
  • Ensure your node is advertising correct multiaddrs

​
Topics for Unknown Validators

If you see topics for validators you don’t manage:
  • This is normal - nodes may briefly subscribe to topics during network discovery
  • Only topics with consistent peer presence indicate managed validators

​
Source Reference

Implementation: api/handlers/node/node.go:68 (Topics method) Topic indexing: network/topics/ package

Build docs developers (and LLMs) love

Get started for freeTalk to us