Multichain Queries

Insight now supports querying multiple blockchain networks in a single API call. This powerful feature allows you to retrieve and analyze data across different chains without making separate requests for each network.

• Efficiency: Reduce the number of API calls needed to fetch data from multiple chains
• Simplicity: Consolidate cross-chain data in a single request and response
• Performance: Minimize latency by avoiding sequential requests to different chains
• Consistency: Process data from different networks using a unified format

Instead of using the chain-specific subdomain approach, multichain queries use the base URL with multiple chain query parameters:

// Traditional single-chain query (using subdomain)
const singleChainUrl = `https://1.insight.thirdweb.com/v1/events`;
 
// Multichain query (using base URL with chain parameters)
const multiChainUrl = `https://insight.thirdweb.com/v1/events?chain=1&chain=137`;

Authentication works the same way as with single-chain queries:

// Using client ID in header
const headers = {
  "x-client-id": "{{clientId}}",
};
 
// Or as a query parameter
const url = `https://insight.thirdweb.com/v1/events?chain=1&chain=137&clientId={{clientId}}`;

Responses for multichain queries include additional metadata to help you identify which data belongs to which chain:

{
  "meta": {
    "chain_ids": [1, 137],     // List of queried chain IDs
    "total_items": 113,        // Total count across all chains
    "limit_per_chain": 100,    // Per-chain limit derived from the request
    "page": 0,
    "limit": 200,
    "total_pages": 1
  },
  "data": [
    {
      "chain_id": 1,           // Each item includes its chain ID
      "block_number": "17859301",
      "transaction_hash": "0x123...",
      // ... other fields
    },
    {
      "chain_id": 137,
      "block_number": "48392021",
      // ... other fields
    }
  ]
}

Key differences in the response format:

• The meta object includes a chain_ids array listing all queried chains
• A limit_per_chain field indicates how many items were requested per chain
• Each item in the data array includes a chain_id field to identify its network

When using multichain queries, the limit parameter applies to each chain individually:

// This will return up to 20 items from each chain (potentially 40 total items)
const url = `https://insight.thirdweb.com/v1/events?chain=1&chain=137&limit=20`;

The limit_per_chain in the response metadata shows how many items were requested per chain, while the overall limit represents the maximum total items across all chains.

const getMultichainEvents = async () => {
  try {
    // Query events on Ethereum (1) and Polygon (137)
    const response = await fetch(
      "https://insight.thirdweb.com/v1/events?chain=1&chain=137&limit=10",
      {
        headers: {
          "x-client-id": "<YOUR_THIRDWEB_CLIENT_ID>",
        },
      },
    );
    return await response.json();
  } catch (error) {
    console.error("Error:", error);
  }
};

const getMultichainTokenBalances = async (ownerAddress) => {
  try {
    // Get ERC-20 balances on Ethereum, Polygon, and Arbitrum
    const response = await fetch(
      `https://insight.thirdweb.com/v1/tokens/erc20/${ownerAddress}?chain=1&chain=137&chain=42161`,
      {
        headers: {
          "x-client-id": "<YOUR_THIRDWEB_CLIENT_ID>",
        },
      },
    );
    return await response.json();
  } catch (error) {
    console.error("Error:", error);
  }
};

const getMultichainNFTs = async (ownerAddress) => {
  try {
    // Get NFTs on Ethereum and Base
    const response = await fetch(
      `https://insight.thirdweb.com/v1/tokens/erc721/${ownerAddress}?chain=1&chain=8453`,
      {
        headers: {
          "x-client-id": "<YOUR_THIRDWEB_CLIENT_ID>",
        },
      },
    );
    return await response.json();
  } catch (error) {
    console.error("Error:", error);
  }
};

All Insight blueprints support multichain queries:

• Events Blueprint: /v1/events - Returns events from specified chains
• Transactions Blueprint: /v1/transactions - Provides transactions from multiple chains
• Tokens Blueprint:
  • /v1/tokens/erc20/:ownerAddress - Consolidates ERC-20 token balances across chains
  • /v1/tokens/erc721/:ownerAddress - Consolidates NFT holdings across chains
  • /v1/tokens/erc1155/:ownerAddress - Consolidates ERC-1155 token balances across chains

• Limit Chain Count: While you can query multiple chains, it's best to limit the number of chains in a single request to avoid timeouts.

• Use Appropriate Limits: Set reasonable limit values to control response size and processing time.

• Handle Chain-Specific Errors: Some chains might return errors while others succeed. Your code should handle partial successes.

• Process Data by Chain: When analyzing the response, group or filter data by chain_id for chain-specific analysis.

• Consider Rate Limits: Multichain queries count against your rate limits for each chain queried.

Track a user's assets across multiple networks to provide a comprehensive view of their holdings:

const getPortfolio = async (address) => {
  // Get ERC-20 tokens across major chains
  const erc20Response = await fetch(
    `https://insight.thirdweb.com/v1/tokens/erc20/${address}?chain=1&chain=137&chain=42161&chain=10&chain=8453`,
    { headers: { "x-client-id": "<YOUR_CLIENT_ID>" } },
  );
 
  // Get NFTs across the same chains
  const nftResponse = await fetch(
    `https://insight.thirdweb.com/v1/tokens/erc721/${address}?chain=1&chain=137&chain=42161&chain=10&chain=8453`,
    { headers: { "x-client-id": "<YOUR_CLIENT_ID>" } },
  );
 
  return {
    tokens: await erc20Response.json(),
    nfts: await nftResponse.json(),
  };
};

Monitor transactions or events across multiple chains for a specific address:

const getRecentActivity = async (address) => {
  const response = await fetch(
    `https://insight.thirdweb.com/v1/transactions?filter_from_address=${address}&chain=1&chain=137&chain=42161&sort_by=block_timestamp&sort_order=desc&limit=10`,
    { headers: { "x-client-id": "<YOUR_CLIENT_ID>" } },
  );
 
  return await response.json();
};

Analyze protocol activity across different deployments on multiple chains:

const getProtocolActivity = async (protocolAddresses) => {
  // protocolAddresses = { 1: "0x123...", 137: "0x456...", 42161: "0x789..." }
 
  const queryParams = Object.entries(protocolAddresses)
    .map(
      ([chainId, address]) =>
        `chain=${chainId}&filter_address=${address}`,
    )
    .join("&");
 
  const response = await fetch(
    `https://insight.thirdweb.com/v1/events?${queryParams}&limit=50`,
    { headers: { "x-client-id": "<YOUR_CLIENT_ID>" } },
  );
 
  return await response.json();
};