Add llms.txt file to insight docs (#5887)

---
title: "[SDK/Dashboard/Portal] Feature/Fix: Concise title for the changes"
---

If you did not copy the branch name from Linear, paste the issue tag here (format is TEAM-0000):

## Notes for the reviewer
Anything important to call out? Be sure to also clarify these in your comments.

## How to test
Unit tests, playground, etc.

<!-- start pr-codex -->

---

## PR-Codex overview
This PR enhances the `insight` application by adding a new `llms.txt` file link in the sidebar and updating the content in the `agents-and-llms` documentation to provide clearer instructions for using the API with AI agents and LLMs.

### Detailed summary
- Added a new link for `llms.txt` in the sidebar of `sidebar.tsx`.
- Updated the introduction in `page.mdx` to clarify the use of the `llms.txt` file.
- Included a link to the `llms.txt` file in the documentation.
- Expanded API usage instructions and details in `llmstxt/page.mdx`.
- Added sections on rate limiting, pagination, error handling, and authentication methods.
- Provided code examples for API calls and error handling best practices.

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

<!-- end pr-codex -->

Author: AmineAfia

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

@@ -0,0 +1,395 @@
+import { createMetadata } from "@doc";
+
+export const metadata = createMetadata({
+	title: "thirdweb Insight For Agents & LLMs",
+	description:
+		"thirdweb Insight query documentation formatted for use with LLMs and agents",
+	image: {
+		title: "Insight",
+		icon: "insight",
+	},
+});
+
+# Thirdweb Insight
+Insight is a powerful tool that lets you retrieve blockchain data from any EVM chain, enrich it with metadata, and transform it using custom logic. Whether you're building a gaming inventory system, tracking DeFi metrics, or analyzing NFT collections, Insight makes it easy to get the data you need with simple API calls.
+
+## Things to Keep in Mind
+
+- **Rate Limiting**: The API has rate limits based on your authentication tier. Monitor your usage and implement appropriate retry logic.
+
+- **Pagination**: When retrieving large datasets, use pagination parameters (`page` and `limit`) to avoid timeouts and manage response sizes effectively.
+
+- **Chain Selection**: Always verify you're querying the correct chain ID. Using an incorrect chain ID will return a 404 error.
+
+- **Data Freshness**: There may be a slight delay between on-chain events and their availability in the API due to block confirmation times.
+
+- **Error Handling**: Implement proper error handling for both HTTP errors (400/500) and network issues. Consider implementing retries for transient failures.
+
+- **Query Optimization**: 
+  - Use specific filters to reduce response size and improve performance
+  - Avoid overly broad date ranges when possible
+  - Consider using aggregations for large datasets
+
+- **Authentication**: Keep your authentication credentials secure and don't expose them in client-side code.
+
+- **Response Processing**: Some numeric values are returned as strings to maintain precision. Convert them appropriately in your application.
+
+
+## API URL
+
+```typescript
+const baseUrl = `https://${chainId}.insight.thirdweb.com`;
+```
+
+## Authentication
+
+The API supports three authentication methods:
+
+```typescript
+// 1. Header Authentication
+const headers = {
+	"x-client-id": "YOUR_CLIENT_ID", // thirdweb Client ID
+};
+
+// 2. Query Parameter
+const url = `https://${chainId}.insight.thirdweb.com/v1/events?clientId=YOUR_CLIENT_ID`;
+
+// 3. Bearer Token
+const headers = {
+	Authorization: "Bearer YOUR_JWT_TOKEN",
+};
+
+// Example using fetch with header auth
+async function getEvents() {
+	const response = await fetch(`https://${chainId}.insight.thirdweb.com/v1/events`, {
+		headers: {
+			"x-client-id": "YOUR_CLIENT_ID",
+		},
+	});
+	return await response.json();
+}
+```
+
+## Core Concepts
+
+### Chain IDs
+
+The API supports the following chain IDs (with 1 as default):
+
+```typescript
+type ChainId = string; // Chain ID of the network you want to query
+
+// Example: Using a specific chain
+const chainId = "<chainId>"; // Replace with your desired chain ID
+const baseUrl = `https://${chainId}.insight.thirdweb.com`;
+```
+
+### Base Response Structure
+
+```typescript
+interface BaseResponse<T> {
+  data: T[];
+  meta: {
+    chain_id: number;     // Required
+    page: number;         // Required
+    limit: number;        // Required
+    total_items: number;  // Required
+    total_pages: number;  // Required
+    address?: string;     // Optional
+    signature?: string;   // Optional
+  }
+}
+
+// Example response from getting events
+{
+  "data": [
+    {
+      "chain_id": 1,
+      "block_number": "17859301",
+      "transaction_hash": "0x123...",
+      "address": "0x456...",
+      "data": "0x789...",
+      "topics": ["0xabc..."]
+    }
+  ],
+  "meta": {
+    "chain_id": 1,
+    "page": 0,
+    "limit": 20,
+    "total_items": 150,
+    "total_pages": 8
+  }
+}
+```
+
+## API Examples
+
+### Events API
+
+```typescript
+// 1. Get All Events
+async function getAllEvents() {
+	const response = await fetch(`https://${chainId}.insight.thirdweb.com/v1/events`, {
+		headers: { "x-client-id": "YOUR_CLIENT_ID" },
+	});
+	return await response.json();
+}
+
+// 2. Get Contract Events with Filtering
+async function getContractEvents(contractAddress: string) {
+	const params = new URLSearchParams({
+		filter_block_number_gte: "17000000",
+		sort_by: "block_timestamp",
+		sort_order: "desc",
+		limit: "50",
+	});
+
+	const url = `https://${chainId}.insight.thirdweb.com/v1/events/${contractAddress}?${params}`;
+	const response = await fetch(url, {
+		headers: { "x-client-id": "YOUR_CLIENT_ID" },
+	});
+	return await response.json();
+}
+```
+
+### Token Balance API
+
+```typescript
+// 1. Get ERC20 Balances
+async function getERC20Balances(ownerAddress: string) {
+	const response = await fetch(
+		`https://${chainId}.insight.thirdweb.com/v1/tokens/erc20/${ownerAddress}`,
+		{ headers: { "x-client-id": "YOUR_CLIENT_ID" } },
+	);
+	const data = await response.json();
+	// Example response:
+	// {
+	//   "data": [
+	//     {
+	//       "tokenAddress": "0x123...",
+	//       "balance": "1000000000000000000"
+	//     }
+	//   ]
+	// }
+	return data;
+}
+
+// 2. Get NFT Balances
+async function getNFTBalances(ownerAddress: string) {
+	const response = await fetch(
+		`https://${chainId}.insight.thirdweb.com/v1/tokens/erc721/${ownerAddress}`,
+		{ headers: { "x-client-id": "YOUR_CLIENT_ID" } },
+	);
+	const data = await response.json();
+	// Example response:
+	// {
+	//   "data": [
+	//     {
+	//       "collectionAddress": "0x456...",
+	//       "tokenId": "1",
+	//       "balance": "1"
+	//     }
+	//   ]
+	// }
+	return data;
+}
+```
+
+### Using Filters
+
+```typescript
+// Example: Get events with complex filtering
+async function getFilteredEvents() {
+	const params = new URLSearchParams({
+		// Block filters
+		filter_block_number_gte: "17000000",
+		filter_block_number_lte: "17859301",
+
+		// Time filters
+		filter_block_timestamp_gte: "1715222400",
+
+		// Transaction filters
+		filter_from_address: "0x123...",
+		filter_value_gte: "1000000000000000000", // 1 ETH
+
+		// Pagination
+		page: "0",
+		limit: "20",
+
+		// Sorting
+		sort_by: "block_timestamp",
+		sort_order: "desc",
+	});
+
+	const response = await fetch(
+		`https://${chainId}.insight.thirdweb.com/v1/events?${params}`,
+		{ headers: { "x-client-id": "YOUR_CLIENT_ID" } },
+	);
+	return await response.json();
+}
+```
+
+### Error Handling
+
+```typescript
+async function safeApiCall() {
+	try {
+		const response = await fetch(`https://${chainId}.insight.thirdweb.com/v1/events`, {
+			headers: { "x-client-id": "YOUR_CLIENT_ID" },
+		});
+
+		if (!response.ok) {
+			const errorData = await response.json();
+			// Example error response:
+			// { "error": "Invalid client ID" }
+			throw new Error(errorData.error);
+		}
+
+		return await response.json();
+	} catch (error) {
+		console.error("API Error:", error.message);
+		throw error;
+	}
+}
+```
+
+## API Reference
+
+### Events API
+
+1. **Get All Events**
+
+```typescript
+GET /v1/events
+```
+
+2. **Get Contract Events**
+
+```typescript
+GET /v1/events/:contractAddress
+```
+
+3. **Get Specific Event Type**
+
+```typescript
+GET /v1/events/:contractAddress/:signature
+```
+
+### Transactions API
+
+1. **Get All Transactions**
+
+```typescript
+GET /v1/transactions
+GET /v1/transactions;
+```
+
+2. **Get Contract Transactions**
+
+```typescript
+GET /v1/transactions/:contractAddress
+```
+
+3. **Get Specific Transaction Type**
+
+```typescript
+GET /v1/transactions/:contractAddress/:signature
+```
+
+### Token Balance API
+
+1. **ERC20 Balances**
+
+```typescript
+GET /v1/tokens/erc20/:ownerAddress
+
+interface ERC20Response {
+  data: {
+    tokenAddress: string;  // Required
+    balance: string;      // Required
+  }[];
+}
+```
+
+2. **ERC721 & ERC1155 Balances**
+
+```typescript
+GET /v1/tokens/erc721/:ownerAddress
+GET /v1/tokens/erc1155/:ownerAddress
+
+interface TokenBalance {
+  data: {
+    collectionAddress: string;  // Required
+    tokenId: string;           // Required
+    balance: string;           // Required
+  }[];
+}
+```
+
+## Query Parameters
+
+### Common Parameters
+
+```typescript
+interface CommonQueryParams {
+	page?: number; // Default: 0
+	limit?: number; // Default: 20, must be > 0
+	sort_by?: "block_number" | "block_timestamp" | "transaction_index";
+	sort_order?: "asc" | "desc";
+	group_by?: string;
+	aggregate?: string[];
+}
+```
+
+### Filter Types
+
+1. **Block Filters**
+
+```typescript
+interface BlockFilters {
+	filter_block_number?: number; // Example: 1000000
+	filter_block_number_gte?: number; // Example: 1000000
+	filter_block_number_gt?: number; // Example: 1000000
+	filter_block_number_lte?: number; // Example: 1000000
+	filter_block_number_lt?: number; // Example: 1000000
+	filter_block_hash?: string; // Example: "0x3a1fba5..."
+}
+```
+
+2. **Time Filters**
+
+```typescript
+interface TimeFilters {
+	filter_block_timestamp?: number; // Example: 1715222400
+	filter_block_timestamp_gte?: number; // Example: 1715222400
+	filter_block_timestamp_gt?: number; // Example: 1715222400
+	filter_block_timestamp_lte?: number; // Example: 1715222400
+	filter_block_timestamp_lt?: number; // Example: 1715222400
+}
+```
+
+3. **Transaction Filters**
+
+```typescript
+interface TransactionFilters {
+	filter_transaction_index?: number;
+	filter_transaction_hash?: string;
+	filter_from_address?: string;
+	filter_value?: number;
+	filter_gas_price?: number;
+	filter_gas?: number;
+	// Additional gte, gt, lte, lt variants for numeric fields
+}
+```
+
+## Error Handling
+
+All endpoints return standard error responses for 400 and 500 status codes:
+
+```typescript
+// 400 Bad Request
+// 500 Internal Server Error
+interface ErrorResponse {
+	error: string; // Required
+}
+```