🔍 Stellar API Inspector

A command-line inspection and health-checking tool for Stellar Horizon and Soroban RPC endpoints. Validate network synchronization, track rate limits, audit account signers/balances, and diagnose performance bottlenecks.

Features

🌐 Horizon Inspection: Connect to any Horizon endpoint and retrieve synchronization status, fee statistics, network protocol, and ledger ranges.
⚡ Soroban RPC Health: Retrieve health details, transaction submission state, latest ledger information, and network parameters.
🔧 Soroban RPC Capabilities: Inspect supported RPC methods, endpoint capabilities, and compatibility information.
🔎 Soroban Transaction Inspection: Inspect execution status, contract events, diagnostic events, resource usage, and fee breakdown for any submitted Soroban transaction.
🧬 Soroban Contract Inspection: Retrieve contract instance metadata, WASM code hash, ledger footprint, storage counts, and TTL expiration warnings.
📜 Transaction Operation Analysis: Fetch any Stellar transaction from Horizon and decode each operation into human-readable descriptions, with asset movement summaries and JSON output.
🧾 Sponsorship Audit: Inspect an account's sponsorship counters and sponsored trustline/signer metadata.
🛡️ Account Auditor: Detailed structural audits of accounts: analyze thresholds, verify signer weights (multi-sig checks), inspect asset balances, and detect trustline authorization/limit risks.
💧 Liquidity Pool Inspection: Inspect pool reserves, shares, fee configuration, derived ratios, and optional recent activity.
📈 Market Trade History: Retrieve recent trades for any Stellar asset pair, display per-trade details, and compute summary statistics (volume, average/high/low price).
📊 Account Offers & Claimable Balances: Inspect open account offers, grouped trading pairs, and claimable balance predicates.
📜 Operations History: Fetch Horizon operations, filter by account/type/limit, and normalize common operation details.
🧭 Interactive Mode: Launch a guided menu when the CLI is run without arguments.
⏱️ Rate Limit Tracker: Read and analyze HTTP headers (X-Ratelimit-Limit, X-Ratelimit-Remaining, X-Ratelimit-Reset) to help avoid rate limits in production.
📋 Health Dashboard: Benchmark latency, check synchronization, and compare performance across multiple endpoints concurrently.
� Network Passphrase Inspection: Validate known Stellar networks, inspect custom passphrases, and identify whether a passphrase matches Mainnet, Testnet, or Futurenet.
�💾 Multiple Output Formats: Supports clean, human-readable CLI tables, raw JSON for automated scripting, or markdown exports.

Installation

Ensure you have Node.js (>= 18.0.0) installed.

Clone the repository and install dependencies:

git clone https://github.com/your-org/stellar-api-inspector.git
cd stellar-api-inspector
npm install

Build the project:

npm run build

Usage

Use the CLI driver via npm run dev or run the compiled output using node dist/cli/index.js.

Interactive Mode

Run the CLI without arguments to launch a guided prompt workflow:

npm run dev

The interactive menu can collect inputs for Horizon inspection, Soroban inspection, account audit, health dashboard, transaction XDR decoding, operations history, and contract inspection. Before execution it prints a command summary and asks for confirmation.

Network Passphrase Inspection

Inspect Stellar network passphrases and determine whether a supplied value matches a built-in network or represents a custom configuration:

npm run dev -- network
npm run dev -- network --passphrase testnet
npm run dev -- network --passphrase "Custom Network ; Local" --json

The command lists the built-in networks (Public Network, Testnet, and Futurenet) and reports whether the supplied value is known or custom. Empty input is rejected with a clear error.

Horizon Endpoint Check

Verify that a Horizon endpoint is reachable, measure response latency, and display network metadata (passphrase, protocol version, Horizon/Core versions):

npm run dev -- horizon https://horizon-testnet.stellar.org

Example output includes response latency in milliseconds, network passphrase, protocol version, and software versions. Invalid URLs are rejected before connecting. Offline endpoints exit with code 1.

Rate Limit Headers

When a Horizon server exposes rate limit headers (X-Ratelimit-Limit, X-Ratelimit-Remaining, X-Ratelimit-Reset), they are automatically parsed and displayed in the inspection table:

Field	Description
Rate Limit (Max)	Total requests allowed per window
Rate Limit (Remaining)	Remaining requests, shown as `count (percent%)`
Rate Limit (Resets In)	Time until the window resets, formatted as `45s` or `1m 30s`

The remaining quota is color-coded for quick scanning:

Green — plenty of quota remaining (≥ 50%)
Yellow — moderately used (10–49%)
Red ⚠ LOW — below 10% — at risk of throttling

Horizon deployments that do not emit these headers show no rate limit rows — there are no errors or placeholder values.

# JSON output — rate limit fields included alongside all other metadata
npm run dev -- horizon https://horizon-testnet.stellar.org --json

JSON output structure (rate limit fields):

{
  "ok": true,
  "data": {
    "info": {
      "url": "https://horizon-testnet.stellar.org",
      "status": "online",
      "latencyMs": 58,
      "rateLimit": {
        "limit": 3600,
        "remaining": 3540,
        "resetSeconds": 42,
        "usedPercent": 2,
        "remainingPercent": 98,
        "isLow": false,
        "hasRateLimitInfo": true
      }
    }
  }
}

When rate limit headers are absent, rateLimit fields are all null:

"rateLimit": {
  "limit": null,
  "remaining": null,
  "resetSeconds": null,
  "usedPercent": null,
  "remainingPercent": null,
  "isLow": false,
  "hasRateLimitInfo": false
}

TLS / SSL Security Inspection

Every horizon inspection also evaluates the TLS/SSL security posture of the endpoint:

HTTPS enforcement — endpoints served over plain http:// are flagged with a warning and a recommendation to enable TLS.
Certificate metadata — Common Name (CN), Subject Alternative Names (SANs), issuer, serial number, and signature algorithm.
Validity window — Valid From / Valid To dates plus a live expiration countdown (Expires In).
Expiration warnings — expired certificates and certificates expiring within 30 days are flagged.
Self-signed detection — self-signed certificates are flagged with a recommendation to use a CA-issued certificate.
Protocol & cipher suite — the negotiated TLS version and cipher suite are displayed; TLS 1.0 / TLS 1.1 are flagged as insecure.
Recommendations — actionable remediation steps are printed for every warning.

