docs: add docs on aggregates (#7201)

# [Portal] Feature: Add Aggregation Examples and Documentation to Insight

## Notes for the reviewer

This PR adds comprehensive documentation for the Insight aggregation functionality across multiple pages:

- Added an "Aggregation Examples" section to the LLMs page with code samples
- Added detailed aggregation documentation to the Agents and LLMs page
- Added aggregation examples to the Blueprints page for Events, Transactions, Wallet Transactions, and Blocks
- Added FAQs about aggregation queries
- Added "Using Aggregation Presets" section to the Get Started page
- Enhanced Use Cases page with example aggregations for relevant scenarios

## How to test

Review the documentation for clarity and accuracy. The examples should be consistent with the actual API functionality.

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

- **Documentation**
  - Added comprehensive examples and explanations for using aggregation functions in Insight API queries across multiple documentation sections, including blueprints, use cases, FAQs, and getting started guides.
  - Introduced new sections detailing aggregation presets, usage patterns, and code snippets for blockchain data analysis.
  - Enhanced clarity on performing statistical and summary queries, with guidance on leveraging the Insight Playground for interactive exploration.
  - Updated the Insight landing page with a new feature card highlighting powerful aggregation capabilities and improved layout for feature cards.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

<!-- start pr-codex -->

---

## PR-Codex overview
This PR enhances the documentation for the `Insight` tool by adding new aggregation features, examples, and updating existing content to clarify how to utilize these functionalities effectively.

### Detailed summary
- Added `FunctionSquareIcon` to the import statement in `page.mdx`.
- Updated grid layout class from `lg:grid-cols-2` to `lg:grid-cols-3` in `page.mdx`.
- Introduced a new `FeatureCard` titled "Powerful Aggregations" in `page.mdx`.
- Added sections on aggregation queries and examples in `faqs/page.mdx`, `get-started/page.mdx`, and `agents-and-llms/page.mdx`.
- Provided aggregation examples in `use-cases/page.mdx` and `blueprints/page.mdx`.
- Enhanced documentation for wallet transactions and blocks, including aggregation examples in `agents-and-llms/page.mdx`.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}`

<!-- end pr-codex -->

Author: catalyst17

apps/portal/src/app/insight/agents-and-llms/llmstxt/page.mdx

@@ -34,6 +34,64 @@ Insight is a powerful tool that lets you retrieve blockchain data from any EVM c
 
 - **Response Processing**: Some numeric values are returned as strings to maintain precision. Convert them appropriately in your application.
 
+## Aggregation Examples
+
+Insight supports various aggregation functions that can be used to analyze blockchain data. Here are some common examples:
+
+### Basic Aggregations
+
+```typescript
+// Count all transactions
+const count = await fetch('https://10.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count');
+
+// Get total value transferred (in wei)
+const totalValue = await fetch('https://10.insight.thirdweb.com/v1/transactions?aggregate=sum(value) AS total_value_wei');
+
+// Get average gas used
+const avgGas = await fetch('https://10.insight.thirdweb.com/v1/transactions?aggregate=avg(gas_used) AS avg_gas_used');
+```
+
+### Wallet-Specific Aggregations
+
+```typescript
+// Get wallet transaction count and total value
+const walletStats = await fetch(
+  'https://10.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei'
+);
+
+// Calculate total fees paid by a wallet
+const walletFees = await fetch(
+  'https://10.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=sum(gas_used * gas_price) AS total_fees_wei'
+);
+```
+
+### Block Data Aggregations
+
+```typescript
+// Get block statistics
+const blockStats = await fetch(
+  'https://10.insight.thirdweb.com/v1/blocks?aggregate=sum(transaction_count) AS total_transactions&aggregate=avg(transaction_count) AS avg_transactions_per_block'
+);
+
+// Get block range
+const blockRange = await fetch(
+  'https://10.insight.thirdweb.com/v1/blocks?aggregate=min(number) AS min_block_number&aggregate=max(number) AS max_block_number'
+);
+```
+
+### Filtering with Aggregations
+
+```typescript
+// Get transaction stats for a specific time period
+const txStats = await fetch(
+  'https://10.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&filter_timestamp_gte=2024-01-01&filter_timestamp_lte=2024-01-31'
+);
+
+// Get block metrics for recent blocks
+const recentBlocks = await fetch(
+  'https://10.insight.thirdweb.com/v1/blocks?aggregate=sum(transaction_count) AS total_transactions&filter_number_gte=18000000'
+);
+```
 
 ## API URL
 

apps/portal/src/app/insight/agents-and-llms/page.mdx

@@ -190,6 +190,100 @@ async function getNFTBalances(ownerAddress: string) {
 }
 ```
 
