> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.sqd.dev/feedback

```json
{
  "path": "/en/portal/evm/quickstart",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# EVM Portal Quickstart

> Make your first SQD Portal request for EVM data in 5 minutes — install the client, query a block range, and stream transaction logs from Ethereum.

export const QueryInterfaceQuickstart = () => {
  const useCasesConfig = [{
    id: "ethereum-blocks",
    name: "Query Ethereum blocks",
    network: "ethereum-mainnet",
    payload: {
      type: "evm",
      fromBlock: 18000000,
      toBlock: 18001000,
      fields: {
        block: {
          number: true,
          timestamp: true,
          gasUsed: true
        }
      }
    }
  }];
  const [queryFormat, setQueryFormat] = useState("curl");
  const [useCase, setUseCase] = useState("ethereum-blocks");
  const [response, setResponse] = useState("");
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  const [viewMode, setViewMode] = useState("code");
  const [copied, setCopied] = useState(false);
  const generateCurlCommand = config => {
    const url = `https://portal.sqd.dev/datasets/${config.network}/stream`;
    const payload = JSON.stringify(config.payload, null, 2);
    return `curl --compressed -X POST '${url}' \\\n  -H 'Content-Type: application/json' \\\n  -d '${payload}'`;
  };
  useEffect(() => {
    setViewMode("code");
    setResponse("");
    setError(null);
  }, [useCase]);
  const handleRun = async () => {
    const selectedUseCase = useCasesConfig.find(uc => uc.id === useCase);
    if (!selectedUseCase) return;
    setViewMode("output");
    setLoading(true);
    setError(null);
    setResponse('');
    try {
      const url = `https://portal.sqd.dev/datasets/${selectedUseCase.network}/stream`;
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(selectedUseCase.payload)
      });
      if (!response.ok) {
        throw new Error(`API request failed: ${response.status} ${response.statusText}`);
      }
      const text = await response.text();
      if (text.trim()) {
        const lines = text.trim().split('\n');
        const parsedData = lines.map((line, index) => {
          try {
            return JSON.parse(line);
          } catch (e) {
            return {
              error: `Failed to parse line ${index + 1}`,
              raw: line
            };
          }
        });
        const formattedOutput = parsedData.map(obj => JSON.stringify(obj, null, 2)).join('\n\n');
        setResponse(formattedOutput);
      } else {
        setResponse('No data returned from API');
      }
    } catch (err) {
      setError(err.message || 'An error occurred while fetching data');
      setResponse('');
    } finally {
      setLoading(false);
    }
  };
  return <div className="not-prose w-full my-6 sm:my-8">

      <div className="bg-white dark:bg-gray-950 rounded-xl p-4 sm:p-6 border border-gray-200 dark:border-gray-800 shadow-sm">
        <div className="flex flex-col sm:flex-row items-start sm:items-center gap-3 sm:gap-4 mb-4">
          <label className="text-sm font-semibold text-gray-700 dark:text-gray-300 whitespace-nowrap">
            Response
          </label>

          <div className="flex flex-wrap items-center gap-3 flex-1 w-full">
            <div className="relative flex-shrink-0">
              <select value={queryFormat} onChange={e => setQueryFormat(e.target.value)} className="appearance-none bg-gray-50 dark:bg-gray-900 border border-gray-300 dark:border-gray-700 rounded-xl px-4 py-2.5 pr-10 text-sm font-medium text-gray-900 dark:text-white focus:outline-none focus:ring-2 focus:ring-[#2563eb] dark:focus:ring-[#2563eb] cursor-pointer transition-all">
                <option value="curl">curl</option>
              </select>
              <div className="absolute inset-y-0 right-0 flex items-center pr-3 pointer-events-none">
                <svg className="w-4 h-4 text-gray-500 dark:text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
                </svg>
              </div>
            </div>

            <div className="relative flex-shrink-0 flex-1 min-w-[200px]">
              <select value={useCase} onChange={e => setUseCase(e.target.value)} className="appearance-none w-full bg-gray-50 dark:bg-gray-900 border border-gray-300 dark:border-gray-700 rounded-xl px-4 py-2.5 pr-10 text-sm font-medium text-gray-900 dark:text-white focus:outline-none focus:ring-2 focus:ring-[#2563eb] dark:focus:ring-[#2563eb] cursor-pointer transition-all">
                {useCasesConfig.map(uc => <option key={uc.id} value={uc.id}>
                    {uc.name}
                  </option>)}
              </select>
              <div className="absolute inset-y-0 right-0 flex items-center pr-3 pointer-events-none">
                <svg className="w-4 h-4 text-gray-500 dark:text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
                </svg>
              </div>
            </div>

            <button onClick={handleRun} type="button" disabled={loading} className="flex items-center gap-2 bg-[#2563eb] hover:bg-[#1e40af] dark:bg-[#2563eb] dark:hover:bg-[#1e40af] disabled:bg-gray-400 disabled:cursor-not-allowed text-white font-semibold px-6 py-2.5 rounded-xl transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-[#2563eb] focus:ring-offset-2 dark:focus:ring-offset-gray-950 whitespace-nowrap shadow-sm hover:shadow-md">
              {loading ? <>
                  <svg className="animate-spin h-4 w-4" fill="none" viewBox="0 0 24 24">
                    <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
                    <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
                  </svg>
                  Loading...
                </> : <>
                  <svg className="w-4 h-4" fill="currentColor" viewBox="0 0 20 20">
                    <path d="M6.3 2.841A1.5 1.5 0 004 4.11V15.89a1.5 1.5 0 002.3 1.269l9.344-5.89a1.5 1.5 0 000-2.538L6.3 2.84z" />
                  </svg>
                  RUN
                </>}
            </button>
          </div>
        </div>

        {error && <div className="mt-4 p-4 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-xl">
            <p className="text-sm text-red-800 dark:text-red-200 font-medium">Error: {error}</p>
          </div>}

        <div className="mt-4 bg-gray-50 dark:bg-gray-950 border border-gray-200 dark:border-gray-800 rounded-xl overflow-hidden h-[450px] flex flex-col">
          <div className="bg-gray-100 dark:bg-gray-900 border-b border-gray-200 dark:border-gray-800 px-4 py-2.5 flex items-center justify-between">
            <span className="text-xs font-semibold text-gray-600 dark:text-gray-400 uppercase tracking-wide">
              {viewMode === "code" ? "Request" : "Response"}
            </span>
            <button onClick={() => {
    const textToCopy = viewMode === "code" ? generateCurlCommand(useCasesConfig.find(uc => uc.id === useCase)) : response;
    navigator.clipboard.writeText(textToCopy);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  }} className={`flex items-center gap-1.5 transition-colors ${copied ? "text-[#2563eb] dark:text-[#60a5fa]" : "text-gray-500 hover:text-[#2563eb] dark:text-gray-400 dark:hover:text-[#60a5fa]"}`} title={copied ? "Copied!" : "Copy to clipboard"}>
              {copied ? <>
                  <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
                  </svg>
                  <span className="text-xs font-medium">Copied!</span>
                </> : <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
                </svg>}
            </button>
          </div>
          <div className="flex-1 overflow-auto p-3 bg-gray-50 dark:bg-gray-950">
            {loading ? <div className="flex items-center justify-center h-full">
                <div className="text-sm text-gray-500 dark:text-gray-400">Fetching data from Portal API...</div>
              </div> : viewMode === "code" ? <div key={`code-${useCase}`} style={{
    position: 'relative'
  }}>
                <pre style={{
    margin: 0,
    padding: '1rem',
    background: 'var(--hl-bg)',
    borderRadius: '0.75rem',
    overflow: 'auto',
    fontSize: '0.875rem',
    lineHeight: '1.5',
    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
    color: 'var(--hl-cmd)'
  }}>
                  <code key={`curl-code-${useCase}`} style={{
    counterReset: 'line'
  }}>
                    {generateCurlCommand(useCasesConfig.find(uc => uc.id === useCase)).trim().split('\n').map((line, i) => <div key={`curl-line-${i}`} style={{
    display: 'flex',
    position: 'relative',
    paddingLeft: '3.5em',
    minHeight: '1.5em',
    lineHeight: '1.5'
  }}>
                        <span style={{
    position: 'absolute',
    left: 0,
    width: '2.5em',
    textAlign: 'right',
    color: 'var(--hl-line-num)',
    userSelect: 'none',
    paddingRight: '1em',
    lineHeight: '1.5'
  }}>{i + 1}</span>
                        <span style={{
    whiteSpace: 'pre-wrap',
    wordBreak: 'break-word',
    color: 'var(--hl-cmd)',
    lineHeight: '1.5'
  }}>
                          {line.includes('curl') && <span style={{
    color: 'var(--hl-key)'
  }}>{line}</span>}
                          {!line.includes('curl') && line.match(/^\s*-[XHd]/) && <>
                              <span style={{
    color: 'var(--hl-flag)'
  }}>{line.match(/^\s*-[XHd]/)[0]}</span>
                              <span style={{
    color: 'var(--hl-cmd)'
  }}>{line.substring(line.match(/^\s*-[XHd]/)[0].length)}</span>
                            </>}
                          {!line.includes('curl') && !line.match(/^\s*-[XHd]/) && line.match(/'[^']*'/) && <>
                              {line.split(/'([^']*)'/).map((part, j) => j % 2 === 1 ? <span key={`curl-part-${i}-${j}`} style={{
    color: 'var(--hl-str)'
  }}>'{part}'</span> : <span key={`curl-part-${i}-${j}`} style={{
    color: 'var(--hl-cmd)'
  }}>{part}</span>)}
                            </>}
                          {!line.includes('curl') && !line.match(/^\s*-[XHd]/) && !line.match(/'[^']*'/) && <span style={{
    color: 'var(--hl-cmd)'
  }}>{line}</span>}
                        </span>
                      </div>)}
                  </code>
                </pre>
              </div> : response ? <div key={`response-${useCase}-${response.length}`} style={{
    position: 'relative'
  }}>
                <pre style={{
    margin: 0,
    padding: '1rem',
    background: 'var(--hl-bg)',
    borderRadius: '0.75rem',
    overflow: 'auto',
    fontSize: '0.875rem',
    lineHeight: '1.5',
    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
    color: 'var(--hl-cmd)'
  }}>
                  <code key={`response-code-${useCase}-${response.length}`}>
                    {response.split('\n').map((line, i) => <div key={`response-line-${i}`} style={{
    display: 'flex',
    position: 'relative',
    paddingLeft: '3.5em',
    minHeight: '1.5em',
    lineHeight: '1.5'
  }}>
                        <span style={{
    position: 'absolute',
    left: 0,
    width: '2.5em',
    textAlign: 'right',
    color: 'var(--hl-line-num)',
    userSelect: 'none',
    paddingRight: '1em',
    lineHeight: '1.5'
  }}>{i + 1}</span>
                        <span style={{
    whiteSpace: 'pre-wrap',
    wordBreak: 'break-word',
    color: 'var(--hl-cmd)',
    lineHeight: '1.5'
  }}>
                          {line.match(/"[^"]+":/) ? <>
                              {line.split(/("[^"]+":)/).map((part, j) => part.match(/^"[^"]+":$/) ? <span key={`resp-part-${i}-${j}`} style={{
    color: 'var(--hl-flag)'
  }}>{part}</span> : part.match(/^"[^"]+"$/) ? <span key={`resp-part-${i}-${j}`} style={{
    color: 'var(--hl-str)'
  }}>{part}</span> : <span key={`resp-part-${i}-${j}`} style={{
    color: 'var(--hl-cmd)'
  }}>{part}</span>)}
                            </> : <span style={{
    color: 'var(--hl-cmd)'
  }}>{line}</span>}
                        </span>
                      </div>)}
                  </code>
                </pre>
              </div> : <div className="text-sm text-gray-500 dark:text-gray-400 text-center h-full flex items-center justify-center">
                No data returned from API
              </div>}
          </div>
        </div>
      </div>
    </div>;
};