The inspection connects with Node's tls.connect (rejectUnauthorized: false, inspection-only — no sensitive data is exchanged) and degrades gracefully: connection failures, timeouts, and missing certificates are reported without failing the command.

npm run dev -- horizon https://horizon-testnet.stellar.org

Example output section:

--- TLS / SSL Security Inspection ---
┌──────────────────────────┬──────────────────────────────────────┐
│ Property                 │ Value                                │
├──────────────────────────┼──────────────────────────────────────┤
│ HTTPS Enabled            │ YES                                  │
│ Negotiated TLS Version   │ TLSv1.3                              │
│ Cipher Suite             │ TLS_AES_256_GCM_SHA384               │
│ Certificate CN           │ horizon-testnet.stellar.org          │
│ Subject Alt Names        │ DNS:horizon-testnet.stellar.org      │
│ Issuer                   │ R3                                   │
│ Serial Number            │ 03:...                               │
│ Signature Algorithm      │ sha256WithRSAEncryption              │
│ Valid From               │ Jun 15 00:00:00 2025 GMT             │
│ Valid To                 │ Jun 15 23:59:59 2026 GMT             │
│ Expires In               │ 310 day(s)                           │
│ Self-Signed              │ NO                                   │
└──────────────────────────┴──────────────────────────────────────┘

TLS findings are included in JSON output under the tls key:

npm run dev -- horizon https://horizon-testnet.stellar.org --json

{
  "ok": true,
  "data": {
    "info": { "url": "https://horizon-testnet.stellar.org", "status": "online" },
    "feeStats": { },
    "tls": {
      "inspected": true,
      "httpsEnabled": true,
      "error": null,
      "tlsVersion": "TLSv1.3",
      "cipherSuite": "TLS_AES_256_GCM_SHA384",
      "insecureProtocol": false,
      "certificate": {
        "subject": { "C": "US", "O": "Let's Encrypt", "CN": "horizon-testnet.stellar.org" },
        "commonName": "horizon-testnet.stellar.org",
        "subjectAltNames": ["DNS:horizon-testnet.stellar.org"],
        "issuer": { "C": "US", "O": "Let's Encrypt", "CN": "R3" },
        "issuerCommonName": "R3",
        "serialNumber": "03:...",
        "signatureAlgorithm": "sha256WithRSAEncryption",
        "validFrom": "Jun 15 00:00:00 2025 GMT",
        "validTo": "Jun 15 23:59:59 2026 GMT",
        "expiresAt": "2026-06-15T23:59:59.000Z",
        "daysRemaining": 310,
        "expired": false,
        "expiringSoon": false,
        "selfSigned": false
      },
      "warnings": [],
      "recommendations": []
    }
  }
}

Endpoints served over plain http:// report httpsEnabled: false with a warning recommending HTTPS. If the TLS handshake cannot be completed (timeout, connection refused, missing certificate), the command still succeeds and surfaces the failure under tls.error with a corresponding warning — Horizon endpoint inspection is never blocked by TLS issues.

Sponsorship Audit

Inspect sponsorship counters and sponsorship metadata visible from an account payload:

npm run dev -- sponsorship G...
npm run dev -- sponsorship G... --json

The report distinguishes reserves sponsored by the account from reserves sponsored for the account and summarizes sponsored trustlines and signers where Horizon exposes that metadata.

Liquidity Pool Inspection

Inspect a liquidity pool's current state:

npm run dev -- liquidity-pool <64-character-pool-id>
npm run dev -- liquidity-pool <64-character-pool-id> --activity --limit 25 --json

The report shows pool type, fee basis points, total shares, reserves, reserve shares, reserve ratio, and an approximate spot price. With --activity, recent pool trades, operations, and transactions are counted separately.

Soroban RPC Inspection

Verify a Soroban RPC node's health, network configuration, protocol version, and ledger synchronization status:

npm run dev -- soroban https://soroban-testnet.stellar.org

The command runs three JSON-RPC calls concurrently to the endpoint:

Call	What it returns
`getHealth`	Health status (`healthy` / degraded string)
`getNetwork`	Network passphrase and protocol version
`getLatestLedger`	Latest ledger sequence and close timestamp

getNetwork and getLatestLedger are treated as optional — if the node doesn't support them the inspection still succeeds and those fields are shown as Unknown.

Unreachable endpoints or HTTP errors exit with code 1 and display a clear error message.

# JSON output — all fields serialized, ideal for monitoring pipelines
npm run dev -- soroban https://soroban-testnet.stellar.org --json

# Save to file
npm run dev -- soroban https://soroban-testnet.stellar.org --json --output soroban-report.json

# Verbose mode (shows debug-level RPC call traces)
npm run dev -- soroban https://soroban-testnet.stellar.org --verbose

JSON output structure:

{
  "ok": true,
  "data": {
    "url": "https://soroban-testnet.stellar.org",
    "status": "online",
    "latencyMs": 112,
    "health": "healthy",
    "networkPassphrase": "Test SDF Network ; September 2015",
    "protocolVersion": 21,
    "latestLedgerSequence": 4500000,
    "latestLedgerCloseTime": 1700000000,
    "latestLedgerCloseTimeIso": "2023-11-14T22:13:20.000Z"
  }
}

Soroban RPC Version Information

Retrieve a node's implementation and software build metadata through the read-only getVersionInfo RPC method:

npm run dev -- soroban-version https://soroban-testnet.stellar.org

The report normalizes implementation, server version, build, commit/revision, protocol version, and supported RPC version information when provided. Missing fields are shown as unavailable; the command does not infer metadata from the endpoint URL. It also includes the endpoint URL, request latency, and retrieval timestamp. The original JSON-RPC response is retained in JSON output as rawResponse.

