Skip to content

Commit c3ded8a

Browse files
committed
docs: multichain queries (#6375)
[Portal] Feature: Add multichain queries documentation and examples ## Notes for the reviewer This PR introduces comprehensive documentation for multichain query functionality in Insight, including detailed examples, response formats, and best practices. ## How to test - Review the new multichain queries documentation page - Verify the code examples work with the described response formats - Check that the sidebar navigation correctly links to the new documentation - Confirm the authentication methods and chain ID formats are accurately described --- ## PR-Codex overview This PR enhances the `Insight` docs by documenting multichain queries. It updates various documentation files to reflect new features, examples, and response formats related to multichain functionality. ### Detailed summary - Added `Multichain Queries` section to the sidebar in `sidebar.tsx`. - Introduced examples for querying multiple chains in `page.mdx` files. - Updated chain ID handling examples in `agents-and-llms/page.mdx` and `llmstxt/page.mdx`. - Detailed multichain response structure added to documentation. - Explained authentication methods for multichain queries. - Provided best practices and use cases for multichain queries in `multichain-queries/page.mdx`. - Updated response format details for multichain queries, including metadata and data array structure. - Included examples for cross-chain portfolio tracking and activity monitoring. > ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}` <!-- start pr-codex --> --- ## PR-Codex overview This PR introduces support for multichain queries in the `thirdweb Insight` API, enhancing the ability to retrieve data across multiple blockchain networks in a single API call. ### Detailed summary - Added a new entry for "Multichain Queries" in the `sidebar`. - Updated examples to illustrate querying multiple chains using query parameters. - Enhanced documentation for multichain queries with examples and best practices. - Modified response formats to include `chain_ids` and `limit_per_chain` for multichain queries. - Updated existing examples to reflect multichain capabilities. > ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}` <!-- end pr-codex -->
1 parent 257d0bd commit c3ded8a

File tree

6 files changed

+350
-20
lines changed

6 files changed

+350
-20
lines changed

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

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -74,18 +74,24 @@ async function getEvents() {
7474

7575
### Chain IDs
7676

77-
The API supports chain IDs in the following format:
77+
The API supports chain IDs in the following formats:
7878

79+
- As a subdomain:
7980
```typescript
80-
interface ChainConfig {
81-
chainId: number; // Chain ID of the network you want to query
82-
}
83-
84-
// Example: Using a specific chain
85-
const chainId = "{{chainId}}"; // Replace with your desired chain ID
81+
// Example
8682
const baseUrl = `https://{{chainId}}.insight.thirdweb.com`;
8783
```
8884

85+
- As a query parameter (this is useful if you want to query multiple chains):
86+
```typescript
87+
// Example for a single chain
88+
const url = `https://insight.thirdweb.com/v1/events?chain={{chainId}}`;
89+
// Example for multiple chains
90+
const url = `https://insight.thirdweb.com/v1/events?chain=1&chain=137`;
91+
```
92+
93+
We won't duplicate multichain examples for each endpoint, but you can pass multiple chains in the query parameters pretty much everywhere!
94+
8995
### Base Response Structure
9096

9197
```typescript
@@ -265,6 +271,12 @@ async function safeApiCall() {
265271
GET https://{{chainId}}.insight.thirdweb.com/v1/events
266272
```
267273

274+
or
275+
276+
```typescript
277+
GET https://insight.thirdweb.com/v1/events?chainId={{chainId1}}&chainId={{chainId2}}
278+
```
279+
268280
2. **Get Contract Events**
269281

270282
```typescript

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

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,14 +63,22 @@ async function getEvents() {
6363

6464
### Chain IDs
6565

66+
- As a subdomain:
6667
```typescript
67-
type ChainId = number; // Chain ID of the network you want to query (e.g., 1 for Ethereum mainnet)
68+
// Example
69+
const baseUrl = `https://{{chainId}}.insight.thirdweb.com`;
70+
```
6871

69-
// Example: Using a specific chain
70-
const chainId = 1; // Ethereum mainnet
71-
const baseUrl = `https://${chainId}.insight.thirdweb.com`;
72+
- As a query parameter (this is useful if you want to query multiple chains):
73+
```typescript
74+
// Example for a single chain
75+
const url = `https://insight.thirdweb.com/v1/events?chain={{chainId}}`;
76+
// Example for multiple chains
77+
const url = `https://insight.thirdweb.com/v1/events?chain=1&chain=137`;
7278
```
7379

80+
We won't duplicate multichain examples for each endpoint, but you can pass multiple chains in the query parameters pretty much everywhere!
81+
7482
### Base Response Structure
7583

7684
```typescript

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

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ export const metadata = createMetadata({
1414

1515
A blueprint is an API that provides access to on-chain data in a user-friendly format. There's no need for ABIs, decoding, RPC, or web3 knowledge to fetch blockchain data. Every chain exposes the default blueprints below
1616

17+
All blueprints support [multichain queries](/insight/multichain-queries)!
18+
1719
## Events Blueprint
1820

1921
Blockchain events offers developers a powerful way to track and analyze blockchain events emitted by smart contracts. This endpoint provides access to detailed event information, such as the address of the contract that generated the event, the transaction that triggered it, and when and where the event occurred on the blockchain. By offering data points like event topics, block numbers, and transaction hashes, developers can easily filter and search for specific event types, such as token transfers or contract executions. With precise timestamps and block references, the Events Blueprint ensures that developers have real-time access to critical on-chain activity, enabling them to build responsive, high-performance applications that can monitor, analyze, and react to blockchain events seamlessly. Whether working on DeFi, NFTs, or general dApps, this endpoint helps unlock the full potential of blockchain data in any project.
@@ -22,14 +24,14 @@ Blockchain events offers developers a powerful way to track and analyze blockcha
2224

2325
| Name | Description | Example |
2426
| ----------- | ----------- | ----------- |
25-
| Address | The `address` is the identifier of the smart contract or account that emitted the event. It tells you who or what generated the event. | If the event is related to an ERC-20 token transfer, the address would be the smart contract address of the token. For instance, if youre tracking events for the USDT token, the address would be the contract address of USDT on Ethereum. |
26-
| Chain ID | The `chain_id` is a unique identifier for the blockchain network where the event occurred. Different blockchain networks (e.g., Ethereum, Binance Smart Chain, Polygon) have their own unique chain IDs. | Ethereums mainnet has a chain_id of 1, while Binance Smart Chain has a chain_id of 56. This field ensures you know which network the event is coming from, which is crucial when interacting with multiple EVM chains.
27-
| Data | The `data` field contains additional information specific to the event. In many cases, its the raw output of the smart contract event. | In an ERC-20 Transfer event, the data might include the number of tokens transferred in raw hexadecimal format. For instance, if 1000 USDT were transferred, this value would be encoded in the events data field.
27+
| Address | The `address` is the identifier of the smart contract or account that emitted the event. It tells you who or what generated the event. | If the event is related to an ERC-20 token transfer, the address would be the smart contract address of the token. For instance, if you're tracking events for the USDT token, the address would be the contract address of USDT on Ethereum. |
28+
| Chain ID | The `chain_id` is a unique identifier for the blockchain network where the event occurred. Different blockchain networks (e.g., Ethereum, Binance Smart Chain, Polygon) have their own unique chain IDs. | Ethereum's mainnet has a chain_id of 1, while Binance Smart Chain has a chain_id of 56. This field ensures you know which network the event is coming from, which is crucial when interacting with multiple EVM chains.
29+
| Data | The `data` field contains additional information specific to the event. In many cases, it's the raw output of the smart contract event. | In an ERC-20 Transfer event, the data might include the number of tokens transferred in raw hexadecimal format. For instance, if 1000 USDT were transferred, this value would be encoded in the event's data field.
2830
| Log Index | The `log_index` is the order of the log (event) in the list of all events within the block. It helps you pinpoint exactly where this event is located in the block. | If multiple events occurred within the same block (e.g., multiple token transfers), the log_index tells you the sequence of this particular event. For example, it might be the 3rd event in the block.
29-
| Topics | The `topics` array contains indexed parameters of the event, often used for filtering or categorizing events. The first topic contains the event signature (the function name), while the remaining topics contain indexed event arguments. | In an ERC-20 Transfer event, the first topic would be the hash of the event signature `Transfer(address,address,uint256)`. The second topic would be the senders address, and the third would be the receivers address. This allows filtering to track all Transfer events for a specific address.
31+
| Topics | The `topics` array contains indexed parameters of the event, often used for filtering or categorizing events. The first topic contains the event signature (the function name), while the remaining topics contain indexed event arguments. | In an ERC-20 Transfer event, the first topic would be the hash of the event signature `Transfer(address,address,uint256)`. The second topic would be the sender's address, and the third would be the receiver's address. This allows filtering to track all Transfer events for a specific address.
3032
| Transaction Hash | The `transaction_hash` is the unique identifier for the transaction that triggered the event. It helps you link the event to the specific transaction that caused it. | If you transfer 1 ETH to another wallet, the transaction hash might be 0x5c7b6f... which uniquely identifies that transaction. Using this hash, you can look up the transaction in any block explorer (e.g., Etherscan) to see all the details.
3133
| Transaction Index | The `transaction_index` tells you the position of the transaction within the block. This helps you identify where in the block this particular transaction was placed relative to others. | If multiple transactions occurred within the same block (e.g., multiple token transfers), the transaction_index tells you the sequence of this particular transaction. For example, it might be the 3rd transaction in the block. | If a block contains 100 transactions, the transaction_index might indicate that this event was triggered by the 45th transaction in the block. This is useful for debugging or tracing the order of execution.
32-
| Block Hash | A `block_hash` is the unique identifier of a block, generated after the block is confirmed. Its like a tamper-proof record of all the transactions and events in that block. | If you wanted to verify that a particular transaction or event was part of a block, you could use the block hash to check its integrity. Think of it as a digital signature for the entire block, such as 0x91d representing all transactions within that specific block.
34+
| Block Hash | A `block_hash` is the unique identifier of a block, generated after the block is confirmed. It's like a tamper-proof record of all the transactions and events in that block. | If you wanted to verify that a particular transaction or event was part of a block, you could use the block hash to check its integrity. Think of it as a digital signature for the entire block, such as 0x91d... representing all transactions within that specific block.
3335
| 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.
3436
| 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.
3537

@@ -41,7 +43,7 @@ Transaction data equips developers with the tools they need to interact with blo
4143

4244
| Name | Description | Example |
4345
| ----------- | ----------- | ----------- |
44-
| From Address | This is the address that initiated the transaction. It represents the sender who paid for the gas to execute the transaction. | If a user sends 1 ETH from their wallet, the `from_address` will be the senders Ethereum address, such as `0xabc123...`.
46+
| From Address | This is the address that initiated the transaction. It represents the sender who paid for the gas to execute the transaction. | If a user sends 1 ETH from their wallet, the `from_address` will be the sender's Ethereum address, such as `0xabc123...`.
4547
| To Address | This is the recipient of the transaction. It could be another wallet or a smart contract. | If sending ETH to a friend, their wallet address, like `0xdef456...`, would be the `to_address`. In the case of interacting with a DeFi platform, the address of the smart contract being called would be the `to_address`.
4648
| Hash | The unique identifier (hash) of the transaction. This hash can be used to look up and verify the transaction on the blockchain. | A transaction might have a hash like `0x5c7b6f...`. You can use this hash to check the transaction status on a block explorer like Etherscan.
4749
| Value | This is the amount of cryptocurrency (in wei) being transferred in the transaction. | If transferring 1 ETH, the `value` would be 1,000,000,000,000,000,000 wei (1 ETH = 10^18 wei).
@@ -50,10 +52,10 @@ Transaction data equips developers with the tools they need to interact with blo
5052
| Max Fee Per Gas | This is the maximum amount of gas fees (in wei) the sender is willing to pay for each gas unit. It was introduced in EIP-1559 to provide a cap on gas costs. | If `max_fee_per_gas` is set to 200 gwei, the sender is ensuring that they will never pay more than this for each gas unit, even during periods of high network congestion.
5153
| Max Priority Fee Per Gas | This is the maximum additional fee the sender is willing to pay to incentivize miners to prioritize their transaction. Also introduced in EIP-1559. | A transaction might specify a `max_priority_fee_per_gas` of 2 gwei, which acts as a "tip" for miners to get their transaction included faster in a block.
5254
| Data | The `data` field contains additional information required by a transaction, such as the input parameters for interacting with a smart contract. | In a call to a DeFi contract's `swap` function, the `data` field will include the encoded function call and arguments (e.g., token amount, recipient address).
53-
| Nonce | The `nonce` is the number of transactions sent from the senders address. It ensures that transactions are processed in the correct order and prevents double-spending. | If the sender has sent 5 transactions before, the nonce will be 5. This helps in tracking the sequence of transactions and ensuring that each one is processed correctly. | If the `nonce` is 12, it means this is the 13th transaction (starting from 0) sent from the `from_address`
55+
| Nonce | The `nonce` is the number of transactions sent from the sender's address. It ensures that transactions are processed in the correct order and prevents double-spending. | If the sender has sent 5 transactions before, the nonce will be 5. This helps in tracking the sequence of transactions and ensuring that each one is processed correctly. | If the `nonce` is 12, it means this is the 13th transaction (starting from 0) sent from the `from_address`
5456
| Transaction Index | The position of the transaction within the block. It indicates the order in which the transaction was included relative to other transactions | If the `transaction_index` is 5, this was the 6th transaction included in the block.
5557
| Transaction Type | The type of transaction, typically either legacy (type `0x0` ) or one of the newer types introduced in EIP-1559 (e.g., type `0x2` for transactions that use the new gas fee mechanism). | A `transaction_type` of `0x2` indicates the transaction follows the new EIP-1559 rules for gas fees.
56-
| Access List | The `access_list` is an optional field introduced in EIP-2930 that specifies which addresses and storage slots the transaction intends to interact with. Its used to optimize gas costs by pre-declaring the data access needed. | When a transaction interacts with a smart contract, the `access_list` may declare the contract address and storage slots the transaction intends to read from or write to. For example, interacting with a DeFi smart contract could include its contract address and the storage slots holding user balances.
58+
| Access List | The `access_list` is an optional field introduced in EIP-2930 that specifies which addresses and storage slots the transaction intends to interact with. It's used to optimize gas costs by pre-declaring the data access needed. | When a transaction interacts with a smart contract, the `access_list` may declare the contract address and storage slots the transaction intends to read from or write to. For example, interacting with a DeFi smart contract could include its contract address and the storage slots holding user balances.
5759
| Chain ID | The `chain_id` identifies the blockchain network on which the transaction was conducted. It prevents replay attacks across different networks. | On Ethereum mainnet, the chain ID is `1`, while on Base Mainnet, the chain ID is `8453` . This field tells you which network the transaction belongs to.
5860
| Block Hash | This is the unique identifier (or "fingerprint") of the block that includes this transaction. The hash ensures that the block hasn't been altered. | If the transaction is included in block `12,345,678`, the block's hash might look like `0xabc123...`, and this hash can be used to reference that particular block on the blockchain.
5961
| Block Number | The `block_number` indicates the specific position of the block in the blockchain that contains the transaction. | If a transaction is included in block `12,345,678`, this number can be used to quickly locate the block and all the transactions it contains.
@@ -67,7 +69,7 @@ Tokens on blockchain can be of different standards, but ones of the most widely
6769
- ERC-20 for fungible tokens
6870
- ERC-721 and ERC-1155 for NFTs
6971

70-
This blueprint provides access to such tokens balances information for a given owner address.
72+
This blueprint provides access to such tokens' balances information for a given owner address.
7173

7274
### Blueprint details
7375

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,3 +138,60 @@ Once you execute the query above you will receive a result similar to this:
138138
]
139139
}
140140
```
141+
142+
## Multichain Queries
143+
144+
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.
145+
146+
```typescript
147+
const getMultichainTransfers = async () => {
148+
try {
149+
// Query USDT transfers on Ethereum (1) and Polygon (137)
150+
const response = await fetch('https://insight.thirdweb.com/v1/events?chain=1&chain=137&limit=10', {
151+
headers: {
152+
'x-client-id': <YOUR_THIRDWEB_CLIENT_ID>
153+
}
154+
});
155+
const transfersInfo = await response.json();
156+
return transfersInfo
157+
} catch (error) {
158+
console.error('Error:', error);
159+
}
160+
};
161+
```
162+
163+
When querying multiple chains, the response includes a `chain_ids` array in the metadata and each item in the data array includes its `chain_id`:
164+
165+
```json
166+
{
167+
"meta": {
168+
"chain_ids": [1, 137],
169+
"total_items": 10,
170+
"limit_per_chain": 5,
171+
"page": 0,
172+
"limit": 10,
173+
"total_pages": 1
174+
},
175+
"data": [
176+
{
177+
"chain_id": 1,
178+
"block_number": 14705663,
179+
// ... other Ethereum event data
180+
},
181+
{
182+
"chain_id": 137,
183+
"block_number": 25631042,
184+
// ... other Polygon event data
185+
}
186+
// ... more events from both chains
187+
]
188+
}
189+
```
190+
191+
Key points about multichain queries:
192+
- Use the base URL `https://insight.thirdweb.com` instead of the chain-specific subdomain
193+
- Add multiple `chain` query parameters (e.g., `chain=1&chain=137`)
194+
- The response includes a `chain_ids` array and `limit_per_chain` in the metadata
195+
- Each item in the data array includes its `chain_id` for identification
196+
197+
For more detailed information and advanced use cases, check out our [Multichain Queries](/insight/multichain-queries) documentation.

0 commit comments

Comments
 (0)