QuickSync is a new scanning mechanism for light-clients wallets based on Waterfalls that moves the computational heavy lifting for address derivation and data fetching from the client to the server. This greatly improves retrieving wallet transaction history and wallet balance.
In the standard Electrum protocol, the client calculates addresses locally and makes individual requests for each address, resulting in many network roundtrips. In contrast, in the Waterfalls protocol, the client sends the wallet descriptor to the server, which derives all necessary addresses server-side and returns the complete wallet history in a single response.
QuickSyncalso has an UTXO-only mode to allow wallets to know their balance and to construct transactions more quickly, at the expense of not knowing the entire transaction history.
View the Waterfalls Github repository for more information.
Access QuickSync
To access the QuickSync endpoints, you need a Blockstream Explorer API account.
The QuickSync endpoints provide transaction history and UTXO data for descriptors or addresses (Available in both JSON and CBOR formats).
Waterfalls Endpoints:
- Bitcoin: https://enterprise.blockstream.info/api/waterfalls/waterfalls?<query_params>
- Bitcoin Testnet: https://enterprise.blockstream.info/testnet/api/waterfalls/waterfalls?<query_params>
- Liquid: https://enterprise.blockstream.info/liquid/api/waterfalls/waterfalls?<query_params>
- Liquid Testnet: https://enterprise.blockstream.info/liquidtestnet/api/waterfalls/waterfalls?<query_params>
Query Parameters:
-
descriptor (string): Bitcoin/Elements descriptor (plain text or encrypted with server key)
- Cannot be used together with addresses
- Supports encryption using age encryption with server's public key
- Network validation: mainnet descriptors (xpub) cannot be used on testnet/regtest
-
addresses (string): Comma-separated list of Bitcoin/Elements addresses
- Cannot be used together with descriptor
- Maximum addresses limited by server configuration
- Addresses cannot be blinded (confidential)
- page (integer, optional): Page number for pagination (default: 0)
- to_index (integer, optional): Maximum derivation index for descriptors (default: 0)
- utxo_only (boolean, optional): Return only unspent outputs (default: false)
Example JSON response:
{
{
"txs_seen": {
"descriptor_or_addresses": [
{
"txid": "transaction_id",
"height": 12345,
"block_hash": "block_hash",
"block_timestamp": 1234567890,
"v": 1
}
]
},
"page": 0,
"tip": "current_tip_hash"
}
Accessing the Waterfalls endpoint also requires getting an access token using your API keys before you can make the actual Waterfalls call. Include the access_token value in your Waterfalls request.
For example, a cURL Waterfalls Request might look like:
{
curl \
--request GET \
--location
"https://enterprise.blockstream.info/liquid/api/waterfalls/waterfalls?descriptor=elwpkh(xpub6DLHCiTPg67KE9ksCjNVpVHTRDHzhCSmoBTKzp2K4FxLQwQvvdNzuqxhK2f9gFVCN6Dori7j2JMLeDoB4VqswG7Et9tjqauAvbDmzF8NEPH%2F%3C0%3B1%3E%2F%2A)" \
--header "Authorization: Bearer ${ACCESS_TOKEN}"
Note: The descriptor must be URL encoded.
Its JSON response would look like this:
{
{
"txs_seen": {
"elwpkh(xpub6DLHCiTPg67KE9ksCjNVpVHTRDHzhCSmoBTKzp2K4FxLQwQvvdNzuqxhK2f9gFVCN6Dori7j2JMLeDoB4VqswG7Et9tjqauAvbDmzF8NEPH/0/*)#pxpc294c": [
[
{
"txid": "6ac214c3833ee06f7a30636dac66f0e5c025ece2693cc3f85a8c22fb2dcb2fa1",
"height": 2859778,
"block_hash": "2f7499435ae332f8a94e330ad1a28914e560eab5acee430bd50e446a66d89e1a",
"block_timestamp": 1715939108
},
{
"txid": "ff5a21c44cf16e69f2455037adadb5faab15189390482df53e8fcdd2e07347f3",
"height": 2879588,
"block_hash": "f39ea35b119d314e2b77b9b6aa31a8592d98cc786c66850e11f67ecc34073158",
"block_timestamp": 1717134068
},
{
"txid": "bcea40dfc86462c5368f2451ffbef6021ee02665d6626834cadee0f9676a7bd4",
"height": 2904668,
"block_hash": "759333440d911fbfab40c4f6d572635873bf4cbc9ffd8efaf014b762e733d30b",
"block_timestamp": 1718639935
}
],
[
{
"txid": "f80937d3834f0395a687a4eee699a43d3a711c7c0ffc2cd2c4c10996c2f1777e",
"height": 2869730,
"block_hash": "c181c818096236ac97f582a3c714887b82f9228360a8c502403cb1fdf9255a5b",
"block_timestamp": 1716542408
},
{
"txid": "ddb2d0b67cb83037c9b8eccf4c87cd310c0c3ea55cbee896c510b75d432eac49",
"height": 2879590,
"block_hash": "8944a6614055f93062dd5f0703467df8d4aafd58d60e4b96792424c123f92f14",
"block_timestamp": 1717134187
},
{
"txid": "723814d8675d9cce5a4a09c80db1e92303b8f951d873dc8c3e36b8426a2e75f8",
"height": 2904676,
"block_hash": "0d4893eafbec1eca40b660b57fd0149391a7776a142116f331f8790f1ac0012c",
"block_timestamp": 1718640428
}
],
...........
To see all the available Waterfalls endpoints please take a look at the API documentation.