Compare two nodes with --compare:

npm run dev -- soroban-version https://rpc-a.example.com --compare https://rpc-b.example.com
npm run dev -- soroban-version https://rpc-a.example.com --compare https://rpc-b.example.com --json

The comparison lists differences in implementation, server/build versions, revision, protocol version, and supported RPC versions. It reports whether the available software metadata matches; protocol or build differences are descriptive only and are not compatibility guarantees.

Responses are classified as available, partially-available, unsupported (the method is not implemented), unreachable, or malformed. Unsupported and partial responses still produce a diagnostic report; unreachable and malformed responses return a non-zero exit code. The command sends only getVersionInfo requests and performs no state-changing operations.

Soroban RPC Capabilities Inspection

Inspect a Soroban RPC endpoint to discover supported methods, server information, and full capability details:

npm run dev -- rpc-capabilities https://soroban-testnet.stellar.org

The command inspects the RPC endpoint and displays:

Health Status — Overall endpoint health (healthy, degraded, etc.)
Network Information — Network passphrase and protocol version
Ledger Information — Latest ledger sequence and close timestamp
Server Information — Server name and version (when available)
Supported Methods — Complete list of RPC methods the endpoint implements
Unsupported Methods — Methods that are not available on this endpoint
Capability Summary — Quick overview of total methods probed and support statistics

# Human-readable output
npm run dev -- rpc-capabilities https://soroban-testnet.stellar.org

# JSON output — ideal for automation and compatibility checking
npm run dev -- rpc-capabilities https://soroban-testnet.stellar.org --json

# Save to file
npm run dev -- rpc-capabilities https://soroban-testnet.stellar.org --output rpc-report.json

# Verbose mode (shows debug traces)
npm run dev -- rpc-capabilities https://soroban-testnet.stellar.org --verbose

Example human-readable output:

=== Soroban RPC Capabilities Inspection ===

Property                 Value
─────────────────────────────────────────────────────────
Status                   ONLINE
Response Latency         145ms
Health Status            HEALTHY
Network Passphrase       Test SDF Network ; September 2015
Protocol Version         21
Latest Ledger Sequence   4500000

--- Server Information ---
Property                 Value
─────────────────────────────────────────────────────────
Name                     SorobanRPC
Version                  21.0.0

--- Ledger Information ---
Property                 Value
─────────────────────────────────────────────────────────
Latest Ledger Close Time 2023-11-14T22:13:20.000Z

--- Supported Methods (11) ---
Method
──────────────────────
getAccount
getContractData
getEvents
getHealth
getLatestLedger
getLedgerEntries
getNetwork
getSendTransaction
getServerInfo
getTransaction
simulateTransaction

--- Capability Summary ---
Metric                   Value
─────────────────────────────────────────────────────────
Total Methods Probed     12
Supported Methods        11
Unsupported Methods      1

JSON output structure:

{
  "ok": true,
  "data": {
    "url": "https://soroban-testnet.stellar.org",
    "status": "online",
    "latencyMs": 145,
    "health": "healthy",
    "networkPassphrase": "Test SDF Network ; September 2015",
    "protocolVersion": 21,
    "latestLedgerSequence": 4500000,
    "latestLedgerCloseTimeIso": "2023-11-14T22:13:20.000Z",
    "serverInfo": {
      "name": "SorobanRPC",
      "version": "21.0.0"
    },
    "supportedMethods": [
      "getAccount",
      "getContractData",
      "getEvents",
      "getHealth",
      "getLatestLedger",
      "getLedgerEntries",
      "getNetwork",
      "sendTransaction",
      "simulateTransaction",
      "getTransaction"
    ],
    "unsupportedMethods": [
      "getServerInfo"
    ]
  }
}

Use cases:

Pre-deployment validation — Verify an RPC endpoint supports all methods your application needs before deploying.
Endpoint compatibility checking — Quickly compare capabilities across multiple RPC providers.
Monitoring and alerting — Track when endpoints lose support for critical methods.
CI/CD integration — Automate RPC readiness checks using JSON output and jq queries.

Example jq query to extract supported methods:

npm run dev -- rpc-capabilities https://soroban-testnet.stellar.org --json | jq '.data.supportedMethods[]'

Example to check if specific methods are supported:

npm run dev -- rpc-capabilities https://soroban-testnet.stellar.org --json | jq '.data | {health, supportedMethodCount: (.supportedMethods | length)}'

Account Audit

Audit a Stellar account's balances, subentries, thresholds, and signing weights:

npm run dev -- account G...

(Optionally provide a custom Horizon URL with -h / --horizon)

Account audits include a trustline health section for non-native assets:

issuer flags: auth_required, auth_revocable, auth_immutable, and clawback status
authorization state and liabilities-only/revoked trustlines
balance utilization as a percentage of trustline limit
warnings when utilization is at or above 99%

npm run dev -- account G... --horizon https://horizon-testnet.stellar.org --json

Account Offers and Claimable Balances

Inspect open offers for an account and claimable balance predicate details:

npm run dev -- account-offers G... --limit 25
npm run dev -- claimable-balance <64-char-balance-id> --json

account-offers groups active offers by selling/buying pair and keeps the raw Horizon offer records in JSON output. claimable-balance reports the asset, amount, sponsor, last modified ledger, and claimant predicate descriptions.

Account Merge Safety Audit

Run a read-only preflight on the source and destination accounts before preparing a merge:

npm run dev -- account-merge-audit G_SOURCE G_DESTINATION
npm run dev -- account-merge-audit G_SOURCE G_DESTINATION --history-depth 50 --json

The report retrieves both accounts and checks source XLM balance and liabilities, trustlines, offers, signers, data entries, subentry counts, and sponsorship counters. It classifies the result as ready, requires-cleanup, destination-unavailable, or insufficient-information; every non-ready result includes findings and suggested actions. JSON includes normalized counts and findings plus the raw Horizon account payload and raw offer records used by the checks.

