From fc6606022d8ca9aca15d1e519fe768b2c925df14 Mon Sep 17 00:00:00 2001 From: AmineAfia Date: Fri, 3 Jan 2025 22:51:29 +0000 Subject: [PATCH] Add docs agents and llms docs for insight (#5881) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 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. --- ## PR-Codex overview This PR introduces documentation for the `thirdweb Insight` API, targeting agents and LLMs. It includes usage instructions, core concepts, API examples, query parameters, and error handling. ### Detailed summary - Added metadata for the page with title and description. - Provided API usage instructions for agents and LLMs. - Explained authentication methods (header, query parameter, bearer token). - Detailed core concepts including chain IDs and base response structure. - Included examples for Events API, Token Balance API, and filtering. - Documented API reference for Events and Transactions. - Listed common query parameters and filter types. - Explained error handling for API responses. > ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}` --- .../src/app/insight/agents-and-llms/page.mdx | 411 ++++++++++++++++++ 1 file changed, 411 insertions(+) create mode 100644 apps/portal/src/app/insight/agents-and-llms/page.mdx 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 { + 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