The Stellar Data Tool is a command line and REST API utility that makes it effortless for developers to access raw blockchain data from Stellar’s public data lake and RPC endpoints. Whether you’re building a blockchain analytics dashboard, auditing transactions, or debugging smart contracts, this tool provides a clean, JSON based interface to Stellar ledger data.
In this tutorial, you’ll learn how to install, run, and use the tool in both CLI and REST API modes, with examples for querying transactions, balances, and smart contract activity.
⚙️ 1. Installation
Clone and build the project from source:
git clone https://github.com/jamesbachini/Stellar-Data.git
cd Stellar-Data
cargo build --release
Once the build completes, the binary will be located at:
./target/release/stellar-data
To make it globally accessible:
sudo cp ./target/release/stellar-data /usr/local/bin/
Now you can run stellar-data from anywhere.
🚀 2. Quick Start with CLI Mode
CLI mode lets you query the Stellar blockchain directly from your terminal.
Use it for quick lookups, scripts, or offline analysis.
Basic Syntax
stellar-data --ledger <LEDGER_NUMBER | RANGE | -N> --query <TYPE> [--address <ADDRESS>]
| Option | Description |
|---|---|
--ledger, -l | Ledger number, range (e.g. 50000000-50000010), or recent (-10) |
--query, -q | Query type: all, transactions, or address |
--address, -a | Filter by a specific Stellar address (required for --query address) |
🧩 Example 1: Query a Single Ledger
Fetch all available data for a specific ledger:
stellar-data --ledger 63864 --query all
This returns a full JSON dump including:
- Ledger header
- Transactions and results
- SCP consensus information
🪄 Example 2: Get All Transactions in a Range
Query a range of ledgers to collect all transactions:
stellar-data --ledger 50000000-50000010 --query transactions
Output includes:
{
"start_sequence": 50000000,
"end_sequence": 50000010,
"count": 7945,
"transactions": [...]
}
⏳ Example 3: Get the Most Recent Ledgers
You can use negative values to query the most recent N ledgers:
stellar-data --ledger -5 --query transactions
The tool automatically detects the latest ledger number via Horizon and works backward.
🧍 Example 4: Filter by Address
Find transactions involving a specific account:
stellar-data --ledger -999 --query address --address GCWGA2XKBSKVAAPN3UKG2V4TA2O4UDOQEVNNND5GPRLBC63DDEUM3G2I
This searches source, destination, and trustline fields for any match to the address.
🌐 3. REST API Mode
For web integrations or continuous queries, run the tool as a REST API server.
Start the Server
stellar-data --server --port 3000
The server will start and show:
Stellar Data API Server
Listening on http://0.0.0.0:3000
API Endpoints Overview
| Endpoint | Description |
|---|---|
/help | Interactive HTML documentation |
/transactions | Query transactions (with optional address filter) |
/all | Get complete ledger data |
/contract | Search contract invocations |
/function | Search specific contract function calls |
/balance | Fetch token balances via RPC |
💡 4. API Examples
All endpoints return JSON, making them easy to use with curl, axios, or fetch.
Example 1: Get Transactions
curl "http://localhost:3000/transactions?ledger=50000000"
Or query a range:
curl "http://localhost:3000/transactions?ledger=50000000-50000005"
Example 2: Search by Address
curl "http://localhost:3000/transactions?ledger=-100&address=GALPCCZN4YXA3YMJHKL6CVIECKPLJJCTVMSNYWBTKJW4K5HQLYLDMZTB"
Example 3: Smart Contract Activity
Search transactions that involve a specific contract:
curl "http://localhost:3000/contract?ledger=-500&address=CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
Or search by function name:
curl "http://localhost:3000/function?ledger=-1000&name=transfer"
Example 4: Token Balances
Query token balances via RPC using shortcuts:
# Native XLM balance
curl "http://localhost:3000/balance?address=GALPCCZN4YXA3YMJHKL6CVIECKPLJJCTVMSNYWBTKJW4K5HQLYLDMZTB&token=xlm"
# USDC balance
curl "http://localhost:3000/balance?address=GALPCCZN4YXA3YMJHKL6CVIECKPLJJCTVMSNYWBTKJW4K5HQLYLDMZTB&token=usdc"
Response example:
{
"address": "GALPCCZ...",
"token": "xlm",
"balance": "1121995790"
}
🧠 5. How It Works (Under the Hood)
The Stellar Data Tool automatically determines the correct data lake paths for each ledger, downloads the .xdr.zst files, decompresses them, and parses the binary data into structured JSON.
Stellar RPC nodes hold data for 7 days, after that the information is archived in the data lake. This tool queries the data lake directly for historical archived data and also has the ability to query RPC nodes for most recent data.
This dual-source design ensures:
- ✅ Access to historical and real-time data
- ✅ Redundancy when public data is incomplete
- ✅ Seamless developer experience
🧩 6. Common Use Cases
| Use Case | Example |
|---|---|
| Blockchain Analytics | Aggregate transactions over ledger ranges |
| Address Tracking | Monitor payments to/from a wallet |
| Smart Contract Debugging | Inspect function calls to deployed Soroban contracts |
| Token Insights | Check balances or trace token transfers |
| Backend Integrations | Expose Stellar data to a dashboard or service |
🧾 8. Galaxie
What if you need all the data, the entire chain?
Galexie is designed to make working with Stellar network data dramatically more accessible and efficient. Historically, extracting the full ledger history has required heavy infrastructure and complex synchronization between Stellar Core, Horizon, and other transformation tools. This made it difficult for developers to independently access and manipulate raw network data at scale. Galexie solves this problem by providing a lightweight, purpose built extractor that decouples data ingestion from transformation.
https://github.com/stellar/go/tree/master/services/galexie
It enables anyone to export and store the entire Stellar ledger history in a cloud based data lake, offering a ready to query foundation that can be reused by different analytics, indexing, or monitoring applications without repeatedly running costly ingestion pipelines.
Download the Entire Chain
By allowing users to download and maintain a complete copy of the Stellar ledger, Galexie ensures full transparency and reproducibility of network data. Its efficient compression and partitioning system makes it possible to handle vast amounts of historical data over a decade of ledger history at relatively low cost.
The output is fully compatible with existing Stellar data formats like XDR, so tools such as Hubble and Horizon can consume it directly without modification.
The Stellar Data Tool bridges the gap between raw ledger data and developer-friendly APIs.
By combining direct access to Stellar’s public data lake with intelligent RPC fallback, it enables:
- Complete historical visibility
- Real-time blockchain analytics
- Simple, scriptable integration for any environment
If this projects gets widely used and devs find it useful I’ll look into setting up a public API that everyone can use.