This is a snapshot-based preflight, not a guarantee that a merge will execute: account state can change after inspection, Horizon history may be incomplete, and sponsorship counters do not enumerate every current ledger relationship. --history-depth optionally includes up to 200 recent source operations as supporting evidence, but historical operations do not establish current state. The command only performs GET requests; it never builds, signs, or submits a transaction.

Soroban Contract Inspection

Inspect contract ledger entries exposed by Soroban RPC:

npm run dev -- contract C... --rpc https://soroban-testnet.stellar.org

The command concurrently queries the Soroban RPC endpoint for two things: the target contract's ledger entries (instance + WASM code) and the RPC node's network configuration (passphrase + protocol version). It extracts the WASM code hash, queries the referenced contract code entry, calculates remaining ledger lifetime when expiration metadata is available, and reports the storage footprint it inspected.

Configure TTL warning sensitivity:

npm run dev -- contract C... \
  --rpc https://soroban-testnet.stellar.org \
  --ttl-warning-ledgers 5000

Example output:

=== Soroban Contract Inspection ===

Contract ID:        C...
RPC URL:           https://soroban-testnet.stellar.org
Network Passphrase: Test SDF Network ; September 2015
Protocol Version:   21
WASM Code Hash:     0202020202020202020202020202020202020202020202020202020202020202
Contract Owner:     C...
Current Ledger:     100
Instance Found:     YES
Code Entry Found:   YES
WASM Size:          4 Bytes

--- TTL & Expiration ---
Current TTL / Live Until Ledger: 105
Last Modified Ledger:            10
Remaining Ledger Lifetime:       5
Warning Threshold:               10 ledgers

--- Storage Footprint ---
Queried Ledger Entries:     2
Found Ledger Entries:       2
Instance Storage Entries:   1

⚠ Contract TTL is below warning threshold (5 ledgers remaining; threshold 10).

JSON output is available:

npm run dev -- contract C... --rpc https://soroban-testnet.stellar.org --json

JSON output structure:

{
  "ok": true,
  "data": {
    "contractId": "C...",
    "rpcUrl": "https://soroban-testnet.stellar.org",
    "currentLedger": 100,
    "wasmHash": "0202...",
    "owner": "C...",
    "instance": {
      "found": true,
      "lastModifiedLedger": 10,
      "liveUntilLedger": 105,
      "currentTtl": 105,
      "remainingLedgers": 5
    },
    "code": {
      "found": true,
      "wasmSizeBytes": 4
    },
    "storage": {
      "footprint": ["...", "..."],
      "queriedEntryCount": 2,
      "foundEntryCount": 2,
      "instanceStorageEntryCount": 1
    },
    "warnings": ["Contract TTL is below warning threshold (5 ledgers remaining; threshold 10)."]
  }
}

If the RPC node cannot be reached, malformed contract IDs are rejected up-front with a clear error, and unknown contracts return a graceful instance.found = false result with an explanatory warning rather than an exception.

Soroban Contract Environment Metadata

Inspect the contractenvmetav0 custom section in a local WASM artifact without network access:

npm run dev -- contract-env-meta --wasm ./contract.wasm

Deployed WASM can be selected by its 32-byte hex hash or by contract ID. A contract ID is resolved through its contract-instance ledger entry, then the referenced contract-code entry is read:

npm run dev -- contract-env-meta --wasm-hash 0123...abcd --rpc https://soroban-testnet.stellar.org
npm run dev -- contract-env-meta --contract-id C... --rpc https://soroban-testnet.stellar.org

Compare two artifacts by selecting one primary source and one --compare-* source. Supported pairs include local/local, local/deployed, and deployed/deployed:

npm run dev -- contract-env-meta --wasm ./old.wasm --compare-wasm ./new.wasm
npm run dev -- contract-env-meta --wasm ./local.wasm --compare-contract-id C... --rpc https://soroban-testnet.stellar.org
npm run dev -- contract-env-meta --contract-id C... --compare-contract-id C... --rpc https://soroban-testnet.stellar.org

The normalized report includes the environment interface version, observed protocol value, metadata entries, artifact hash, and a deterministic SHA-256 metadata fingerprint. JSON output also preserves the complete custom-section XDR as base64 and hex. Metadata states distinguish decoded, partially unsupported, absent, malformed, and unavailable artifacts. Unsupported XDR remains available in the raw representation.

Comparisons list added, removed, and changed normalized entries and indicate whether fingerprints match. Version differences are observations only: the command reports compatibility as not assessed unless an explicit compatibility rule is added. Deployed inspection uses read-only getLedgerEntries RPC calls; local inspection makes no network requests. Missing ledger entries and RPC failures are reported as unavailable artifacts.

npm run dev -- contract-env-meta --wasm ./contract.wasm --json

JSON results are returned in the standard { "ok": true, "data": ... } envelope. Each artifact includes normalized, rawMetadata, fingerprint, status, and any diagnostic; comparisons are included under comparison.

Operations History

Fetch and normalize recent Horizon operations:

npm run dev -- operations --limit 10 --type payment

Filter by account:

npm run dev -- operations \
  --horizon https://horizon-testnet.stellar.org \
  --account G... \
  --type change_trust \
  --limit 25

Supported normalized operation families include payments, create account, account merge, change trust, manage buy/sell offer, and path payment operations. Use --json for machine-readable output:

npm run dev -- operations --account G... --limit 10 --json

Route, Effects, and Account Data Inspection

Inspect path payment routes, account data entries, transaction effects, and operation effects from Horizon:

npm run dev -- path-routes --mode strict-send --source-asset XLM --source-amount 10 --destination-account G...
npm run dev -- account-data G... --prefix app:
npm run dev -- tx-effects <64-char-transaction-hash> --limit 25
npm run dev -- operation-effects <operation-id> --json

path-routes supports both strict-send and strict-receive route discovery. Issued assets use CODE:G... notation, while native assets can be passed as XLM or native. The effects commands include normalized counts by effect type, account, and asset while preserving raw Horizon records in JSON output.

Order Book Inspection

Query DEX order book depth, spread, and volume for a trading pair:

