TriportRPC
DashboardDocs

getLedgers

POSThttps://triport.io/rpc/stellar

Returns a list of ledgers with their details through Stellar Soroban JSON-RPC.

Stellar mainnetstellar:rpcstellar_read_rpc — 15 / 20 / 100 / 250 RPS (free / basic / pro / business) (default, unmeasured)

Returns a cursor-paginated list of retained ledgers starting at an optional sequence, with header and close-metadata XDR when available.

Use it to scan recent ledger history. Use getLatestLedger for only the head or Horizon GET /ledgers for HAL resources.

Both measured Soroban nodes retained 120,960 ledgers. The page limit is 200.

Parameters

JSON-RPC params is a by-name object. Only the fields below are defined by the OpenRPC catalog.

startLedgernumberoptional
Ledger sequence number to start fetching responses from (inclusive). This method will return an error if startLedger is less than the oldest ledger stored in this node, or greater than the latest ledger seen by this node. If a cursor is included in the request, startLedger must be omitted.
paginationobjectoptional
Pagination in stellar-rpc is similar to pagination in Horizon. See Pagination.
xdrFormatstringoptional
Lets the user choose the format in which the response should be returned - either as unpacked JSON or as base64-encoded XDR strings. Note that you should not rely on any schema for the JSON, as it will change when the underlying XDR changes.
Parameter sub-fieldsobject
pagination.cursorstring
An opaque string which acts as a paging token. To obtain the next page of results occurring after a given response set this value to the cursor field of the response.
pagination.limitnumber
The maximum number of records returned. The limit for getLedgers can range from 1 to 200 - an upper limit that is hardcoded in Stellar-RPC for performance reasons. If this argument isn't designated, it defaults to 50.

Response

The response is copied unchanged from the accepted fixture.

resultobject
Method result object.
result.cursorstring
A token which can be included in a subsequent request to obtain the next page of results.
result.latestLedgernumber
The sequence number of the latest ledger known to Stellar RPC at the time it handled the request.
result.latestLedgerCloseTimenumber
The unix timestamp of the close time of the latest ledger known to Stellar RPC at the time it handled the request.
result.ledgersarray of object
Defined by the OpenRPC schema.
result.ledgers[].hashstring
The hash of the ledger header which was included in the chain
result.ledgers[].headerXdrstring
The LedgerHeaderHistoryEntry structure for this ledger (base64-encoded string).
result.ledgers[].ledgerCloseTimestring
The unix timestamp (as a string) at which the ledger was closed.
result.ledgers[].metadataXdrstring
The LedgerCloseMeta union for this ledger (base64-encoded string).
result.ledgers[].sequencenumber
The sequence number of the ledger (sometimes called the 'block height').
result.oldestLedgernumber
The sequence number of the oldest ledger ingested by Stellar RPC at the time it handled the request.
result.oldestLedgerCloseTimenumber
The unix timestamp of the close time of the oldest ledger ingested by Stellar RPC at the time it handled the request.

Errors

Errors use the standard JSON-RPC envelope. See Stellar errors and the shared error reference.

CodeMeaningWhen it happens
-32602Invalid paramspagination.limit exceeds 200; positional-array style params are rejected. A start ledger below the node window returns beyond_retention and oldest N.
-32601Method not foundThe method is absent from the published Stellar OpenRPC catalog.
401UnauthorizedThe API key is missing or invalid.
429Rate limitedThe stellar_read_rpc RPS budget is exceeded.

Examples

JavaScript (fetch)

const request = {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getLedgers",
  "params": {
    "startLedger": "${stellar.ledger}",
    "pagination": {
      "limit": 2
    }
  }
};
const response = await fetch("https://triport.io/rpc/stellar", {
  method: "POST",
  headers: {
    "x-token": process.env.TRIPORT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(request),
});
const payload = await response.json();
if (!response.ok || payload.error) throw new Error(JSON.stringify(payload.error));
console.log(payload.result);

Notes

  • The measured retention is 120,960 ledgers.
  • pagination.limit is at most 200; continue with the opaque cursor.
  • Related: getLatestLedger, getHealth, and getTransactions.
  • This is a read-only surface. No write or transaction-submission method is published.