Make your first Portal request to access raw EVM blockchain data in under 5 minutes. No setup required, just HTTP requests.

## What You'll Build

In this quickstart, you'll:

1. Make a simple Portal request using curl (no installation required)
2. Query recent Ethereum blocks
3. Filter event logs from a smart contract

<Info>
  This guide uses the **Public Portal** endpoint, which is free and
  rate-limited. Perfect for getting started.
</Info>

## Step 1: Your First Request

Let's query the last 1,000 blocks from Ethereum mainnet. Copy and paste this command:

<Tabs>
  <Tab title="curl">
    ```bash theme={"system"}
    curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/stream' \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "evm",
        "fromBlock": 18000000,
        "toBlock": 18001000,
        "includeAllBlocks": true,
        "fields": {
          "block": {
            "number": true,
            "timestamp": true,
            "gasUsed": true
          }
        }
      }'
    ```

    <Check>
      You should see a stream of JSON objects, one per block, showing block numbers,
      timestamps, and gas usage.
    </Check>

    <Note>
      `includeAllBlocks: true` tells Portal to return every block in the range.
      Without it (the default on EVM), Portal returns **only blocks matching your
      data filters** (`logs`, `transactions`, `traces`, `stateDiffs`). This request
      has no filters, so without `includeAllBlocks` it would return just the
      boundary blocks of the underlying workers, not the full range. See [Stream
      semantics](#stream-semantics) below.
    </Note>

    <Info>Try it yourself with the interactive query interface below:</Info>

    <QueryInterfaceQuickstart />
  </Tab>

  <Tab title="TypeScript">
    First, install the client:

    ```bash theme={"system"}
    npm install @subsquid/portal-client
    ```

    Then run this code:

    ```typescript theme={"system"}
    import { DataSource } from "@subsquid/portal-client";

    const dataSource = new DataSource({
      network: "ethereum-mainnet",
    });

    const blocks = await dataSource.getBlocks({
      from: 18000000,
      to: 18001000,
      includeAllBlocks: true,
      fields: {
        block: {
          number: true,
          timestamp: true,
          gasUsed: true,
        },
      },
    });

    console.log(`Retrieved ${blocks.length} blocks`);
    blocks.forEach((block) => {
      console.log(`Block ${block.header.number}: ${block.header.gasUsed} gas used`);
    });
    ```
  </Tab>

  <Tab title="Python">
    First, install requests:

    ```bash theme={"system"}
    pip install requests
    ```

    Then run this code:

    ```python theme={"system"}
    import requests
    import json

    url = "https://portal.sqd.dev/datasets/ethereum-mainnet/stream"
    headers = {"Content-Type": "application/json"}
    payload = {
        "type": "evm",
        "fromBlock": 18000000,
        "toBlock": 18001000,
        "includeAllBlocks": True,
        "fields": {
            "block": {
                "number": True,
                "timestamp": True,
                "gasUsed": True
            }
        }
    }

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

    # Response is newline-delimited JSON
    for line in response.text.strip().split('\n'):
        block = json.loads(line)
        print(f"Block {block['header']['number']}: {block['header']['gasUsed']} gas used")
    ```
  </Tab>
</Tabs>

## Step 2: Understanding the Request

Let's break down what you just sent:

```typescript theme={"system"}
{
  "type": "evm",              // Chain type (EVM, Solana, etc.)
  "fromBlock": 18000000,      // Starting block (inclusive)
  "toBlock": 18001000,        // Ending block (inclusive)
  "fields": {                 // What data to return
    "block": {
      "number": true,         // Block number
      "timestamp": true,      // Block timestamp
      "gasUsed": true         // Total gas used in block
    }
  }
}
```

<Tip>
  Portal only returns the fields you request. This keeps responses fast and
  bandwidth-efficient.
</Tip>

## Step 3: Understanding the Response

Portal returns **newline-delimited JSON (NDJSON)**. Each line is a complete JSON object representing one block. With `includeAllBlocks: true` the request above returns 1001 blocks (one per line). The first and last look like this:

```json theme={"system"}
{"header": {"number": 18000000, "timestamp": 1693066895, "gasUsed": "0xf7e9ab"}}
{"header": {"number": 18000001, "timestamp": 1693066907, "gasUsed": "0x1068c5a"}}
...
{"header": {"number": 18001000, "timestamp": 1693078967, "gasUsed": "0xae0606"}}
```

<Note>
  This format enables **constant-memory streaming** of massive ranges. You can
  process millions of blocks without loading everything into RAM.
</Note>

## Stream semantics

Two behaviors are easy to miss on your first Portal request. Both are enforced by the API, and clients that ignore them will silently drop data.

### `includeAllBlocks`

Portal returns **only blocks that match your data filters** (`logs`, `transactions`, `traces`, `stateDiffs`).

* If you set filters (e.g. `logs: [{ address: [...] }]`), Portal returns only blocks containing matching items. You rarely need `includeAllBlocks`.
* If you want **every** block in the range regardless of filters (for analytics, backfilling a full block table, etc.), set `"includeAllBlocks": true`.
* Defaults differ by chain: `false` on EVM, Solana, and Substrate; `true` on Bitcoin. Check the dataset's [API spec](/en/api/evm/stream) if in doubt.

Without filters and without `includeAllBlocks`, Portal returns just the worker-range boundary blocks. On EVM that's typically 2–4 blocks per query. If you see far fewer blocks than expected, this is why.

### The stream can end before `toBlock`

A single HTTP response can be cut short at any point: when a worker's range ends, when a connection is recycled, or at the dataset's current head. Clients must treat one response as a **batch**, not the entire range. To continue:

1. Read the last block number (`N`) in the response.
2. Issue a new request with `fromBlock = N + 1` (and the same `toBlock`, filters, and fields).
3. Loop until you receive HTTP 204 (range is above dataset height) or you reach your `toBlock`.

If you're streaming near the chain head, also set `parentBlockHash` on each subsequent request and handle HTTP 409 (reorg). See the [full API reference](/en/portal/evm/api#stream-continuation).

## Step 4: Filter Event Logs

Track USDC Transfer events:

<CodeGroup>
  ```bash curl theme={"system"}
  curl --compressed -X POST 'https://portal.sqd.dev/datasets/ethereum-mainnet/stream' \
    -H 'Content-Type: application/json' \
    -d '{
      "type": "evm",
      "fromBlock": 18000000,
      "toBlock": 18010000,
      "fields": {
        "log": {
          "address": true,
          "topics": true,
          "data": true,
          "transactionHash": true
        }
      },
      "logs": [{
        "address": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
        "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
      }]
    }'
  ```

  ```typescript TypeScript theme={"system"}
  import { DataSource } from "@subsquid/portal-client";

  const dataSource = new DataSource({
    network: "ethereum-mainnet",
  });

  const blocks = await dataSource.getBlocks({
    from: 18000000,
    to: 18010000,
    fields: {
      log: {
        address: true,
        topics: true,
        data: true,
        transactionHash: true,
      },
    },
    logs: [
      {
        address: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"], // USDC
        topic0: [
          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        ], // Transfer
      },
    ],
  });

  for (const block of blocks) {
    for (const log of block.logs) {
      console.log(`Transfer in tx ${log.transactionHash}`);
    }
  }
  ```

  ```python Python theme={"system"}
  import requests
  import json

  url = "https://portal.sqd.dev/datasets/ethereum-mainnet/stream"
  headers = {"Content-Type": "application/json"}
  payload = {
      "type": "evm",
      "fromBlock": 18000000,
      "toBlock": 18010000,
      "fields": {
          "log": {
              "address": True,
              "topics": True,
              "data": True,
              "transactionHash": True
          }
      },
      "logs": [{
          "address": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
          "topic0": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
      }]
  }

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

  for line in response.text.strip().split('\n'):
      block = json.loads(line)
      for log in block.get('logs', []):
          print(f"Transfer in tx {log['transactionHash']}")
  ```
</CodeGroup>

<Check>
  You should see Transfer events from the USDC contract. Portal filtered the
  data before sending, saving bandwidth.
</Check>

## What You Learned

In 5 minutes, you:

* ✓ Made HTTP requests to Portal
* ✓ Queried arbitrary block ranges
* ✓ Filtered smart contract events
* ✓ Processed newline-delimited JSON responses

## Rate Limits

The Public Portal is rate-limited:

* **20 requests per 10 seconds**
* Perfect for development and testing

<CardGroup cols={2}>
  <Card title="Cloud Portal" icon="cloud" href="/en/cloud/overview">
    Production-ready managed access with higher limits
  </Card>

  <Card title="Self-Host Portal" icon="server" href="/en/portal/self-hosting">
    Run your own Portal instance with no rate limits
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="API Reference" icon="book" href="/en/portal/evm/api">
    Complete reference with all fields and filters
  </Card>

  {" "}

  <Card title="View Examples" icon="code" href="/en/portal/evm/examples/query-logs">
    Practical examples for common use cases
  </Card>

  <Card title="Use with SDK" icon="brackets-curly" href="/en/sdk/overview">
    Build type-safe indexers with Portal as the data source
  </Card>
</CardGroup>

### Popular Examples

<CardGroup cols={2}>
  <Card title="Query Event Logs" icon="file-lines" href="/en/portal/evm/examples/query-logs">
    Track smart contract events
  </Card>

  {" "}

  <Card title="Query Transactions" icon="arrow-right-arrow-left" href="/en/portal/evm/examples/query-transactions">
    Monitor wallet activity
  </Card>

  {" "}

  <Card title="Track NFT Transfers" icon="image" href="/en/portal/evm/examples/nft-transfers">
    Index NFT collection activity
  </Card>

  <Card title="Index DEX Swaps" icon="repeat" href="/en/portal/evm/examples/dex-swaps">
    Build DEX analytics
  </Card>
</CardGroup>