diff --git a/apps/portal/src/app/insight/agents-and-llms/page.mdx b/apps/portal/src/app/insight/agents-and-llms/page.mdx
new file mode 100644
index 00000000000..d72b904c726
--- /dev/null
+++ b/apps/portal/src/app/insight/agents-and-llms/page.mdx
@@ -0,0 +1,411 @@
+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",
+	},
+});
+
+# For Agents & LLMs
+
+The schema below can be copied and pasted into the AI assistant of your choice. Feed this to your assistant, then ask your assistant to construct Insight queries on your behalf, asking it for certain onchain information.
+
+````markdown
+# ATTENTION LLMs - API Usage Instructions
+
+## API URL
+
+https://{chain-id}.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://1.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://1.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 =
+	| "1"
+	| "2039"
+	| "30"
+	| "98865"
+	| "42793"
+	| "1952959480"
+	| "98864"
+	| "466"
+	| "37714555429"
+	| "8008135"
+	| "55244"
+	| "42019"
+	| "8453"
+	| "480"
+	| "84532"
+	| "888888888"
+	| "43113"
+	| "19934"
+	| "7897"
+	| "2040"
+	| "37111"
+	| "33139"
+	| "80002"
+	| "8333"
+	| "660279"
+	| "42161"
+	| "11155111"
+	| "421614"
+	| "994873017"
+	| "42026"
+	| "43114"
+	| "1946"
+	| "31"
+	| "41455"
+	| "1993"
+	| "98985";
+
+// Example: Using a specific chain
+const chainId = "1"; // Ethereum Mainnet
+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://1.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://1.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://1.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://1.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://1.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://1.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;
+```
+
+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
+}
+```
+````
\ No newline at end of file