state_getKeysPaged - JSON-RPC Method

Description

Retrieves storage keys for a prefix in fixed-size batches. This method is preferable to state_getKeys when scanning large datasets on Enjin Matrix, such as enumerating all Matrixchain accounts or fuel tank records, because it prevents oversized responses.

Parameters

Parameter	Type	Required	Description
prefix	string	Yes	Storage prefix (hex)
count	number	Yes	Maximum number of keys to return
startKey	string | null	No	Key to resume iteration from (exclusive)
blockHash	string | null	No	Block hash for historical queries

Returns

Array of storage keys (hex strings) limited by count.

Request Example

{
  "jsonrpc": "2.0",
  "method": "state_getKeysPaged",
  "params": [
    "0x26aa394eea5630e07c48ae0c9558cef7",
    5,
    null,
    null
  ],
  "id": 1
}

Response Example

{
  "jsonrpc": "2.0",
  "result": [
    "0x26aa394eea5630e07c48ae0c9558cef702a5c1b19ab7a04f536c519aca4983ac",
    "0x26aa394eea5630e07c48ae0c9558cef70a98fdbe9ce6c55837576c60c7af3850",
    "0x26aa394eea5630e07c48ae0c9558cef734abf5cb34d6244378cddbf18e849d96",
    "0x26aa394eea5630e07c48ae0c9558cef74e7b9012096b41c4eb3aaf947f6ea429",
    "0x26aa394eea5630e07c48ae0c9558cef75684a022a34dd8bfa2baaf44f172b710"
  ],
  "id": 1
}

Code Examples

cURL

curl https://api-enjin-matrixchain.n.dwellir.com/YOUR_API_KEY \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "state_getKeysPaged",
    "params": ["0x26aa394eea5630e07c48ae0c9558cef7", 5, null, null],
    "id": 1
  }'

JavaScript

async function getKeyPage(prefix, startKey) {
  const response = await fetch('https://api-enjin-matrixchain.n.dwellir.com/YOUR_API_KEY', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'state_getKeysPaged',
      params: [prefix, 100, startKey ?? null, null],
      id: 1
    })
  });

  return (await response.json()).result;
}

Pagination Pattern

prefix = "0x26aa394eea5630e07c48ae0c9558cef7"
start = None

while True:
    payload = {
        "jsonrpc": "2.0",
        "method": "state_getKeysPaged",
        "params": [prefix, 100, start, None],
        "id": 1,
    }
    result = requests.post(
        "https://api-enjin-matrixchain.n.dwellir.com/YOUR_API_KEY",
        headers={"Content-Type": "application/json"},
        data=json.dumps(payload),
        timeout=10,
    ).json()["result"]

    if not result:
        break

    start = result[-1]

Practical Tips

• Choose a count that balances latency and payload size (100–500 works for most use cases).
• Persist startKey between runs to resume scans without re-fetching earlier keys.
• For archive nodes, pair this method with state_getStorage at a historical blockHash to replay past state.