Présentation générale

Tests your filter function with data from a specific block before deploying it to a stream. This allows you to validate your filter logic and see the transformed output without affecting any live streams.

Key use cases:

• Validate filter function syntax and logic
• Preview transformed data output
• Debug filter functions before deployment
• Test filters against historical block data

Endpoint

Send a POST request to test a filter function.

POST https://api.quicknode.com/streams/rest/v1/streams/test_filter

Paramètres de requête

Paramètre	Type	Obligatoire	Description
network	chaîne de caractères	Oui	Blockchain network (see Supported Chains)
dataset	chaîne de caractères	Oui	Dataset type (see Data Sources)
filter_function	chaîne de caractères	Oui	Base64-encoded JavaScript filter function
block	chaîne de caractères	Oui	Block number to test against

Example Request

cURL

curl -X POST "https://api.quicknode.com/streams/rest/v1/streams/test_filter" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "network": "ethereum-mainnet",
    "dataset": "block",
    "filter_function": "ZnVuY3Rpb24gbWFpbihkYXRhKSB7CiAgcmV0dXJuIHsKICAgIGhhc2g6IGRhdGEuc3RyZWFtRGF0YS5oYXNoLAogICAgbnVtYmVyOiBwYXJzZUludChkYXRhLnN0cmVhbURhdGEubnVtYmVyLCAxNikKICB9Owp9",
    "block": "18000000"
  }'

CLI

qn stream test-filter --network ethereum-mainnet \
  --dataset block \
  --block 18000000 \
  --filter-file ./filter.js \
  --filter-language javascript \
  -o json

JavaScript

const headers = new Headers()
headers.append('accept', 'application/json')
headers.append('Content-Type', 'application/json')
headers.append('x-api-key', 'YOUR_API_KEY')

// Encode your filter function to base64
const filterFunction = Buffer.from(`
function main(data) {
  return {
    hash: data.streamData.hash,
    number: parseInt(data.streamData.number, 16)
  };
}
`).toString('base64')

const body = JSON.stringify({
  network: 'ethereum-mainnet',
  dataset: 'block',
  filter_function: filterFunction,
  block: '18000000'
})

fetch('https://api.quicknode.com/streams/rest/v1/streams/test_filter', {
  method: 'POST',
  headers: headers,
  body: body
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error))

Python

import requests
import base64

url = "https://api.quicknode.com/streams/rest/v1/streams/test_filter"

# Encode your filter function to base64
filter_code = """
function main(data) {
  return {
    hash: data.streamData.hash,
    number: parseInt(data.streamData.number, 16)
  };
}
"""
filter_function = base64.b64encode(filter_code.encode()).decode()

payload = {
    "network": "ethereum-mainnet",
    "dataset": "block",
    "filter_function": filter_function,
    "block": "18000000"
}

headers = {
    "accept": "application/json",
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Ruby

require "uri"
require "net/http"
require "json"
require "base64"

url = URI("https://api.quicknode.com/streams/rest/v1/streams/test_filter")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["Content-Type"] = "application/json"
request["x-api-key"] = "YOUR_API_KEY"

# Encode your filter function to base64
filter_code = <<~JS
  function main(data) {
    return {
      hash: data.streamData.hash,
      number: parseInt(data.streamData.number, 16)
    };
  }
JS
filter_function = Base64.strict_encode64(filter_code)

request.body = {
  "network" => "ethereum-mainnet",
  "dataset" => "block",
  "filter_function" => filter_function,
  "block" => "18000000"
}.to_json

response = https.request(request)
puts response.body

SDK (JS)

import { QuicknodeSdk, StreamDataset } from "@quicknode/sdk"

const qn = new QuicknodeSdk({ apiKey: "YOUR_API_KEY" })

const filterFunction = Buffer.from(`
function main(data) {
	return data
}
`).toString("base64")

const result = await qn.streams.testFilter({
	network: "ethereum-mainnet",
	dataset: StreamDataset.Block,
	block: "17811625",
	filterFunction,
})

console.log("logs:", result.logs)
console.log("result:", result.result)

SDK (Python)

import asyncio
import base64
from quicknode_sdk import QuicknodeSdk, SdkFullConfig

async def main():
    qn = QuicknodeSdk(SdkFullConfig(api_key="YOUR_API_KEY"))

    filter_function = base64.b64encode(
        b"function main(data) { return data; }"
    ).decode()

    result = await qn.streams.test_filter(
        network="ethereum-mainnet",
        dataset="block",
        block="17811625",
        filter_function=filter_function,
    )

    print("logs:", result.logs)
    print("result:", result.result)

asyncio.run(main())

SDK (Ruby)

require "base64"
require "quicknode_sdk"

qn = QuicknodeSdk::SDK.from_config(api_key: "YOUR_API_KEY")

filter_function = Base64.strict_encode64("function main(data) { return data; }")

result = qn.streams.test_filter(
  network: "ethereum-mainnet",
  dataset: "block",
  block: "17811625",
  filter_function: filter_function,
)

puts "logs: #{result["logs"]}"
puts "result: #{result["result"]}"

SDK (Rust)

use quicknode_sdk::{
    streams::{StreamDataset, TestFilterParams},
    QuicknodeSdk,
    SdkFullConfig,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let qn = QuicknodeSdk::new(&SdkFullConfig::builder().api_key("YOUR_API_KEY").build())?;

    // Base64-encoded: function main(data) { return data; }
    let filter_function = "ZnVuY3Rpb24gbWFpbihkYXRhKSB7IHJldHVybiBkYXRhOyB9".to_string();

    let params = TestFilterParams {
        network: "ethereum-mainnet".to_string(),
        dataset: StreamDataset::Block,
        block: "17811625".to_string(),
        filter_function: Some(filter_function),
        filter_language: None,
        address_book_config: None,
    };
    let result = qn.streams.test_filter(&params).await?;

    println!("logs: {:?}", result.logs);
    println!("result: {}", result.result);
    Ok(())
}

Réponse

On success, the API returns the result of applying your filter function to the specified block's data.

{
  "logs": [],
  "result": "{...}"
}

Champs de réponse

Champ	Type	Description
journaux	tableau	Any console logs output by your filter function
résultat	chaîne de caractères	The result of the filter test

astuce

If your filter function has errors, the response will contain error details to help you debug the issue.