diff --git a/apps/portal/src/app/insight/agents-and-llms/llmstxt/page.mdx b/apps/portal/src/app/insight/agents-and-llms/llmstxt/page.mdx index d0fa5396a94..4582d80714e 100644 --- a/apps/portal/src/app/insight/agents-and-llms/llmstxt/page.mdx +++ b/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 diff --git a/apps/portal/src/app/insight/agents-and-llms/page.mdx b/apps/portal/src/app/insight/agents-and-llms/page.mdx index 21aa5f6a6ff..6b9b1c4b029 100644 --- a/apps/portal/src/app/insight/agents-and-llms/page.mdx +++ b/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 diff --git a/apps/portal/src/app/insight/blueprints/page.mdx b/apps/portal/src/app/insight/blueprints/page.mdx index 3437745bb95..7da1a1f0f92 100644 --- a/apps/portal/src/app/insight/blueprints/page.mdx +++ b/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 diff --git a/apps/portal/src/app/insight/faqs/page.mdx b/apps/portal/src/app/insight/faqs/page.mdx index 86d5e657324..bb785becee4 100644 --- a/apps/portal/src/app/insight/faqs/page.mdx +++ b/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. \ No newline at end of file diff --git a/apps/portal/src/app/insight/get-started/page.mdx b/apps/portal/src/app/insight/get-started/page.mdx index 1019a1f1666..17451f66b78 100644 --- a/apps/portal/src/app/insight/get-started/page.mdx +++ b/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': '' + } + } + ); + 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': '' + } + } + ); + 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. diff --git a/apps/portal/src/app/insight/page.mdx b/apps/portal/src/app/insight/page.mdx index 075dcb733c7..e20102df6ac 100644 --- a/apps/portal/src/app/insight/page.mdx +++ b/apps/portal/src/app/insight/page.mdx @@ -1,7 +1,7 @@ import { OpenSourceCard, DocImage, Grid, ArticleCard, FeatureCard } from "@doc"; import { createMetadata } from "@/components/Document"; import SupportedChains from "../_images/supported-chains.png"; -import { WalletIcon, FileIcon, MessageCircleIcon, BracesIcon, BotIcon, BlocksIcon, AlbumIcon, ServerIcon, ZapIcon } from "lucide-react"; +import { WalletIcon, FileIcon, MessageCircleIcon, BracesIcon, BotIcon, BlocksIcon, AlbumIcon, ServerIcon, ZapIcon, FunctionSquareIcon } from "lucide-react"; export const metadata = createMetadata({ @@ -22,7 +22,7 @@ Insight is a tool that lets you retrieve blockchain data from any EVM chain, enr ## Features
} /> + } + href="/insight/get-started#using-aggregations" + /> + } /> - } /> - -
## Video Tutorials diff --git a/apps/portal/src/app/insight/use-cases/page.mdx b/apps/portal/src/app/insight/use-cases/page.mdx index d07d095a5f1..2e208abb8e7 100644 --- a/apps/portal/src/app/insight/use-cases/page.mdx +++ b/apps/portal/src/app/insight/use-cases/page.mdx @@ -19,12 +19,12 @@ making it a powerful tool for building dynamic blockchain applications. | --- | --- | | Display in-game assets such as items or tokens (ERC-20, ERC-721, or ERC-1155) tied to the player's wallet. | Use Events Blueprint to fetch transfer events where the player’s wallet is the recipient, showing all NFTs or in-game items acquired by the player. | | Display earned tokens based on achievements or progress rewarded to players in games. | Use Transactions Blueprint to track transactions where the game’s smart contract sends tokens to a player’s wallet.
Use Events Blueprint to filter transfer events from the game’s contract to list all tokens awarded to players. | -| Analyze token economics such as daily trading volume to understand token liquidity or market activity. | Use the Transactions Blueprint to get transactions involving any token and then aggregate data based on timestamps to calculate 24-hour transaction volumes. | -| Analyze gas consumption of different transactions to help minimize gas fees for users by evaluating high-gas transactions or commonly used functions. | Use Transactions Blueprint to summarize gas usage across transactions for specific functions, helping to analyze and optimize protocol functions for efficiency. | +| Analyze token economics such as daily trading volume to understand token liquidity or market activity. | Use the Transactions Blueprint to get transactions involving any token and then aggregate data based on timestamps to calculate 24-hour transaction volumes.

**Example Aggregations:**
- `sum(value) AS daily_volume`
- `count() AS transaction_count`
- `avg(value) AS avg_tx_value` | +| Analyze gas consumption of different transactions to help minimize gas fees for users by evaluating high-gas transactions or commonly used functions. | Use Transactions Blueprint to summarize gas usage across transactions for specific functions, helping to analyze and optimize protocol functions for efficiency.

**Example Aggregations:**
- `avg(gas_used) AS avg_gas_used`
- `max(gas_used) AS max_gas_used`
- `sum(gas_used * gas_price) AS total_fees_wei` | | Analyze token ownership to understand community health and investment risks. | Use Events Blueprint to track token transfer events, allowing users to analyze the distribution and concentration of token holders. | -| Track the movements of an entire NFT collection. | Use Events Blueprint to capture all transfer events for a specified collection and show ownership history or current trading volume for the collection. | +| Track the movements of an entire NFT collection. | Use Events Blueprint to capture all transfer events for a specified collection and show ownership history or current trading volume for the collection.

**Example Aggregations:**
- `countDistinct(from_address) AS unique_sellers`
- `countDistinct(to_address) AS unique_buyers`
- `count() AS total_transfers` | | Fetch all NFTs owned by a specific wallet address. | Use Events Blueprint to fetch transfer events for each NFT contract where the specified wallet address is the recipient. | -| Fetch all transactions emitted by a single wallet across multiple chains. | Use Transactions Blueprint to filter transactions by wallet address across different chain_ids to provide a historical view of cross-chain transactions. | +| Fetch all transactions emitted by a single wallet across multiple chains. | Use Transactions Blueprint to filter transactions by wallet address across different chain_ids to provide a historical view of cross-chain transactions.

**Example Aggregations:**
- `count() AS total_transactions`
- `sum(value) AS total_value_transferred` | | Fetch all tokens owned by a specific wallet address. | Use Events Blueprint to find transfer events where the wallet address is the recipient, providing a list of token balances. | | Detect wallet staking activity on platforms such as AAVE or other DeFi protocols. | Use Events Blueprint to filter for staking-related events such as deposits, and monitor which wallets are actively staking. |