Using the Stellar RPC to Access Real-Time Blockchain Data

The Stellar RPC (formerly Soroban RPC) is the primary interface for accessing real-time blockchain state on the Stellar network. Whether you're querying smart contract data, simulating transactions, or streaming events, the Stellar RPC is your gateway to live network data. This guide covers every method you need to know, with practical code examples.

What Is the Stellar RPC?

The Stellar RPC is a JSON-RPC 2.0 interface that provides real-time access to:

Current ledger state - Latest ledger sequence, protocol version

Transaction simulation - Test transactions before submitting

Contract state - Read smart contract storage entries

Event streaming - Monitor contract events as they happen

Fee estimation - Get current fee statistics for proper transaction pricing

For a comparison of when to use Stellar RPC vs. the Horizon API, read our guide on Horizon API vs Stellar RPC.

Getting Started

Endpoint Configuration

LumenQuery provides managed Stellar RPC access:

# LumenQuery Stellar RPC endpoint
RPC_URL="https://rpc.lumenquery.io"
API_KEY="lq_your_api_key"

# Test connectivity
curl -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "healthy"
  }
}

Sign up for a free LumenQuery account to get your API key. See Getting Started with LumenQuery for a complete setup guide.

Core RPC Methods

getLatestLedger

Returns the current ledger sequence and protocol version. This is the most basic health check for your application:

curl -X POST https://rpc.lumenquery.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getLatestLedger"
  }'

{
  "result": {
    "id": "abc123...",
    "sequence": 62100450,
    "protocolVersion": 21
  }
}

You can see this data visualized on our Analytics Dashboard, which tracks ledger progression in real time.

getNetwork

Returns network passphrase and other configuration:

curl -X POST https://rpc.lumenquery.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getNetwork"
  }'

getLedgerEntries

Read specific ledger entries, including smart contract storage. This is how you query contract state:

curl -X POST https://rpc.lumenquery.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getLedgerEntries",
    "params": {
      "keys": ["AAAA...base64_encoded_key"]
    }
  }'

Our Soroban Smart Contracts Explorer uses this method under the hood to display contract storage entries. You can browse contract state visually using the Storage Viewer.

simulateTransaction

The most important method for smart contract developers. Simulate a transaction to estimate resources, fees, and catch errors before submitting:

async function simulateTransaction(xdr: string) {
  const response = await fetch('https://rpc.lumenquery.io', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.LUMENQUERY_API_KEY!,
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'simulateTransaction',
      params: { transaction: xdr },
    }),
  });

  const data = await response.json();

  if (data.result.error) {
    throw new Error(data.result.error);
  }

  return {
    cost: data.result.cost,
    footprint: data.result.transactionData,
    result: data.result.results,
  };
}

This is exactly the pattern used in LumenQuery's contract deployment feature, which lets you deploy Soroban contracts directly from the browser.

sendTransaction

Submit a signed transaction to the network:

async function submitTransaction(signedXdr: string) {
  const response = await fetch('https://rpc.lumenquery.io', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'sendTransaction',
      params: { transaction: signedXdr },
    }),
  });

  const data = await response.json();
  return data.result; // { hash, status, latestLedger }
}

getTransaction

Check the status of a submitted transaction:

curl -X POST https://rpc.lumenquery.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTransaction",
    "params": {
      "hash": "abc123..."
    }
  }'

Possible statuses: NOT_FOUND, SUCCESS, FAILED. Our Live Transaction Viewer shows decoded transaction results in real time.

getEvents

Query historical events emitted by smart contracts:

async function getContractEvents(contractId: string, startLedger: number) {
  const response = await fetch('https://rpc.lumenquery.io', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'getEvents',
      params: {
        startLedger,
        filters: [{
          type: 'contract',
          contractIds: [contractId],
        }],
        pagination: { limit: 100 },
      },
    }),
  });

  const data = await response.json();
  return data.result.events;
}

The Event Stream feature in Soroban Pro provides real-time SSE streaming of contract events.

getFeeStats

Get current fee statistics for proper transaction pricing:

curl -X POST https://rpc.lumenquery.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getFeeStats"
  }'

Understanding fees is critical—see our documentation on understanding stroops for how fees are denominated on Stellar.

Building a Real-Time Dashboard

Here's a practical example: building a dashboard that monitors ledger progression using Stellar RPC and Horizon API together.

// Poll Stellar RPC for latest ledger
async function pollLedger() {
  const rpcResponse = await fetch('https://rpc.lumenquery.io', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'getLatestLedger',
    }),
  });
  const rpc = await rpcResponse.json();

  // Get detailed ledger info from Horizon
  const horizonResponse = await fetch(
    `https://api.lumenquery.io/ledgers/${rpc.result.sequence}`
  );
  const horizon = await horizonResponse.json();

  return {
    sequence: rpc.result.sequence,
    protocolVersion: rpc.result.protocolVersion,
    transactionCount: horizon.successful_transaction_count,
    operationCount: horizon.operation_count,
    baseFee: horizon.base_fee_in_stroops,
    closedAt: horizon.closed_at,
  };
}

This dual-API approach is exactly what powers our Analytics Dashboard. For more patterns like this, check out our guide on building a Stellar blockchain explorer.

Best Practices

1. Always Simulate First

Never submit a transaction without simulating it. Simulation catches errors, estimates fees, and returns resource limits—all for free.

2. Handle Rate Limits

LumenQuery provides generous rate limits, but your application should handle 429 responses gracefully:

async function rpcCallWithRetry(method: string, params: object, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch('https://rpc.lumenquery.io', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
    });

    if (response.status === 429) {
      await new Promise(r => setTimeout(r, 1000 * (i + 1)));
      continue;
    }

    return response.json();
  }
  throw new Error('Rate limit exceeded after retries');
}

See our API documentation for current rate limit tiers.

3. Cache Where Possible

Ledger data doesn't change once a ledger closes (every ~5 seconds). Cache responses with TTLs:

getLatestLedger - Cache for 3-5 seconds

getLedgerEntries - Cache based on ledger sequence

getFeeStats - Cache for 30 seconds

getHealth - Cache for 10 seconds

4. Use Horizon for Historical Data

Stellar RPC is optimized for real-time state. For historical queries (transaction history, payment streams, offer books), use the Horizon API:

# Historical transactions via Horizon
curl https://api.lumenquery.io/transactions?limit=10&order=desc

# Real-time state via Stellar RPC
curl -X POST https://rpc.lumenquery.io \
  -d '{"jsonrpc":"2.0","method":"getLatestLedger","id":1}'

Or use our Natural Language Query Interface to explore both data sources with plain English questions.

RPC Method Reference

Method	Purpose	Use When
getHealth	Check server status	Monitoring, health checks
getNetwork	Network configuration	Initial setup
getLatestLedger	Current ledger	Dashboard displays
getLedgerEntries	Read ledger state	Contract storage queries
simulateTransaction	Test transaction	Before every submission
sendTransaction	Submit transaction	After simulation + signing
getTransaction	Check tx status	After submission
getTransactions	Batch tx queries	Batch status checking
getEvents	Query contract events	Event monitoring
getFeeStats	Fee estimation	Transaction construction

What's Next

The Stellar RPC is evolving rapidly. The Stellar Foundation roadmap for 2026 includes plans for enhanced event streaming, better state archival, and improved developer tooling.

For developers new to Stellar, start with our Soroban JSON RPC Explained guide for the foundational concepts, then come back here for the practical implementation patterns.

From Soroban to Stellar RPC: What the Rebrand Means

How to Build a Stellar Blockchain Explorer Using Horizon API

Soroban Smart Contracts Explorer Documentation