npm run dev -- orderbook XLM USDC:GBBD47IF6LWK7P7MDEVSCWR7D6WV3FYVHQRFFTL6PQGP54YPM7K32T6H

Native XLM can be specified as XLM, native, or XLM:native. JSON output is available with --json.

Market Trade History

Retrieve and summarize recent trades for a Stellar asset pair from Horizon:

npm run dev -- trades XLM USDC:GBBD47IF6LWK7P7MDEVSCWR7D6WV3FYVHQRFFTL6PQGP54YPM7K32T6H

Native XLM can be specified as XLM, native, or XLM:native. Non-native assets use CODE:ISSUER format.

Control how many trades are returned with --limit (default: 20, max: 200):

npm run dev -- trades XLM USDC:GBBD47IF6LWK7P7MDEVSCWR7D6WV3FYVHQRFFTL6PQGP54YPM7K32T6H \
  --limit 50

Point at a different Horizon endpoint with --horizon:

npm run dev -- trades XLM USDC:GBBD47IF6LWK7P7MDEVSCWR7D6WV3FYVHQRFFTL6PQGP54YPM7K32T6H \
  --horizon https://horizon.stellar.org \
  --limit 100

The output shows a trade table followed by summary statistics:

=== Market Trade History ===

Pair:    XLM / USDC:GBBD47IF...
Horizon: https://horizon-testnet.stellar.org
Latency: 62ms

┌──────────────────────┬──────────────────────┬───────────┬──────────────┬─────────────┬─────────────────┬───────────────────┐
│ Trade ID             │ Timestamp            │ Base      │ Counter      │ Price       │ Base Amount     │ Counter Amount    │
├──────────────────────┼──────────────────────┼───────────┼──────────────┼─────────────┼─────────────────┼───────────────────┤
│ 2163...              │ 2026-07-28T10:01:00Z │ XLM       │ USDC:GBBD... │ 0.1100000   │ 500.0000000     │ 55.0000000        │
│ 2162...              │ 2026-07-28T09:58:00Z │ XLM       │ USDC:GBBD... │ 0.1095000   │ 1200.0000000    │ 131.4000000       │
└──────────────────────┴──────────────────────┴───────────┴──────────────┴─────────────┴─────────────────┴───────────────────┘

--- Summary Statistics ---
┌──────────────────────┬─────────────────┐
│ Metric               │ Value           │
├──────────────────────┼─────────────────┤
│ Number of Trades     │ 2               │
│ Total Base Volume    │ 1700.0000000    │
│ Total Counter Volume │ 186.4000000     │
│ Average Price        │ 0.1097500       │
│ Highest Price        │ 0.1100000       │
│ Lowest Price         │ 0.1095000       │
└──────────────────────┴─────────────────┘

When no trades exist for the pair, the command exits cleanly with a No recent trades found message — no error or non-zero exit.

JSON output — ideal for analytics pipelines and dashboards:

npm run dev -- trades XLM USDC:GBBD47IF6LWK7P7MDEVSCWR7D6WV3FYVHQRFFTL6PQGP54YPM7K32T6H --json

{
  "ok": true,
  "data": {
    "horizonUrl": "https://horizon-testnet.stellar.org",
    "baseLabel": "XLM",
    "counterLabel": "USDC:GBBD47IF...",
    "limit": 20,
    "latencyMs": 62,
    "trades": [
      {
        "id": "216334...",
        "ledgerCloseTime": "2026-07-28T10:01:00Z",
        "baseAsset": "XLM",
        "counterAsset": "USDC:GBBD47IF...",
        "baseAmount": "500.0000000",
        "counterAmount": "55.0000000",
        "price": 0.11
      }
    ],
    "stats": {
      "tradeCount": 1,
      "totalBaseVolume": 500,
      "totalCounterVolume": 55,
      "averagePrice": 0.11,
      "highestPrice": 0.11,
      "lowestPrice": 0.11
    }
  }
}

When the market has no recent trades the trades array is empty and all stats numeric fields are null:

"stats": {
  "tradeCount": 0,
  "totalBaseVolume": 0,
  "totalCounterVolume": 0,
  "averagePrice": null,
  "highestPrice": null,
  "lowestPrice": null
}

Save output to a file:

npm run dev -- trades XLM USDC:GBBD47IF6LWK7P7MDEVSCWR7D6WV3FYVHQRFFTL6PQGP54YPM7K32T6H \
  --json --output trades-report.json

Decode Transaction XDR

Decode a base64 TransactionEnvelope offline without network access:

npm run dev -- decode <xdrBase64>
npm run dev -- decode <xdrBase64> --network testnet --json

Supports multi-operation transactions, memo fields, time bounds, and signature inspection.

Fee-Bump Transaction Analysis

Analyze a regular transaction or fee-bump TransactionEnvelope entirely offline. A fee-bump transaction wraps an inner transaction while a separate fee source pays the outer fee. This command displays both fee ceilings, computes the effective maximum fee rate as the outer fee divided by the inner operation count plus the fee-bump operation, and keeps outer and inner signatures distinct. Signer identities are reported only when decorated signature hints match known source/signer accounts. Transaction hashes are shown when an explicit network passphrase is supplied.

npm run dev -- fee-bump <xdrBase64>
npm run dev -- fee-bump <xdrBase64> --network testnet
npm run dev -- fee-bump <xdrBase64> --network 'Public Global Stellar Network ; September 2015' --json

The report preserves the exact supplied XDR in JSON output and includes normalized outer and inner transaction structures, transaction preconditions, concise operation summaries, fee relationships, and signature counts. It never requests private keys, signs or modifies a transaction, or submits it to a network.

Ledger Header Inspection

Retrieve and summarize information about a specific Stellar ledger using Horizon (GET /ledgers/{sequence}):

npm run dev -- ledger 57000000

The command prints a human-readable table containing the ledger's metadata and consensus activity:

