What is a Stellar RPC server and how do you use it?

Quick decision guide: run your own or use a provider?

Before you dig into endpoints and methods, decide how you want to access Stellar RPC. The choice affects your operational overhead, data retention, and cost.

• Run your own Stellar RPC server if you need full control over your infrastructure, want to avoid third-party dependencies, or need to customize the RPC configuration. This requires running Stellar Core and managing a captive core instance, which is non-trivial.
• Use a managed Stellar RPC provider if you want to focus on your application logic rather than node operations. Providers handle uptime, scaling, and maintenance. OnFinality offers a public Stellar mainnet endpoint and dedicated node options, which you can explore on the Stellar network page.

For production Soroban apps, a dedicated node or a private endpoint is usually the right fit because public endpoints often have rate limits and shared performance. If you are just prototyping, a public endpoint is fine.

What is a Stellar RPC server?

A Stellar RPC server is a lightweight service that provides real-time access to Stellar network data. It is the recommended way for developers to query the network, submit transactions, and interact with Soroban smart contracts. The server exposes a JSON-RPC API that lets you read ledger state, account balances, and transaction status.

Stellar RPC is not an indexer. It retains only a bounded, recent window of history—about 7 days by default. It is also not a drop-in replacement for Horizon, which provides indexing features that RPC does not. Use RPC as your gateway to the blockchain, but ingest and index only the data you care about.

Stellar RPC vs Horizon: what's the difference?

Stellar RPC and Horizon serve different purposes. Horizon is a RESTful API that indexes and serves historical data, while Stellar RPC is a JSON-RPC API that provides real-time state and transaction submission. If you need historical transaction data or want to query by account, Horizon is more suitable. If you need to interact with Soroban contracts or submit transactions directly, Stellar RPC is the right tool.

How to connect to a Stellar RPC server

You can connect to a Stellar RPC server using cURL or one of the Stellar SDKs. The endpoint is a URL that accepts JSON-RPC requests. For example, the OnFinality public Stellar mainnet endpoint is https://stellar.api.onfinality.io/public. You can find more details on the Stellar network page.

Here is a basic cURL example to get the latest ledger:

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

This returns the latest ledger sequence and other metadata. You can use similar requests to query account balances, contract data, and transaction status.

Common Stellar RPC methods you'll use

Stellar RPC exposes a set of JSON-RPC methods. Here are the ones you will use most often:

• getLatestLedger – returns the latest ledger sequence and metadata.
• getLedgerEntries – retrieves ledger entries for accounts, contracts, and other data.
• getTransaction – fetches the status and result of a submitted transaction.
• sendTransaction – submits a transaction to the network.
• simulateTransaction – simulates a transaction to estimate fees and results.
• getEvents – queries for contract events.
• getNetwork – returns network information like the passphrase and protocol version.

For a full list, refer to the Stellar RPC documentation.

Setting up a wallet or dApp with Stellar RPC

If you are building a wallet or dApp, you will need to configure your SDK to point to a Stellar RPC endpoint. Here is an example using the Stellar JavaScript SDK:

import { SorobanRpc } from '@stellar/stellar-sdk';

const server = new SorobanRpc.Server('https://stellar.api.onfinality.io/public');

const latestLedger = await server.getLatestLedger();
console.log(latestLedger.sequence);

Make sure you use the correct endpoint for your network (mainnet, testnet, or futurenet). OnFinality provides a public mainnet endpoint, and you can find testnet options on the supported networks page.

Troubleshooting Stellar RPC connection issues

If you are having trouble connecting to a Stellar RPC server, check the following:

• Network mismatch: Ensure you are using the correct endpoint for the network you intend to use (mainnet vs testnet).
• Rate limits: Public endpoints may have rate limits. If you hit them, consider upgrading to a dedicated node or private endpoint.
• CORS issues: If you are calling from a browser, ensure the provider supports CORS. OnFinality's public endpoint supports CORS for development.
• Transaction errors: If sendTransaction fails, check the transaction envelope and simulate it first to catch errors.

For more advanced troubleshooting, consider using a dedicated node to avoid shared infrastructure issues.

Running your own Stellar RPC server

If you decide to run your own Stellar RPC server, you will need to set up Stellar Core and a captive core instance. The official repository stellar/stellar-rpc provides an admin guide. This approach gives you full control but requires ongoing maintenance and monitoring.

Most teams find that using a managed provider is more cost-effective, especially for production workloads. OnFinality offers dedicated Stellar nodes that can be provisioned on demand. Check the dedicated node page for more information.

Key Takeaways

• Stellar RPC is a lightweight JSON-RPC server for real-time network data and Soroban contract interaction.
• It is not an indexer; it retains only a recent window of history.
• Choose between running your own server or using a managed provider based on your operational capacity and workload.
• Use public endpoints for development, but consider dedicated nodes for production.
• Always test with real requests and monitor rate limits.

Frequently Asked Questions

What is the difference between Stellar RPC and Horizon?

Stellar RPC is a JSON-RPC API for real-time state and Soroban contracts, while Horizon is a REST API for historical data and indexing. They serve different purposes and can be used together.

Can I use Stellar RPC for historical data?

Stellar RPC retains only a bounded, recent window of history (about 7 days). For historical data, use Horizon or an archive provider that supports the getLedgers method.

How do I get a dedicated Stellar RPC endpoint?

You can get a dedicated endpoint from providers like OnFinality. Visit the Stellar network page to see options for dedicated nodes and private endpoints.

What are the rate limits for public Stellar RPC endpoints?

Rate limits vary by provider. Public endpoints often have fair-use policies. For production, consider a dedicated node to avoid throttling.

Does OnFinality support Stellar testnet?

OnFinality currently provides a public Stellar mainnet endpoint. For testnet, you can use other providers or run your own. Check the supported networks page for the latest availability.

For more details on pricing and network support, see RPC pricing and supported RPC networks.