What is a Polygon node and how do you run or connect to one?

Quick decision: run your own Polygon node or use an RPC provider?

Before diving into node architecture, decide how you want to interact with Polygon. If you need full control over the node, want to run a validator, or require custom tracing, self-hosting makes sense. If you want to focus on building your dApp without managing infrastructure, a managed RPC provider like OnFinality's Polygon endpoint is the faster path.

Here's a quick guide:

• You are a dApp developer – Use a managed RPC provider. You get a reliable endpoint, WebSocket support, and scaling without node maintenance.
• You are a validator or need deep chain access – Run your own node. You'll need both Bor and Heimdall.
• You need archive data or high throughput – Consider a dedicated node from a provider, which offers dedicated resources and historical state.

What is a Polygon node?

A Polygon node is a computer that runs the Polygon PoS client software, maintaining a copy of the blockchain and participating in the network. Unlike a single-client chain, Polygon uses a dual-layer architecture:

• Bor – The execution layer, a fork of Geth that handles transaction processing and smart contract execution.
• Heimdall – The consensus layer, based on Tendermint, which manages validators, checkpoints, and state sync to Ethereum.

Nodes can be full nodes (storing the entire chain state) or archive nodes (storing all historical states). Validator nodes additionally participate in block production and consensus.

Why run a Polygon node?

Running your own node gives you:

• Direct access – No third-party between you and the chain.
• Customization – You can modify the client or add custom indexing.
• Privacy – Your requests are not logged by a provider.
• Cost control – For high-volume usage, self-hosting may be cheaper than paid RPC plans.

However, it comes with operational burdens: hardware, storage, monitoring, and keeping the node synced. For most developers, the trade-off favors a managed provider.

How to run a Polygon node

Hardware requirements

Polygon recommends the following for a full node:

• CPU: 8+ cores
• RAM: 16 GB (32 GB for archive)
• Storage: 2.5 TB SSD (grows over time)
• Bandwidth: 100 Mbps+ with unmetered transfer

Setup steps

1. Install dependencies – Docker, or build from source.
2. Download the genesis files – For mainnet, use the official Polygon snapshots.
3. Start Heimdall – Initialize and start the Heimdall service.
4. Start Bor – Configure Bor to connect to Heimdall and start the service.
5. Verify sync – Check logs and use eth_blockNumber to confirm the node is syncing.

Here's a simplified Docker Compose example:

version: '3'
services:
  heimdall:
    image: 0xpolygon/heimdall:latest
    command: heimdall start
    volumes:
      - ./heimdall:/heimdall
    ports:
      - "26657:26657"
  bor:
    image: 0xpolygon/bor:latest
    command: bor server
    volumes:
      - ./bor:/bor
    ports:
      - "8545:8545"

Connecting to Polygon via RPC

Once your node is running, it exposes an RPC endpoint (default http://localhost:8545). You can also use a public endpoint from a provider like OnFinality:

curl https://polygon.api.onfinality.io/public \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

For WebSocket subscriptions:

const WebSocket = require('ws');
const ws = new WebSocket('wss://polygon.api.onfinality.io/public');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_subscribe',
    params: ['newHeads'],
    id: 1
  }));
});

ws.on('message', (data) => {
  console.log(data.toString());
});

Polygon node types and their use cases

Self-hosted vs managed RPC: what to consider

When deciding, evaluate:

• Time to deploy – Self-hosting can take days to sync; managed providers offer instant endpoints.
• Maintenance – You must handle upgrades, monitoring, and backups.
• Scalability – Managed providers can handle traffic spikes with load balancing.
• Cost – Self-hosting has fixed hardware costs; managed plans scale with usage.

For most production apps, a managed provider like OnFinality offers a balance of reliability and simplicity. Check our RPC pricing for transparent plans.

Common pitfalls and troubleshooting

• Node out of sync – Check Heimdall and Bor logs. Ensure your system clock is accurate.
• Storage full – Prune old data or increase disk space.
• RPC timeouts – Increase request timeouts or use a provider with better infrastructure.
• WebSocket disconnects – Implement reconnection logic in your client.

If you're using a managed provider, most of these are handled for you.

Key Takeaways

• Polygon nodes run Bor and Heimdall, each serving a distinct role.
• Self-hosting gives control but requires significant operational effort.
• Managed RPC providers like OnFinality offer quick, reliable endpoints for developers.
• Choose node type based on your needs: full, archive, or validator.

Frequently Asked Questions

What is the difference between a Polygon full node and an archive node?

A full node stores the current state and can query recent data, while an archive node stores all historical states, enabling queries at any past block.

How long does it take to sync a Polygon node?

With snapshots, it can take a few hours to a day, depending on hardware and network speed.

Can I use a public RPC endpoint for production?

Public endpoints are fine for development, but for production you should use a dedicated or paid endpoint to avoid rate limits and ensure reliability.

Does OnFinality support Polygon WebSocket?

Yes, OnFinality provides WebSocket support for Polygon. See the Polygon network page for details.

How do I add Polygon to MetaMask?

Use the network details: Chain ID 137, RPC URL https://polygon.api.onfinality.io/public, symbol POL, explorer https://polygonscan.com.

For more networks, visit our supported networks page.