Sequence & identifiers — sequence number, ledger hash, previous ledger hash
Activity — transaction count, successful transaction count, operation count, close timestamp
Protocol — Stellar protocol version in effect at close time
Network economics — base fee, base reserve, network totals (total_coins, fee_pool, max_tx_set_size) when the Horizon version exposes them

# Target a custom Horizon endpoint
npm run dev -- ledger 57000000 --horizon https://horizon.stellar.org

# Surface Horizon-provided links to related transactions/operations
npm run dev -- ledger 57000000 --show-links

# JSON output for monitoring pipelines or shell scripting
npm run dev -- ledger 57000000 --json
npm run dev -- ledger 57000000 --json --output ledger-57000000.json

JSON output structure:

{
  "ok": true,
  "data": {
    "horizonUrl": "https://horizon-testnet.stellar.org",
    "ledger": {
      "id": "...",
      "sequence": 57000000,
      "hash": "...",
      "prev_hash": "...",
      "transaction_count": 12,
      "successful_transaction_count": 12,
      "operation_count": 38,
      "closed_at": "2024-01-15T12:00:00Z",
      "total_coins": "105000000.0000000",
      "fee_pool": "100.5",
      "base_fee": 100,
      "base_reserve": "5000000",
      "max_tx_set_size": 1000,
      "protocol_version": 21,
      "_links": { "self": { "href": "..." }, "transactions": { "href": "..." } }
    }
  }
}

When the ledger is unknown to the Horizon node (commonly a future or not-yet-finalized sequence number), the CLI prints a clear error, emits an ok: false JSON envelope with code 1, and exits without silently hanging. Input validation rejects non-numeric or non-positive sequences before any network call is made.

Transaction Submission Test

Measure Horizon transaction submission latency with a lightweight self-payment:

export STELLAR_SECRET_KEY=S...
npm run dev -- tx-test

Requires a funded testnet account. Optionally set HORIZON_URL to target a different endpoint. JSON output available with --json.

Multi-Endpoint Health Dashboard

Concurrently inspect up to 10 Horizon endpoints and generate a comparison scorecard showing availability, latency, ledger sequence, and sync lag:

npm run dev -- health https://horizon.stellar.org https://horizon-testnet.stellar.org

Example with three endpoints:

npm run dev -- health \
  https://horizon.stellar.org \
  https://horizon-testnet.stellar.org \
  https://horizon-futurenet.stellar.org

The dashboard displays a summary banner followed by a per-endpoint scorecard:

Status — ONLINE / OFFLINE
Latency — round-trip time in milliseconds
Latest Ledger — the most recent ledger sequence reported by each node
Lag — how many ledgers behind the most-synced peer; endpoints lagging by more than 3 ledgers are highlighted in red with a ⚠ warning
Protocol — protocol version

Endpoints are queried concurrently, so the total wall-clock time equals roughly the slowest single endpoint response.

# JSON output — ideal for CI pipelines, monitoring, and jq queries
npm run dev -- health https://horizon.stellar.org https://horizon-testnet.stellar.org --json

# Parse with jq
npm run dev -- health https://horizon.stellar.org --json | jq '.data.summary'
npm run dev -- health https://horizon.stellar.org --json | jq '.data.endpoints[] | {endpoint, status, ledgerLag}'

# Save to file
npm run dev -- health https://horizon.stellar.org https://horizon-testnet.stellar.org --json --output health-report.json

JSON output structure:

{
  "ok": true,
  "data": {
    "checkedAt": "2024-01-15T12:00:00.000Z",
    "summary": {
      "total": 2,
      "online": 2,
      "offline": 0,
      "lagging": 0,
      "maxLedger": 50000000
    },
    "endpoints": [
      {
        "endpoint": "https://horizon.stellar.org",
        "status": "online",
        "latencyMs": 45,
        "latestLedger": 50000000,
        "ledgerLag": 0,
        "lagging": false,
        "protocolVersion": 21,
        "horizonVersion": "2.28.0"
      }
    ]
  }
}

Ledger Range Analysis

Analyze a range of consecutive Stellar ledgers to understand network performance, transaction throughput, and protocol behavior:

npm run dev -- ledgers 57000000 57000100

The command retrieves ledger information across the specified range and displays aggregate metrics:

Total Ledgers Analyzed — count of ledgers successfully retrieved
Total Transactions — sum of all transactions in the range
Total Operations — sum of all operations in the range
Avg Transactions / Ledger — mean transactions per ledger
Avg Operations / Ledger — mean operations per ledger
Avg Close Interval — average time between consecutive ledger closes

Ledgers with unusually high transaction counts (exceeding the mean + 2σ threshold) are highlighted in a separate table.

Use a custom Horizon endpoint with -h:

npm run dev -- ledgers 57000000 57000100 -h https://horizon.stellar.org

Control the maximum range size with --max-range (default: 200):

npm run dev -- ledgers 57000000 57000500 --max-range 500

Invalid ranges (start > end, non-positive integers, ranges exceeding the max) return clear error messages:

$ npm run dev -- ledgers 100 50
# End sequence must be greater than or equal to start sequence

$ npm run dev -- ledgers -1 100
# Start sequence must be a positive integer

Missing or unavailable ledgers within the range are reported:

npm run dev -- ledgers 57000000 57000010 --json

Example JSON output:

Soroban Transaction Inspection

Inspect execution details of a Soroban transaction after submission — including execution status, ledger, return value, resource consumption, fee breakdown, contract events, and diagnostic events:

npm run dev -- soroban-tx <transactionHash>

Specify a custom RPC endpoint with --rpc:

npm run dev -- soroban-tx <transactionHash> \
  --rpc https://soroban-testnet.stellar.org

The transaction hash must be a 64-character hexadecimal string. Invalid hashes are rejected before any network call is made.

Status values:

Status	Meaning
`SUCCESS`	Contract invocation completed successfully
`FAILED`	Transaction was included in a ledger but the contract execution failed
`PENDING`	Transaction has been submitted but not yet included in a ledger
`NOT_FOUND`	Transaction hash is unknown to the node (expired or never submitted)

Handling failed executions:

