What are Stellar nodes and how do you connect to the network?

Quick decision guide: Do you need to run a Stellar node or just connect to one?

Before diving into node types and setup, ask yourself what you actually need. Most applications do not need to run a Stellar node. If you are building a wallet, an exchange integration, or a payment app, you need reliable access to the network's data and the ability to submit transactions. Running your own node gives you full control and data privacy, but it comes with operational overhead: syncing, monitoring, and keeping up with protocol upgrades.

If you are just starting out or your traffic is moderate, using a managed RPC service like OnFinality's Stellar RPC is the fastest path. You get a public endpoint for testing and scalable access for production without managing infrastructure. If you have strict data residency or compliance needs, or you expect very high request volumes, a dedicated node might be worth the cost. For most teams, the decision comes down to: do you want to spend engineering time on node operations, or on your product?

What is a Stellar node?

A Stellar node is a computer that runs the Stellar Core software, which implements the Stellar Consensus Protocol (SCP). Nodes communicate with each other to agree on the state of the ledger. Unlike proof-of-work or proof-of-stake networks, Stellar uses a federated Byzantine agreement system. Each node chooses a set of trusted validators, called a quorum slice, and consensus is reached when enough nodes agree.

There are different roles a node can play:

• Validator: Participates in consensus by proposing and voting on transaction sets. Validators are the backbone of the network's agreement.
• Full node: Maintains a complete copy of the ledger and validates all transactions, but does not necessarily participate in consensus. Full nodes provide data to clients and help with network health.
• Archive node: Stores historical ledger data, enabling new nodes to sync from snapshots and providing data for analytics.

For most developers, the distinction matters less than the access method. You interact with the network through an API, typically Horizon or Soroban RPC, which we'll cover below.

Stellar node types compared

Validators are critical for network operation, but they are not something most developers need to run. Full nodes are more common for teams that want to self-host Horizon or need direct access to ledger data. Archive nodes are for specialized use cases.

How to run a Stellar node

Running a Stellar node involves installing Stellar Core and configuring it to connect to the network. The process is well-documented in the official Stellar documentation, but here is a high-level overview.

Prerequisites

• A server with at least 8 GB of RAM and a few hundred GB of storage (the ledger grows over time).
• A public IP address if you want to participate in the network.
• Basic familiarity with Linux and command-line tools.

Installation steps

1. Install Stellar Core: You can download pre-built binaries or build from source. The official docs provide instructions for various operating systems.
2. Configure stellar-core.cfg: This file contains your node's identity, network settings, and quorum set. You need to specify the network passphrase (e.g., Public Global Stellar Network ; September 2015 for mainnet).
3. Sync with the network: The initial sync can take hours or days, depending on your hardware and network speed. You can speed this up by using a snapshot from an archive node.
4. Run Horizon: If you want to provide an HTTP API for your applications, you'll also need to run Horizon, which connects to Stellar Core and indexes data.

Here is a minimal example of a stellar-core.cfg snippet:

[NETWORK]
NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"

[QUORUM_SET]
VALIDATORS="GCGB2S2KjARzYHe1i4EsnDWxFiUlytK8vH8D2UfJ7VvH4ZqYg"

[HTTP]
PORT=11626

This is a simplified example. In practice, you need to include more validators in your quorum set and configure database connections.

Connecting to Stellar: Horizon and Soroban RPC

Once you have a node running (or you're using a third-party service), you interact with Stellar through APIs. The two main interfaces are:

• Horizon: A RESTful API that provides access to accounts, transactions, and ledger data. It's the traditional way to build on Stellar.
• Soroban RPC: A JSON-RPC API for interacting with Soroban smart contracts, introduced with the Soroban upgrade.

Most developers use Horizon for basic operations and Soroban RPC for contract interactions. If you're using a managed provider, you get endpoints for both.

For example, to get account details via Horizon, you can use a simple curl command:

curl https://horizon.stellar.org/accounts/GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF

Replace the address with a real one. This returns JSON with the account's balance, sequence number, and other data.

Stellar RPC endpoints and configuration

When you use a third-party RPC provider, you typically get a URL that points to a Horizon or Soroban RPC instance. OnFinality offers a public Stellar endpoint that you can use for development. For production, you should sign up for an API key to get higher rate limits and reliability.

The base URL for OnFinality's public Stellar endpoint is https://stellar.rpc.onfinality.io. You can append paths for Horizon or Soroban RPC depending on the service. For example, to make a Soroban RPC call, you might use:

curl -X POST https://stellar.rpc.onfinality.io/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth","params":[]}'

This is a simple health check. The exact methods and paths are documented in the Stellar developer docs.

Common pitfalls when working with Stellar nodes

Even with a managed service, you might run into issues. Here are some common pitfalls and how to avoid them:

• Using the wrong network: Stellar has a mainnet and a testnet (called Futurenet). Make sure your configuration uses the correct network passphrase and endpoint.
• Rate limiting: Public endpoints often have rate limits. If you're making many requests, use a dedicated endpoint or add caching.
• Horizon cursor and pagination: When streaming transactions, you need to handle pagination correctly. Use the cursor parameter to avoid missing events.
• Soroban RPC method differences: Soroban RPC is JSON-RPC, but the methods are different from Ethereum's. Refer to the official docs.

Key Takeaways

• Stellar nodes run Stellar Core and participate in consensus or serve data.
• Most applications do not need to run a node; use a managed RPC service for simplicity.
• Horizon is the REST API for accounts and transactions; Soroban RPC is for smart contracts.
• When choosing a provider, consider rate limits, uptime, and support for both Horizon and Soroban RPC.
• OnFinality provides public and dedicated Stellar endpoints; check RPC pricing and supported networks for details.

Frequently Asked Questions

What is the difference between a Stellar node and a validator?

A validator is a node that participates in consensus. All validators are nodes, but not all nodes are validators. Full nodes and archive nodes serve data but do not necessarily vote.

How long does it take to sync a Stellar node?

Initial sync can take from a few hours to a few days, depending on your hardware and network. Using a snapshot from an archive node can significantly reduce this time.

Can I run a Stellar node on a laptop?

Technically yes, but it's not recommended. The ledger is large and grows continuously. You need a server with reliable storage and network connectivity.

What is Soroban RPC?

Soroban RPC is a JSON-RPC API for interacting with Soroban smart contracts on Stellar. It allows you to submit transactions, read contract state, and simulate contract calls.

How do I choose between running my own node and using a managed service?

If you need full control, data privacy, or have very high traffic, a dedicated node might be worth it. For most projects, a managed service like OnFinality offers a good balance of cost and reliability. Evaluate your team's operational capacity and your application's requirements.