+### Aggregations
+
+Insight supports powerful aggregation functions that can be used to analyze blockchain data. Here's how to use them:
+
+```typescript
+// Basic aggregation structure
+const response = await fetch(
+  'https://{{chainId}}.insight.thirdweb.com/v1/endpoint?aggregate=function(field) AS alias',
+  { headers: { 'x-client-id': '{{clientId}}' } }
+);
+
+// Multiple aggregations in one request
+const response = await fetch(
+  'https://{{chainId}}.insight.thirdweb.com/v1/endpoint?aggregate=count() AS total&aggregate=sum(value) AS total_value',
+  { headers: { 'x-client-id': '{{clientId}}' } }
+);
+
+// With filters
+const response = await fetch(
+  'https://{{chainId}}.insight.thirdweb.com/v1/transactions?aggregate=count() AS tx_count&filter_timestamp_gte=2024-01-01',
+  { headers: { 'x-client-id': '{{clientId}}' } }
+);
+```
+
+#### Aggregation Presets available in the playground as examples
+
+1. **Default Aggregations**
+   - `count() AS count_all` - Count all items
+   - `sum(gas_used) AS total_gas_used` - Total gas used
+   - `avg(gas_used) AS avg_gas_used` - Average gas used
+   - `min(gas_used) AS min_gas_used` - Minimum gas used
+   - `max(gas_used) AS max_gas_used` - Maximum gas used
+   - `countDistinct(column_name) AS unique_count` - Count distinct values
+
+2. **Events Specific**
+   - `count() AS event_count` - Count events
+   - `countDistinct(address) AS unique_addresses` - Unique addresses
+   - `min(block_number) AS min_block` - Minimum block number
+   - `max(block_number) AS max_block` - Maximum block number
+
+3. **Transactions Specific**
+   - `count() AS transaction_count` - Count transactions
+   - `sum(value) AS total_value_wei` - Total value transferred
+   - `sum(gas_used) AS total_gas_used` - Total gas used
+   - `avg(value) AS avg_value_wei` - Average value
+   - `avg(gas_used) AS avg_gas_used` - Average gas used
+   - `countDistinct(from_address) AS unique_senders` - Unique senders
+   - `countDistinct(to_address) AS unique_receivers` - Unique receivers
+
+4. **Wallet Transactions**
+   - `count() AS transaction_count` - Transaction count
+   - `sum(value) AS total_value_wei` - Total value
+   - `avg(value) AS avg_value_wei` - Average value
+   - `sum(gas_used * gas_price) AS total_fees_wei` - Total fees
+
+5. **Blocks Specific**
+   - `sum(transaction_count) AS total_transactions` - Total transactions
+   - `avg(transaction_count) AS avg_transactions_per_block` - Avg tx/block
+   - `sum(gas_used) AS total_gas_used` - Total gas used
+   - `min(number) AS min_block_number` - Min block number
+   - `max(number) AS max_block_number` - Max block number
+
+#### Common Aggregation Examples
+
+```typescript
+// 1. Get transaction statistics
+const txStats = await fetch(
+  'https://{{chainId}}.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&aggregate=avg(gas_used) AS avg_gas_used',
+  { headers: { 'x-client-id': '{{clientId}}' } }
+);
+
+// 2. Get wallet transaction stats
+const walletStats = await fetch(
+  'https://{{chainId}}.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&aggregate=sum(gas_used * gas_price) AS total_fees_wei',
+  { headers: { 'x-client-id': '{{clientId}}' } }
+);
+```
+
+#### Filtering with Aggregations
+
+```typescript
+// Get transaction stats for a specific time period
+const txStats = await fetch(
+  'https://{{chainId}}.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&filter_timestamp_gte=2024-01-01&filter_timestamp_lte=2024-01-31',
+  { headers: { 'x-client-id': '{{clientId}}' } }
+);
+
+// Get block metrics for recent blocks
+const blockStats = await fetch(
+  'https://{{chainId}}.insight.thirdweb.com/v1/blocks?aggregate=sum(transaction_count) AS total_transactions&aggregate=avg(transaction_count) AS avg_transactions_per_block&filter_number_gte=18000000',
+  { headers: { 'x-client-id': '{{clientId}}' } }
+);
+```
+
 ### Using Filters
 
 ```typescript

apps/portal/src/app/insight/blueprints/page.mdx

@@ -35,6 +35,32 @@ Blockchain events offers developers a powerful way to track and analyze blockcha
 | Block Number | The `block_number` indicates the position of the block in the blockchain. It tells you when (in terms of blockchain sequence) the event occurred. | Block number 12,345,678 on Ethereum might contain transactions from a particular moment, such as the transfer of 10 ETH between two accounts. You can think of block numbers like page numbers in a ledger.
 | Block Timestamp | The `block_timestamp` is the exact time when the block was mined and added to the blockchain. | If block 12,345,678 was mined on July 1, 2023, at 12:30 PM UTC, the timestamp will reflect this exact moment. This helps you pinpoint when an event, such as a token transfer, actually happened in real time.
 
+### Aggregations Examples
+
+#### Get Event Statistics
+```typescript
+// Get total event count and unique addresses
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/events?aggregate=count() AS event_count&aggregate=countDistinct(address) AS unique_addresses'
+);
+```
+
+#### Track Collection Activity
+```typescript
+// Get min/max block numbers and unique topics
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/events?aggregate=min(block_number) AS min_block&aggregate=max(block_number) AS max_block&aggregate=countDistinct(topic0) AS unique_topics'
+);
+```
+
+#### Custom Aggregations
+```typescript
+// Custom aggregations for specific analysis
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/events?aggregate=count() AS transfers&aggregate=countDistinct(from_address) AS unique_senders&aggregate=countDistinct(to_address) AS unique_recipients'
+);
+```
+
 ## Transactions Blueprint
 
 Transaction data equips developers with the tools they need to interact with blockchain data efficiently and effectively. By providing clear, actionable insights into each transaction, the API helps streamline tasks like monitoring smart contract interactions, tracking asset transfers, and debugging. Developers can rely on this endpoint to access essential transaction details, enabling faster troubleshooting and more informed decision-making. Whether building DeFi platforms, dApps, or blockchain-based analytics tools, transaction data is the essence for all interactions with any chains.
@@ -62,6 +88,67 @@ Transaction data equips developers with the tools they need to interact with blo
 | Block Timestamp | This is the exact time when the block containing the transaction was mined and added to the blockchain. | If the transaction was confirmed on July 1, 2023, at 12:30 PM UTC, the block timestamp will reflect this moment. It's useful for analyzing when specific activities (like token transfers) occurred.
 | r, s, v | These are the cryptographic components of the transaction signature. They prove that the transaction was signed by the private key associated with the sender's address. | The `r`, `s`, and `v` values are produced during the signing process and are necessary to verify the authenticity of the transaction on the blockchain.
 
+### Aggregations Examples
+
+#### Get Transaction Statistics
+```typescript
+// Get total transaction count and total value transferred
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value'
+);
+```
+
+#### Analyze Gas Usage
+```typescript
+// Get average and max gas used
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/transactions?aggregate=avg(gas_used) AS avg_gas&aggregate=max(gas_used) AS max_gas'
+);
+```
+
+## Wallet Transactions Blueprint
+
+The Wallet Transactions Blueprint provides detailed transaction history for specific wallet addresses, making it easy to track all activities associated with a particular address.
+
+### Aggregation Examples
+
+#### Get Wallet Summary
+```typescript
+// Get total transaction count and total value for a wallet
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value'
+);
+```
+
+#### Calculate Total Fees Paid
+```typescript
+// Calculate total fees paid by a wallet
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/wallets/0x123.../transactions?aggregate=sum(gas_used * gas_price) AS total_fees'
+);
+```
+
+## Blocks Blueprint
+
+The Blocks Blueprint provides access to blockchain block data, including block details, transaction counts, and gas usage statistics.
+
+### Aggregation Examples
+
+#### Get Block Statistics
+```typescript
+// Get total block count and total transactions
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/blocks?aggregate=count() AS block_count&aggregate=sum(transaction_count) AS total_transactions'
+);
+```
+
+#### Analyze Block Metrics
+```typescript
+// Get average transactions per block and total gas used
+const response = await fetch(
+  'https://1.insight.thirdweb.com/v1/blocks?aggregate=avg(transaction_count) AS avg_transactions&aggregate=sum(gas_used) AS total_gas_used'
+);
+```
 
 ## Tokens Blueprint
 

apps/portal/src/app/insight/faqs/page.mdx

@@ -1,3 +1,30 @@
 # Insight FAQs
 
+## Aggregation Queries
+
+### How do I use aggregations in my queries?
+You can include aggregation functions directly in your API requests. Here's an example:
+```typescript
+// Get total transaction value and average gas used
+const response = await fetch(
+  'https://10.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value_wei&aggregate=avg(gas_used) AS avg_gas_used'
+);
+```
+
+### Where can I find examples of using aggregations?
+You can find working examples and experiment with different aggregation presets in the Insight Playground. The Playground provides a user-friendly interface to build and test your aggregation queries.
+
+### What are some common use cases for aggregations?
+- Calculating total trading volume
+- Finding average transaction values
+- Counting unique users/wallets
+- Analyzing gas usage patterns
+- Tracking NFT collection statistics
+
+### Can I create custom aggregations?
+Yes, you can create custom aggregations using standard SQL aggregation functions like `count()`, `sum()`, `avg()`, `min()`, `max()`, and `countDistinct()`. The presets are just convenient shortcuts for common operations.
+
+### Where can I learn more about available presets?
+You can find the complete list of available aggregation presets in the Insight Playground, where you can also test them with real blockchain data.
+
 More information coming soon.

apps/portal/src/app/insight/get-started/page.mdx

@@ -139,6 +139,60 @@ Once you execute the query above you will receive a result similar to this:
 }
 ```
 