When a contract invocation fails, soroban-tx still displays all available information — ledger sequence, resource usage, and any diagnostic events emitted before the failure — making it straightforward to diagnose what went wrong:

npm run dev -- soroban-tx <failedTxHash> --rpc https://soroban-testnet.stellar.org

A ⚠ Contract invocation failed warning is shown at the bottom of the output, and the exit code is non-zero.

JSON output:

npm run dev -- soroban-tx <transactionHash> --json

JSON output structure:

Multi-Endpoint Compatibility Comparison

Compare configuration, compatibility, and health across multiple Stellar endpoints (both Horizon and Soroban RPC). The command automatically detects the endpoint type, gathers metadata, and highlights configuration differences.

npm run dev -- compare-endpoints https://horizon.stellar.org https://rpc.example.com

Compare endpoints from different Stellar networks:

npm run dev -- compare-endpoints \
  https://horizon.stellar.org \
  https://horizon-testnet.stellar.org \
  https://soroban-testnet.stellar.org

The comparison table shows the following for each endpoint:

Column	Description
Endpoint URL	The normalized URL of the endpoint
Type	Detected service type: `Horizon`, `Soroban RPC`, or `Unknown`
Status	`ONLINE` or `OFFLINE`
Latency	Round-trip response time in milliseconds
Network Passphrase	The Stellar network passphrase (e.g. "Public Global Stellar Network ; September 2015")
Protocol	Stellar protocol version number
Latest Ledger	The most recent ledger sequence reported by the endpoint
Health	Health status (HTTP status for Horizon, "healthy" for Soroban, or error message for offline)

Differences between endpoints are highlighted:

Network mismatches are shown in red — endpoints may be on different Stellar networks
Protocol version mismatches are highlighted in yellow
Offline endpoints are reported as warnings

Configurable timeout

Set a custom request timeout in milliseconds:

npm run dev -- compare-endpoints https://horizon.stellar.org https://horizon-testnet.stellar.org --timeout 15000

JSON output

npm run dev -- compare-endpoints https://horizon.stellar.org https://horizon-testnet.stellar.org --json

JSON output structure:

{
  "ok": true,
  "data": {
    "horizonUrl": "https://horizon-testnet.stellar.org",
    "range": {
      "start": 57000000,
      "end": 57000100,
      "requestedSize": 101,
      "maxRange": 200
    },
    "summary": {
      "totalLedgers": 101,
      "totalTransactions": 452,
      "totalOperations": 1080,
      "avgTransactionsPerLedger": 4.48,
      "avgOperationsPerLedger": 10.69,
      "avgLedgerCloseIntervalSeconds": 5.0,
      "missingLedgers": 0,
      "missingSequences": []
    },
    "highActivityLedgers": [
      {
        "sequence": 57000050,
        "transactionCount": 85,
        "operationCount": 200,
        "threshold": 32
      }
    ]
  }
}

"hash": "aabbcc...",
"rpcUrl": "https://soroban-testnet.stellar.org",
"latencyMs": 84,
"status": "SUCCESS",
"ledger": 5000000,
"ledgerCloseTime": 1700000000,
"ledgerCloseTimeIso": "2023-11-14T22:13:20.000Z",
"returnValue": "AAAAAQAAAA==",
"events": [
  {
    "type": "contract",
    "contractId": "C...",
    "topics": ["AAAAA=", "BBBBB="],
    "data": "CCCCC="
  }
],
"diagnosticEvents": [],
"resources": {
  "instructions": 1000000,
  "readBytes": 512,
  "writeBytes": 256,
  "readLedgerEntries": 3,
  "writeLedgerEntries": 1
},
"fee": {
  "totalFee": 1500,
  "inclusionFee": 100,
  "resourceFeeCharged": 1400,
  "refundableFee": 200
},
"contractFailed": false
"endpoints": [
  {
    "url": "https://horizon.stellar.org",
    "type": "horizon",
    "status": "online",
    "latencyMs": 120,
    "networkPassphrase": "Public Global Stellar Network ; September 2015",
    "protocolVersion": 21,
    "latestLedger": 50000000,
    "healthStatus": "HTTP 200"
  },
  {
    "url": "https://horizon-testnet.stellar.org",
    "type": "horizon",
    "status": "online",
    "latencyMs": 85,
    "networkPassphrase": "Test SDF Network ; September 2015",
    "protocolVersion": 21,
    "latestLedger": 45000000,
    "healthStatus": "HTTP 200"
  }
],
"differences": {
  "networkMismatch": true,
  "protocolMismatch": false,
  "hasOfflineEndpoints": false
},
"checkedAt": "2024-01-15T12:00:00.000Z"

} }


Save to file:

