The Starknet API of SQD Network is currently in beta. Breaking changes may be introduced in the future releases.
SQD Network API distributes the requests over a (potentially decentralized) network of workers. The main gateway URL points at a router that provides URLs of workers that do the heavy lifting. Each worker has its own range of blocks on each dataset it serves.Suppose you want to retrieve an output of some query on a block range starting at firstBlock (can be the genesis block) and ending at the highest available block. Proceed as follows:
Retrieve the dataset height from the router with GET /height and make sure it’s above firstBlock.
Save the value of firstBlock to some variable, say currentBlock.
Query the router for an URL of a worker that has the data for currentBlock with GET /${currentBlock}/worker.
Retrieve the data from the worker by posting the query (POST /), setting the "fromBlock" query field to ${currentBlock}.
Parse the retrieved data to get a batch of query data plus the height of the last block available from the current worker. Take the header.number field of the last element of the retrieved JSON array - it is the height you want. Even if your query returns no data, you’ll still get the block data for the last block in the range, so this procedure is safe.
Set currentBlock to the height from the previous step plus one.
Repeat steps 3-6 until all the required data is retrieved.
Unlike in the explorer, addresses in this API do not have leading zeros (both in valid requests and in the returned data). For example, explorer’s 0x00ce6c...0552 becomes 0xce6c...0552. This is the format that Starknet RPC nodes use.
Implementation examples:
Manually with cURL
Suppose we want data on all txs sent by Layerswap/0x19252b1deef483477c4d30cfcc3e5ed9c82fafea44669c182a45a01b4fdb97a starting from block 600_000. The steps are:
Verify that the dataset has reached the required height:
Grab the network data you requested from the list items with non-empty data fields (transactions, events). For the example above, this data will include the txn 0x6a88....
Observe that we received the data up to and including block 617979.
To get the rest of the data, update the current height to 617980 and go to step 3.
Note how the worker URL you’re getting while repeating step 3 points to a different host than before. This is how data storage and reads are distributed across the SQD Network.
Repeat steps 3 through 6 until the dataset height of 632494 is reached.
In Python
def get_text(url: str) -> str: res = requests.get(url) res.raise_for_status() return res.textdef dump( gateway_url: str, query: Query, first_block: int, last_block: int) -> None: assert 0 <= first_block <= last_block query = dict(query) # copy query to mess with it later dataset_height = int(get_text(f'{gateway_url}/height')) next_block = first_block last_block = min(last_block, dataset_height) while next_block <= last_block: worker_url = get_text(f'{gateway_url}/{next_block}/worker') query['fromBlock'] = next_block query['toBlock'] = last_block res = requests.post(worker_url, json=query) res.raise_for_status() blocks = res.json() last_processed_block = blocks[-1]['header']['number'] next_block = last_processed_block + 1 for block in blocks: print(json.dumps(block))
GET ${firstBlock}/worker (get a suitable worker URL)
The returned worker is capable of processing POST / requests in which the "fromBlock" field is equal to ${firstBlock}.Example response:https://rb06.sqd-archive.net/worker/query/czM6Ly9zdGFya25ldC1tYWlubmV0.
fromBlock: Block number to start from (inclusive).
toBlock: (optional) Block number to end on (inclusive). If this is not given, the query will go on for a fixed amount of time or until it reaches the height of the dataset.
includeAllBlocks: (optional) If true, the Network will include blocks that contain no data selected by data requests into its response.
fields: (optional) A selector of data fields to retrieve. Common for all data items.
transactions: (optional) A list of transaction requests. An empty list requests no data.
events: (optional) A list of event requests. An empty list requests no data.
The response is a JSON array of per-block data items that covers a block range starting from fromBlock. The last block of the range is determined by the worker. You can find it by looking at the header.number field of the last element in the response array.The first and the last block in the range are returned even if all data requests return no data for the range.In most cases the returned range will not contain all the range requested by the user (i.e. the last block of the range will not be toBlock). To continue, retrieve a new worker URL for blocks starting at the end of the current range plus one block and repeat the query with an updated value of fromBlock.
A transaction will be included in the response if it matches all the requests. An empty array matches no transactions; omit all requests to match all transactions.All events emitted by the selected transactions will be included into the response if events is set to true.See Data fields selector for info on field selection.
An event will be included in the response if it matches all the requests. An empty array matches no events; omit all requests to match all events.If transaction is set to true, all parent transactions will be included into the response.See Data fields selector for info on field selection.
{ transactionHash contractAddress entryPointSelector calldata maxFee type senderAddress version signature nonce classHash compiledClassHash contractAddressSalt constructorCalldata}
A valid field selector for transactions is a JSON that has a subset of these fields as keys and true as values, e.g. {"transactionHash": true, "type": true, "calldata": true}.