+## Using Aggregations
+
+Insight provides several predefined aggregation presets that make it easy to analyze your blockchain data. These presets are available in the Insight Playground, where you can experiment with them using a user-friendly interface.
+
+### Example: Get Transaction Statistics
+
+```typescript
+const getTransactionStats = async () => {
+  try {
+    const response = await fetch(
+      'https://1.insight.thirdweb.com/v1/transactions?aggregate=count() AS transaction_count&aggregate=sum(value) AS total_value&aggregate=avg(gas_used) AS avg_gas',
+      {
+        headers: {
+          'x-client-id': '<YOUR_THIRDWEB_CLIENT_ID>'
+        }
+      }
+    );
+    const stats = await response.json();
+    return stats;
+  } catch (error) {
+    console.error('Error:', error);
+  }
+};
+```
+
+### Example: Get Block Metrics
+
+```typescript
+const getBlockMetrics = async () => {
+  try {
+    const response = await fetch(
+      'https://1.insight.thirdweb.com/v1/blocks?aggregate=count() AS block_count&aggregate=sum(transaction_count) AS total_transactions&aggregate=avg(transaction_count) AS avg_transactions',
+      {
+        headers: {
+          'x-client-id': '<YOUR_THIRDWEB_CLIENT_ID>'
+        }
+      }
+    );
+    const metrics = await response.json();
+    return metrics;
+  } catch (error) {
+    console.error('Error:', error);
+  }
+};
+```
+
+### Explore in the Playground
+
+For a more interactive experience, try out the aggregation presets in the Insight Playground. The Playground allows you to:
+- Browse available presets for each endpoint
+- See real-time results
+- Generate code snippets for your application
+- Test different aggregation combinations
+
 ## Multichain Queries
 
 Insight also supports querying multiple chains in a single API call. This is useful when you need to retrieve data across different networks without making separate requests.