```bash
npm run dev -- soroban-tx <transactionHash> --json --output tx-report.json
npm run dev -- compare-endpoints https://horizon.stellar.org https://horizon-testnet.stellar.org --json --output comparison.json

Transaction Result Analysis

Inspect the protocol-level outcome of a transaction retrieved from Horizon:

npm run dev -- result <transactionHash>
npm run dev -- result <transactionHash> --horizon https://horizon.stellar.org
npm run dev -- result <transactionHash> --json
npm run dev -- result <transactionHash> --verbose

The report distinguishes successful transactions, transaction-level failures, and operation-level failures. It includes the ledger sequence, result code and explanation, whether operations were applied, fee charged, operation count, and any operation result codes. Failed transactions are atomic: when a transaction or operation fails, its operations are not applied, though the transaction fee may still be charged.

Common result codes include:

Code	Meaning
`tx_bad_seq`	The transaction sequence number is invalid or out of date.
`tx_bad_auth`	The transaction is missing required signatures.
`tx_insufficient_balance`	The source account cannot cover the transaction fee.
`tx_insufficient_fee`	The transaction fee is below the network minimum.
`tx_too_early` / `tx_too_late`	The transaction fell outside its time bounds.
`tx_failed`	An operation failed; operation-specific results follow when available.
`PAYMENT_UNDERFUNDED`	A payment source does not have enough balance.

Unknown result codes remain in the report with a generic description rather than causing analysis to fail. The extensible result registry is exported from src/services/transaction-result-analyzer.ts. JSON output retains the raw XDR as resultXdr; --verbose adds decoded result details:

npm run dev -- result <transactionHash> --json --verbose

Transaction Operation Analysis

Analyze a Stellar transaction with human-readable operation descriptions, asset movement summaries, and structured JSON output:

npm run dev -- analyze-tx <transactionHash>

The command fetches transaction details and associated operations from Horizon, decodes each operation into a human-readable description, and generates a comprehensive report suitable for debugging and auditing.

Supported operation types:

Payment — source, destination, amount, asset
Path Payment (Strict Receive) — source, destination, amount, path, source asset
Path Payment (Strict Send) — same as above with destination minimum
Create Account — funder, new account, starting balance
Change Trust — trustor, asset, limit, trustee
Manage Sell Offer — selling asset, buying asset, amount, price, offer ID
Manage Buy Offer — selling asset, buying asset, amount, price, offer ID
Create Passive Sell Offer — selling asset, buying asset, amount, price
Account Merge — source, destination
Set Options — thresholds, signer updates, flags, home domain, master key weight
Allow Trust — trustor, trustee, asset, authorization status
Inflation — source account
Manage Data — source account, data name/value
Bump Sequence — source account, new sequence
Create/Claim Claimable Balance — source, asset, amount, claimants
Sponsorship Operations — begin/end sponsoring, revoke sponsorship
Clawback — source, asset, amount
Liquidity Pool Operations — deposit/withdraw, asset amounts, price range

Report includes a transaction summary (hash, source account, ledger, status, fee, memo) followed by a human-readable operation list and an asset movement summary.

# Analyze a specific transaction
npm run dev -- analyze-tx <64-char-hex-hash>

# Use a custom Horizon endpoint
npm run dev -- analyze-tx <hash> --horizon https://horizon.stellar.org

# JSON output for automated processing
npm run dev -- analyze-tx <hash> --json

# Save output to file
npm run dev -- analyze-tx <hash> --json --output analysis.json

Example human-readable output:

=== Transaction Analysis Report ===

┌──────────────────────┬────────────────────────────────────────────────────┐
│ Property             │ Value                                              │
├──────────────────────┼────────────────────────────────────────────────────┤
│ Transaction Hash     │ ccf9e7f...                                         │
│ Source Account       │ G...                                               │
│ Ledger Sequence      │ 50000000                                           │
│ Status               │ SUCCESSFUL                                         │
│ Fee Charged          │ 100 stroops                                        │
│ Memo Type            │ text                                               │
│ Memo Value           │ Test memo                                          │
│ Operation Count      │ 3                                                  │
└──────────────────────┴────────────────────────────────────────────────────┘

--- Operations (3) ---

┌───┬───────────────────────┬──────────────────────────────────────────────────┐
│ # │ Type                  │ Description                                      │
├───┼───────────────────────┼──────────────────────────────────────────────────┤
│ 1 │ payment               │ G... sent 100.0000000 XLM to G...                │
│ 2 │ create_account        │ G... funded new account G... with 2.0000000 XLM  │
│ 3 │ set_options           │ G... updated account settings -- home domain: ...│
└───┴───────────────────────┴──────────────────────────────────────────────────┘

--- Asset Movement Summary ---

┌──────────────────┬───────────────────────────────────────────────────────────┐
│ Type             │ Details                                                   │
├──────────────────┼───────────────────────────────────────────────────────────┤
│ XLM Sent         │ G... sent 100.0000000 XLM to G...                         │
│ Account Funded   │ G... funded new account G... with 2.0000000 XLM            │
└──────────────────┴───────────────────────────────────────────────────────────┘

JSON output structure:

{
  "ok": true,
  "data": {
    "transaction": {
      "hash": "ccf9e7f...",
      "sourceAccount": "G...",
      "ledger": 50000000,
      "successful": true,
      "feeCharged": "100",
      "maxFee": "150",
      "memoType": "text",
      "memoValue": "Test memo",
      "operationCount": 3,
      "createdAt": "2026-01-15T12:00:00Z",
      "horizonUrl": "https://horizon-testnet.stellar.org"
    },
    "operations": [
      {
        "index": 0,
        "type": "payment",
        "description": "G... sent 100.0000000 XLM to G...",
        "details": {
          "source": "G...",
          "destination": "G...",
          "amount": "100.0000000",
          "asset": "XLM"
        },
        "supported": true
      }
    ],
    "assetSummary": {
      "movements": [
        {
          "type": "payment",
          "description": "G... sent 100.0000000 XLM to G..."
        }
      ]
    }
  }
}

Options

-j, --json: Return raw JSON instead of formatted CLI tables (great for shell pipelines).
-o, --output <path>: Save inspection output directly to a file (JSON or Markdown).
-v, --verbose: Turn on debug logging.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on code style, testing, and how to pick up open issues from our roadmap.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
src		src
tests		tests
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PR_DESCRIPTION.md		PR_DESCRIPTION.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

🔍 Stellar API Inspector

Features

Installation

Usage

Interactive Mode

Network Passphrase Inspection

Horizon Endpoint Check

Rate Limit Headers

TLS / SSL Security Inspection

Sponsorship Audit

Liquidity Pool Inspection

Soroban RPC Inspection

Soroban RPC Version Information

Soroban RPC Capabilities Inspection

Account Audit

Account Offers and Claimable Balances

Account Merge Safety Audit

Soroban Contract Inspection

Soroban Contract Environment Metadata

Operations History

Route, Effects, and Account Data Inspection

Order Book Inspection

Market Trade History

Decode Transaction XDR

Fee-Bump Transaction Analysis

Ledger Header Inspection

Transaction Submission Test

Multi-Endpoint Health Dashboard

Ledger Range Analysis

Soroban Transaction Inspection

Multi-Endpoint Compatibility Comparison

Configurable timeout

JSON output

Transaction Result Analysis

Transaction Operation Analysis

Options

Contributing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages