data
Querying Stellar chain data via Stellar RPC (preferred) and Horizon (legacy). Covers RPC JSON-RPC methods, Horizon REST endpoints, streaming, pagination, historical queries, Hubble/Galexie for deep history, and the RPC/Horizon migration story. Use when reading balances, transactions, operations, ledgers, contract events, or building any indexer/analytics workflow.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 6
- Forks
- 3
01 前言 Front Matter
- name
- data
- metadata
- { "argument-hint": "[data task]", "user-invocable": "true" }
- description
- Querying Stellar chain data via Stellar RPC (preferred) and Horizon (legacy). Covers RPC JSON-RPC methods, Horizon REST endpoints, streaming, pagination, historical queries, Hubble/Galexie for deep history, and the RPC/Horizon migration story. Use when reading balances, transactions, operations, ledgers, contract events, or building any indexer/analytics workflow.
02 资源文件 30
- 参考文档electric-capital/stellar-repos.json939.0 KB
- 参考文档guides/a16z-big-ideas-2025.md20.4 KB
- 参考文档guides/a16z-state-of-crypto-2025.md25.9 KB
- 参考文档guides/alliance-ideas.md3.1 KB
- 参考文档guides/building-with-ai/mexico-hackathon.md4.5 KB
- 参考文档guides/building-with-ai/README.md7.2 KB
- 参考文档guides/defi/README.md3.9 KB
- 参考文档guides/fca00c/instructions.md3.5 KB
- 参考文档guides/fca00c/README.md2.4 KB
- 参考文档guides/indexers/providers.md7.1 KB
- 参考文档guides/indexers/README.md3.3 KB
- 参考文档guides/infrastructure/README.md7.6 KB
- 参考文档guides/learning/README.md6.7 KB
- 参考文档guides/LINKS.md1.0 KB
- 参考文档guides/oracles/README.md3.2 KB
- 参考文档guides/security/README.md4.9 KB
- 参考文档guides/soroban-development/README.md7.2 KB
- 参考文档guides/tokens/README.md6.5 KB
- 参考文档guides/yc-crypto-companies-p2.md15.5 KB
- 参考文档guides/yc-crypto-companies.md33.5 KB
- 参考文档guides/yc-requests-for-startups.md12.4 KB
- 参考文档ideas/a16z-big-ideas-2025.json40.2 KB
- 参考文档ideas/a16z-state-of-crypto-2025.json25.1 KB
- 参考文档ideas/alliance-ideas.json27.2 KB
- 参考文档ideas/yc-crypto-companies.json151.2 KB
- 参考文档ideas/yc-requests-for-startups.json20.6 KB
- 参考文档lumenloop/audits/registry.json14.2 KB
- 参考文档lumenloop/projects.json711.3 KB
- 参考文档lumenloop/scf/rounds.json77.2 KB
- 参考文档lumenloop/tokens/registry.json4.3 KB
03 SKILL.md 正文
Stellar Data: RPC + Horizon
API access for reading chain state. Stellar RPC is the preferred entry point for new projects; Horizon remains for legacy and historical-query workflows. For deeper history beyond RPC's 7-day window, use Hubble/Galexie.
When to use this skill
- Calling Stellar RPC methods (
getLatestLedger,getLedgerEntries,getEvents,simulateTransaction,sendTransaction) - Querying Horizon endpoints (accounts, transactions, operations, effects, ledgers)
- Streaming live events or operations
- Pulling historical data beyond RPC's 7-day window (Hubble, Galexie)
- Choosing between RPC and Horizon for a given workflow
Related skills
- Building transactions to send →
../dapp/SKILL.md - Soroban contract simulation and event emission →
../soroban/SKILL.md - Asset balance and trustline lookups →
../assets/SKILL.md - Standards (SEP-7 deeplinks, SEP-10 auth) →
../standards/SKILL.md
Overview
Stellar provides two API paradigms:
| API | Status | Use Case |
|---|---|---|
| Stellar RPC | Preferred | Soroban, real-time state, new projects |
| Horizon | Legacy-focused | Historical data, legacy applications |
Recommendation: Use Stellar RPC for all new projects. Use Horizon mainly for historical queries and legacy compatibility paths.
Quick Navigation
- RPC methods and usage: Stellar RPC
- Horizon endpoints and streaming: Horizon API (Legacy)
- Migration strategy: Migration: Horizon to RPC
- Data history/indexing options: Historical Data Access
- Environment setup and endpoints: Network Configuration
Stellar RPC
Endpoints
Note: SDF directly provides Futurenet public RPC. For Mainnet RPC, select a provider from the RPC providers directory.
| Network | RPC URL |
|---|---|
| Mainnet | Provider-specific endpoint (see RPC providers directory) |
| Testnet | https://soroban-testnet.stellar.org |
| Futurenet | https://rpc-futurenet.stellar.org |
| Local | http://localhost:8000/soroban/rpc |
Setup
import * as StellarSdk from "@stellar/stellar-sdk";
const rpc = new StellarSdk.rpc.Server("https://soroban-testnet.stellar.org");
Key Methods
Get Account
const account = await rpc.getAccount(publicKey);
// Returns account with sequence number for transaction building
Get Health
const health = await rpc.getHealth();
// { status: "healthy" }
Get Latest Ledger
const ledger = await rpc.getLatestLedger();
// { id: "...", sequence: 123456, protocolVersion: 25 }
Get Ledger Entries
// Read contract storage
const key = StellarSdk.xdr.LedgerKey.contractData(
new StellarSdk.xdr.LedgerKeyContractData({
contract: new StellarSdk.Address(contractId).toScAddress(),
key: StellarSdk.xdr.ScVal.scvSymbol("Counter"),
durability: StellarSdk.xdr.ContractDataDurability.persistent(),
})
);
const entries = await rpc.getLedgerEntries(key);
if (entries.entries.length > 0) {
const value = StellarSdk.scValToNative(
entries.entries[0].val.contractData().val()
);
}
Simulate Transaction
const simulation = await rpc.simulateTransaction(transaction);
if (StellarSdk.rpc.Api.isSimulationError(simulation)) {
console.error("Simulation failed:", simulation.error);
} else if (StellarSdk.rpc.Api.isSimulationSuccess(simulation)) {
console.log("Cost:", simulation.cost);
console.log("Result:", simulation.result);
}
Send Transaction
const response = await rpc.sendTransaction(signedTransaction);
if (response.status === "PENDING") {
// Poll for result
let result = await rpc.getTransaction(response.hash);
while (result.status === "NOT_FOUND") {
await new Promise(r => setTimeout(r, 1000));
result = await rpc.getTransaction(response.hash);
}
if (result.status === "SUCCESS") {
console.log("Success:", result.returnValue);
} else {
console.error("Failed:", result.status);
}
}
Get Transaction
const tx = await rpc.getTransaction(txHash);
// status: "SUCCESS" | "FAILED" | "NOT_FOUND"
// returnValue: ScVal (for contract calls)
// ledger: number
Get Events
const events = await rpc.getEvents({
startLedger: 1000000,
filters: [
{
type: "contract",
contractIds: [contractId],
topics: [
["*", StellarSdk.xdr.ScVal.scvSymbol("transfer").toXDR("base64")],
],
},
],
});
for (const event of events.events) {
console.log("Event:", event.topic, event.value);
}
RPC Limitations
- 7-day history for most methods:
getTransaction,getEvents, etc. only cover recent data getLedgersexception: "Infinite Scroll" feature queries any ledger back to genesis via the data lake- No streaming: Poll for updates (no WebSocket)
- Contract-focused: Limited classic Stellar data
Horizon API (Legacy)
Endpoints
| Network | Horizon URL |
|---|---|
| Mainnet | https://horizon.stellar.org |
| Testnet | https://horizon-testnet.stellar.org |
| Local | http://localhost:8000 |
Setup
import * as StellarSdk from "@stellar/stellar-sdk";
const server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
Common Operations
Load Account
const account = await server.loadAccount(publicKey);
// Full account details including balances, signers, data
Get Account Balances
const account = await server.loadAccount(publicKey);
for (const balance of account.balances) {
if (balance.asset_type === "native") {
console.log("XLM:", balance.balance);
} else {
console.log(`${balance.asset_code}:`, balance.balance);
}
}
Get Transactions
// Account transactions
const transactions = await server
.transactions()
.forAccount(publicKey)
.order("desc")
.limit(10)
.call();
// Specific transaction
const tx = await server
.transactions()
.transaction(txHash)
.call();
Get Operations
const operations = await server
.operations()
.forAccount(publicKey)
.order("desc")
.limit(20)
.call();
for (const op of operations.records) {
console.log(op.type, op.created_at);
}
Get Payments
const payments = await server
.payments()
.forAccount(publicKey)
.order("desc")
.call();
for (const payment of payments.records) {
if (payment.type === "payment") {
console.log(
`${payment.from} -> ${payment.to}: ${payment.amount} ${payment.asset_code || "XLM"}`
);
}
}
Get Effects
const effects = await server
.effects()
.forAccount(publicKey)
.limit(50)
.call();
Streaming (Server-Sent Events)
// Stream transactions
const closeHandler = server
.transactions()
.forAccount(publicKey)
.cursor("now")
.stream({
onmessage: (tx) => {
console.log("New transaction:", tx.hash);
},
onerror: (error) => {
console.error("Stream error:", error);
},
});
// Close stream when done
closeHandler();
Submit Transaction
try {
const result = await server.submitTransaction(signedTransaction);
console.log("Success:", result.hash);
} catch (error) {
if (error.response?.data?.extras?.result_codes) {
console.error("Error codes:", error.response.data.extras.result_codes);
}
}
Pagination
// First page
let page = await server.transactions().forAccount(publicKey).limit(10).call();
// Next page
if (page.records.length > 0) {
page = await page.next();
}
// Previous page
page = await page.prev();
Migration: Horizon to RPC
Account Loading
// Horizon (old)
const account = await horizonServer.loadAccount(publicKey);
// RPC (new)
const account = await rpc.getAccount(publicKey);
// Note: RPC returns less data, just what's needed for transactions
Transaction Submission
// Horizon (for classic transactions)
const result = await horizonServer.submitTransaction(tx);
// RPC (for Soroban transactions)
const response = await rpc.sendTransaction(tx);
const result = await pollForResult(response.hash);
Historical Data
// Horizon - full history
const allTxs = await horizonServer
.transactions()
.forAccount(publicKey)
.call();
// RPC - most methods limited to 7 days
// Exception: getLedgers can query back to genesis (Infinite Scroll)
// For full historical data, use:
// 1. Hubble (SDF's BigQuery dataset)
// 2. Galexie (data pipeline)
// 3. Your own indexer
Streaming Replacement
// Horizon - native streaming
server.payments().stream({ onmessage: handlePayment });
// RPC - polling (no native streaming)
async function pollForUpdates() {
const lastLedger = await rpc.getLatestLedger();
// Check for new events/transactions
// Repeat on interval
}
setInterval(pollForUpdates, 5000);
Historical Data Access
For data older than 7 days (not available via most RPC methods; getLedgers can reach genesis via Infinite Scroll):
Hubble (BigQuery)
-- Query Stellar data in BigQuery
SELECT *
FROM `crypto-stellar.crypto_stellar.history_transactions`
WHERE source_account = 'G...'
ORDER BY created_at DESC
LIMIT 100
Galexie
Self-hosted data pipeline for processing Stellar ledger data:
Data Lake
RPC "Infinite Scroll" is powered by the Stellar data lake - a cloud-based object store (SEP-0054 format):
- Public access:
s3://aws-public-blockchain/v1.1/stellar/ledgers/pubnet(AWS Open Data) - Self-host: Use Galexie to export to AWS S3 or Google Cloud Storage
- Hosted: Quasar (Lightsail Network) provides hosted Galexie Data Lake + Archive RPC endpoints
- Size: ~3.8TB, growing ~0.5TB/year
- Cost: ~$160/month self-hosted ($60 compute + $100 storage)
- Docs: https://developers.stellar.org/docs/data/apis/rpc/admin-guide/data-lake-integration
Third-Party Indexers
For complex queries, event streaming, or custom data pipelines beyond what RPC/Horizon provide:
- Mercury - Stellar-native indexer with Retroshades, GraphQL API (https://mercurydata.app)
- SubQuery - Multi-chain indexer with Stellar/Soroban support, event handlers (https://subquery.network)
- Goldsky - Real-time data replication pipelines and subgraphs (https://goldsky.com)
- StellarExpert API - Free, no-auth REST API for assets, accounts, ledger resolution (https://stellar.expert/openapi.html)
See the full indexer directory: https://developers.stellar.org/docs/data/indexers
Network Configuration
For a React/Next.js-specific setup, see frontend-stellar-sdk.md. For mainnet RPC, set
STELLAR_MAINNET_RPC_URLfrom a provider in the RPC providers directory.
Environment-Based Setup
// lib/stellar-config.ts
import * as StellarSdk from "@stellar/stellar-sdk";
type NetworkConfig = {
rpcUrl: string;
horizonUrl: string;
networkPassphrase: string;
friendbotUrl: string | null;
};
const requireEnv = (name: string): string => {
const value = process.env[name];
if (!value) throw new Error(`Missing required env var: ${name}`);
return value;
};
const configs: Record<string, NetworkConfig> = {
mainnet: {
rpcUrl: requireEnv("STELLAR_MAINNET_RPC_URL"),
horizonUrl: "https://horizon.stellar.org",
networkPassphrase: StellarSdk.Networks.PUBLIC,
friendbotUrl: null,
},
testnet: {
rpcUrl: "https://soroban-testnet.stellar.org",
horizonUrl: "https://horizon-testnet.stellar.org",
networkPassphrase: StellarSdk.Networks.TESTNET,
friendbotUrl: "https://friendbot.stellar.org",
},
local: {
rpcUrl: "http://localhost:8000/soroban/rpc",
horizonUrl: "http://localhost:8000",
networkPassphrase: "Standalone Network ; February 2017",
friendbotUrl: "http://localhost:8000/friendbot",
},
};
const network = process.env.STELLAR_NETWORK || "testnet";
export const config = configs[network];
export const rpc = new StellarSdk.rpc.Server(config.rpcUrl);
export const horizon = new StellarSdk.Horizon.Server(config.horizonUrl);
Best Practices
Use RPC for:
- New application development
- Soroban contract interactions
- Transaction simulation and submission
- Real-time account state
Use Horizon for:
- Historical transaction queries
- Payment streaming
- Legacy application maintenance
- Rich account metadata
Error Handling
// RPC errors
try {
const result = await rpc.sendTransaction(tx);
} catch (error) {
if (error.code === 400) {
// Invalid transaction
} else if (error.code === 503) {
// Service unavailable
}
}
// Horizon errors
try {
const result = await horizon.submitTransaction(tx);
} catch (error) {
const extras = error.response?.data?.extras;
if (extras?.result_codes) {
// Detailed error codes
console.log("Transaction:", extras.result_codes.transaction);
console.log("Operations:", extras.result_codes.operations);
}
}
Rate Limiting
Both RPC and Horizon have rate limits:
- Use exponential backoff for retries
- Cache responses where appropriate
- Consider running your own nodes for high-volume applications
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
let lastError: Error;
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
lastError = error;
if (error.response?.status === 429) {
// Rate limited - exponential backoff
await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
} else {
throw error;
}
}
}
throw lastError;
}
04 同仓库更多 Skills
zk-proofs
Zero-knowledge proofs and privacy patterns on Stellar. Covers Groth16 verification in smart contracts via BLS12-381 host functions (CAP-0059, available), the BN254 + Poseidon proposals (CAP-0074/0075, status-sensitive), and concrete toolchain walkthroughs for Circom (on-chain verifiable today), Noir, and RISC Zero (attestation pattern until BN254 lands). Use when building privacy-preserving applications, ZK-verifier contracts, or wiring a proving toolchain to Stellar.
tyler-architect
System architect and technical design leader. Use when the user asks to talk to Tyler or requests the architect.
stellar-help
Analyzes current state and user query to answer BMad questions or recommend the next skill(s) to use. Use when user asks for help, bmad help, what to do next, or what to start with in BMad.
stellar-competitive-landscape
Map the competitive landscape for a Stellar project idea. Use when a user says "who are my competitors on Stellar", "competitive analysis Stellar", "what already exists in this space on Stellar", "show me similar Stellar projects", "is anyone else building this on Stellar", or "map the Stellar landscape for X". Queries the 728-project LumenLoop ecosystem database and Electric Capital developer activity to rank competitors by SCF funding history and repo activity.
standards
Stellar standards, ecosystem, and reference. Covers SEPs (Stellar Ecosystem Proposals), CAPs (Core Advancement Proposals), and a quick map for picking the right standard for wallets, anchors, payments, deposits/withdrawals, federation, deep links, and KYC. Also bundles ecosystem references (DeFi protocols, dev tools, wallets, infra, community projects), curated documentation links, and MCP servers (live tools such as Raven). Use when you need to know which SEP applies, or want a starting point for ecosystem integrations, official docs, or live MCP tooling.
smart-contracts
Stellar smart contract development (Rust, soroban-sdk). Entry point with project setup, contract anatomy, and build/deploy workflow, routing to three companion files in this directory - development.md (storage/TTL, authorization, cross-contract calls, tokens, events, errors, upgrades, fees, troubleshooting), testing.md (unit, fuzz, property, fork, mutation, integration), and security.md (vulnerability classes, checklists, tooling, audits). Use when writing, testing, reviewing, securing, debugging, or shipping Stellar smart contracts, including anything the user calls "Soroban" - Soroban contracts, soroban-sdk, Soroban auth/storage/TTL errors, SEP-41 tokens, or SAC integration from contract code.