const fs = require('fs'); const path = require('path'); const matter = require('gray-matter'); // Paths const apiReferenceDir = path.resolve(__dirname, '../api-reference/foundational-api'); const streamingApiDir = path.resolve(__dirname, '../api-reference/streaming-api'); const chainsDir = path.resolve(__dirname, '../chains'); const chainsOverviewPath = path.resolve(__dirname, '../chains/overview.mdx'); const datoApiEndpointsPath = path.resolve(__dirname, '../data/dato-apiendpoints.json'); const datoChainsPath = path.resolve(__dirname, '../data/dato-chains.json'); const openapiPath = path.resolve(__dirname, '../api-reference/openapi.json'); const graphqlEndpointsPath = path.resolve(__dirname, '../goldrush-streaming-api/graphql-endpoints.mdx'); const sdkMethodsMappingPath = path.resolve(__dirname, './sdk-methods-mapping.json'); const llmsTxtPath = path.resolve(__dirname, '../llms.txt'); const llmsFullTxtPath = path.resolve(__dirname, '../llms-full.txt'); // Load DatoCMS data const datoApiData = JSON.parse(fs.readFileSync(datoApiEndpointsPath, 'utf8')); const datoChainsData = JSON.parse(fs.readFileSync(datoChainsPath, 'utf8')); // Filter for only published, non-phantom endpoints const apiEndpoints = datoApiData.data.allApiendpoints.filter(e => e._status === 'published' && !e.phantom ); const chains = datoChainsData.data.allBlockchains; // Parse OpenAPI spec for REST endpoint operation IDs const openapiSpec = JSON.parse(fs.readFileSync(openapiPath, 'utf8')); // Parse GraphQL endpoints for subscription/query field names const graphqlEndpointsContent = fs.readFileSync(graphqlEndpointsPath, 'utf8'); // Load SDK methods mapping const sdkMethodsMapping = JSON.parse(fs.readFileSync(sdkMethodsMappingPath, 'utf8')); /** * Extract support level definitions from chains/overview.mdx */ function extractSupportLevelDefinitions() { if (!fs.existsSync(chainsOverviewPath)) { return {}; } const overviewContent = fs.readFileSync(chainsOverviewPath, 'utf8'); const definitions = {}; // Extract Foundational Chains definition const foundationalMatch = overviewContent.match(/### Foundational Chains\s*\n(.+?)(?=\n\n|\n###)/s); if (foundationalMatch) { definitions.foundational = foundationalMatch[1].trim(); } // Extract Frontier Chains definition const frontierMatch = overviewContent.match(/### Frontier Chains\s*\n(.+?)(?=\n\n|\n###)/s); if (frontierMatch) { definitions.frontier = frontierMatch[1].trim(); } // Extract Community Chains definition const communityMatch = overviewContent.match(/### Community Chains\s*\n(.+?)(?=\n\n|\n###)/s); if (communityMatch) { definitions.community = communityMatch[1].trim(); } // Extract Archived Chains definition const archivedMatch = overviewContent.match(/### Archived Chains\s*\n(.+?)(?=\n\n|\n###)/s); if (archivedMatch) { definitions.archived = archivedMatch[1].trim(); } return definitions; } /** * Build a lookup map from OpenAPI spec: path+method -> operationId * Returns a map like: { "GET /v1/{chainName}/address/{walletAddress}/balances_v2/" -> "getTokenBalancesForWalletAddress" } */ function buildOpenapiLookup() { const lookup = {}; for (const [pathTemplate, pathItem] of Object.entries(openapiSpec.paths || {})) { for (const [method, operation] of Object.entries(pathItem)) { if (operation.operationId) { const key = `${method.toUpperCase()} ${pathTemplate}`; lookup[key] = { operationId: operation.operationId, method: method.toUpperCase(), path: pathTemplate }; } } } return lookup; } /** * Parse GraphQL endpoints table from graphql-endpoints.mdx * Returns array like: [{ title: "New DEX Pairs Stream", type: "subscription", field: "newPairs" }, ...] */ function parseGraphqlEndpoints() { const endpoints = []; // Match table rows: |Title|`type`|```type { field { ... } }```| const tableRegex = /\|([^|]+)\|`(subscription|query)`\|```(?:subscription|query)\s*\{\s*(\w+)/g; let match; while ((match = tableRegex.exec(graphqlEndpointsContent)) !== null) { const title = match[1].trim(); const type = match[2].trim(); const field = match[3].trim(); endpoints.push({ title, type: `graphql-${type}`, field }); } return endpoints; } const openapiLookup = buildOpenapiLookup(); const graphqlEndpoints = parseGraphqlEndpoints(); /** * Get expected response schema for an endpoint based on its category */ function getResponseSchema(endpoint, apiType) { if (apiType === 'REST') { const category = endpoint.grouping || endpoint.category; if (category === 'balances') { return { description: 'Returns token balances with pricing data', schema: `{ "data": { "address": "0x...", "updated_at": "2024-01-20T...", "next_update_at": "2024-01-20T...", "quote_currency": "USD", "chain_id": 1, "chain_name": "eth-mainnet", "items": [ { "contract_decimals": 18, "contract_name": "Token Name", "contract_ticker_symbol": "TKN", "contract_address": "0x...", "balance": "1500000000000000000", "quote_rate": 2500.50, "quote": 3750.75, "pretty_quote": "$3,750.75" } ] }, "error": false, "error_message": null, "error_code": null }` }; } else if (category === 'transactions') { return { description: 'Returns transaction list with decoded logs', schema: `{ "data": { "address": "0x...", "updated_at": "2024-01-20T...", "items": [ { "tx_hash": "0x...", "successful": true, "from_address": "0x...", "to_address": "0x...", "value": "0", "block_signed_at": "2024-01-20T...", "gas_spent": 21000, "gas_price": 50000000000, "fees_paid": "1050000000000000" } ], "pagination": { "has_more": true, "page_number": 0, "page_size": 100 } }, "error": false }` }; } // Default REST response return { description: 'Standard REST API response format', schema: `{ "data": { "items": [...], "pagination": { "has_more": boolean, "page_number": 0, "page_size": 100 } }, "error": false, "error_message": null }` }; } else if (apiType === 'graphql-subscription' || apiType === 'graphql-query') { return { description: 'GraphQL subscription delivers real-time updates via WebSocket', schema: `{ "data": { "${endpoint.slug}": [ { "chain_name": "BASE_MAINNET", "timestamp": "2025-01-20T...", ... } ] } }` }; } return null; } /** * Find all MDX files recursively in a directory */ function findMdxFiles(dir, fileList = []) { if (!fs.existsSync(dir)) { return fileList; } const files = fs.readdirSync(dir); files.forEach(file => { const filePath = path.join(dir, file); const stat = fs.statSync(filePath); if (stat.isDirectory()) { findMdxFiles(filePath, fileList); } else if (file.endsWith('.mdx')) { fileList.push(filePath); } }); return fileList; } /** * Extract slug from file path for matching with DatoCMS */ function getSlugFromPath(filePath) { const basename = path.basename(filePath, '.mdx'); return basename; } /** * Determine API type based on endpoint data * - REST: Foundational API endpoints (HTTP) * - graphql-subscription: Streaming API subscriptions (real-time WebSocket push) * - graphql-query: Streaming API queries (one-time GraphQL fetch) */ function getApiType(endpoint) { if (endpoint.grouping === 'streaming') { // Subscriptions: Real-time streaming endpoints (suffix: -stream) if (endpoint.slug.includes('-stream')) { return 'graphql-subscription'; } // Queries: One-time fetch endpoints (suffix: -query or other patterns) return 'graphql-query'; } // Default: REST API for Foundational endpoints return 'REST'; } /** * Format credit cost with appropriate unit context * - fixed model: per call * - linear model with item unit: per item */ function getCreditCostDisplay(endpoint) { if (endpoint.creditrate === null || endpoint.creditrate === undefined) { return null; } const cost = endpoint.creditrate; const model = endpoint.creditratemodel; const unit = endpoint.creditrateunit; // Determine the appropriate unit description if (model === 'fixed') { return `${cost} per call`; } else if (model === 'linear' && unit === 'item') { return `${cost} per item`; } else if (model === 'linear') { return `${cost} per item`; } // Default: just show the cost return `${cost}`; } /** * Get chains list for endpoint */ function getChainsList(endpoint) { if (endpoint.allChainsSupported) { return 'all'; } if (endpoint.supportedchains && endpoint.supportedchains.length > 0) { return endpoint.supportedchains.map(c => c.chainname); } return []; } /** * Find related endpoints (same grouping) */ function getRelatedEndpoints(endpoint, allEndpoints) { if (!endpoint.grouping) return []; return allEndpoints .filter(e => e.grouping === endpoint.grouping && e.slug !== endpoint.slug && e._status === 'published' && !e.phantom ) .slice(0, 3) .map(e => e.slug); } /** * Extract operation identity for REST endpoints from OpenAPI spec */ function getRestOperationIdentity(frontmatter) { if (!frontmatter.openapi) return null; // OpenAPI field format: "GET /v1/{chainName}/address/{walletAddress}/balances_v2/" const openapiValue = frontmatter.openapi.trim(); const openapiData = openapiLookup[openapiValue]; if (!openapiData) { return null; } const identity = { operation_id: openapiData.operationId, method: openapiData.method, path: openapiData.path }; // Add SDK method information if available const sdkMethod = sdkMethodsMapping[openapiData.operationId]; if (sdkMethod) { identity.sdk_service = sdkMethod.service; identity.sdk_method = sdkMethod.method; } return identity; } /** * Extract operation identity for GraphQL endpoints from graphql-endpoints.mdx */ function getGraphqlOperationIdentity(title, apiType) { // Find matching GraphQL endpoint by title const graphqlEndpoint = graphqlEndpoints.find(e => { const normalizedTitle = title.toLowerCase().replace(/\s+/g, ' ').trim(); const normalizedEndpointTitle = e.title.toLowerCase().replace(/\s+/g, ' ').trim(); return normalizedEndpointTitle === normalizedTitle; }); if (!graphqlEndpoint) { return null; } // Map GraphQL fields to StreamingService methods const streamingMethodMap = { 'ohlcvCandlesForPair': 'subscribeToOHLCVPairs', 'ohlcvCandlesForToken': 'subscribeToOHLCVTokens', 'walletTxs': 'subscribeToWalletActivity', 'newPairs': 'subscribeToNewPairs', 'updatePairs': 'subscribeToUpdatePairs' }; const identity = { operation_id: graphqlEndpoint.field, type: graphqlEndpoint.type, field: graphqlEndpoint.field }; // Add SDK method for streaming subscriptions if (graphqlEndpoint.type === 'graphql-subscription') { const sdkMethod = streamingMethodMap[graphqlEndpoint.field]; if (sdkMethod) { identity.sdk_service = 'StreamingService'; identity.sdk_method = sdkMethod; } } return identity; } /** * Parse MDX file and enrich with DatoCMS data */ function parseAndEnrichEndpoint(filePath, apiEndpoints) { const fileContent = fs.readFileSync(filePath, 'utf8'); const { data, content } = matter(fileContent); const slug = getSlugFromPath(filePath); // Find matching DatoCMS record const datoRecord = apiEndpoints.find(e => e.slug === slug || e.slug === data.slug || e.title === data.title ); if (!datoRecord) { console.warn(`⚠️ No DatoCMS record found for: ${slug}`); return { path: filePath, frontmatter: data, content: content.trim(), datoRecord: null }; } // Determine API type const apiType = getApiType(datoRecord); // Extract operation identity based on API type let operationIdentity = null; if (apiType === 'REST') { operationIdentity = getRestOperationIdentity(data); } else if (apiType === 'graphql-subscription' || apiType === 'graphql-query') { operationIdentity = getGraphqlOperationIdentity(datoRecord.title || data.title, apiType); } // Enrich frontmatter with DatoCMS data const enrichedFrontmatter = { ...data, title: datoRecord.title || data.title, category: datoRecord.grouping || data.category, api_type: apiType, operation_identity: operationIdentity, endpoint_role: datoRecord.endpointrole || null, credit_cost: getCreditCostDisplay(datoRecord), chains: getChainsList(datoRecord), use_cases: datoRecord.keyusecases || data.use_cases || [], beta: datoRecord.beta || false, related: getRelatedEndpoints(datoRecord, apiEndpoints) }; return { path: filePath, frontmatter: enrichedFrontmatter, content: content.trim(), datoRecord }; } /** * Parse chain MDX and enrich with DatoCMS data */ function parseAndEnrichChain(filePath, chains) { const fileContent = fs.readFileSync(filePath, 'utf8'); const { data, content } = matter(fileContent); const slug = getSlugFromPath(filePath); // Map MDX file slugs to their DatoCMS chainname const chainNameMap = { 'ethereum': 'eth-mainnet', 'polygon': 'matic-mainnet', 'base': 'base-mainnet', 'arbitrum': 'arbitrum-mainnet', 'arbitrum-nova': 'arbitrum-nova-mainnet', 'optimism': 'optimism-mainnet', 'avalanche-c-chain': 'avalanche-mainnet', 'bitcoin': 'btc-mainnet', 'bnb-smart-chain-bsc': 'bsc-mainnet', 'axie-ronin': 'axie-mainnet', 'berachain': 'berachain-mainnet', 'arc': 'arc-testnet', 'gnosis': 'gnosis-mainnet', 'fantom': 'fantom-mainnet', 'moonbeam': 'moonbeam-mainnet', 'moonriver': 'moonbeam-moonriver', 'canto': 'canto-mainnet', 'celo': 'celo-mainnet', 'harmony': 'harmony-mainnet', 'cronos': 'cronos-mainnet', 'cronos-zkevm': 'cronos-zkevm-mainnet', 'oasis': 'emerald-paratime-mainnet', 'oasis-sapphire': 'oasis-sapphire-mainnet', 'solana': 'solana-mainnet', 'sonic': 'sonic-mainnet', 'covalent': 'covalent-internal-network-v1', 'blast': 'blast-mainnet', 'linea': 'linea-mainnet', 'mantle': 'mantle-mainnet', 'scroll': 'scroll-mainnet', 'zksync-era': 'zksync-mainnet', 'opbnb': 'bnb-opbnb-mainnet', 'manta-pacific': 'manta-sepolia-testnet', 'redstone': 'redstone-mainnet', 'taiko': 'taiko-mainnet', 'sei': 'sei-mainnet', 'zetachain': 'zetachain-mainnet', 'viction': 'viction-mainnet', 'ink': 'ink-mainnet', 'world-chain': 'world-mainnet', 'unichain': 'unichain-mainnet', 'lisk': 'lisk-mainnet', 'loot-chain': 'loot-mainnet', 'plasma': 'plasma-mainnet', 'sx-network': 'sx-mainnet', 'apechain': 'apechain-mainnet', 'hyperevm': 'hyperevm-mainnet', 'hypercore': 'hypercore-mainnet', 'monad': 'monad-mainnet', 'megaeth': 'megaeth-mainnet', 'lens': 'lens-mainnet', 'adi-chain': 'adi-mainnet', 'adi': 'adi-testnet' }; const chainname = chainNameMap[slug] || data.chain_name || slug; // Find matching DatoCMS record const datoRecord = chains.find(c => c.chainname === chainname); if (!datoRecord) { console.warn(`⚠️ No DatoCMS record found for chain: ${chainname}`); return { path: filePath, frontmatter: data, content: content.trim(), datoRecord: null }; } // Enrich frontmatter with DatoCMS data const enrichedFrontmatter = { ...data, title: datoRecord.displayname || data.title, chain_name: datoRecord.chainname, chain_id: datoRecord.chainid, support_level: datoRecord.support, network_type: datoRecord.testnet ? 'testnet' : 'mainnet', apis: { foundational: datoRecord.foundationalapi || false, streaming: datoRecord.streamingapi || false }, capabilities: data.capabilities || {} }; return { path: filePath, frontmatter: enrichedFrontmatter, content: content.trim(), datoRecord }; } /** * Strip MDX/JSX components and convert to plain Markdown */ function stripMdxToPlainMarkdown(content) { let processed = content; // Convert components in order processed = convertCardComponents(processed); processed = convertAccordionComponents(processed); processed = convertInfoComponents(processed); processed = convertCodeGroupComponents(processed); processed = processed.replace(/]*>([\s\S]*?)<\/Columns>/g, '$1'); processed = convertHtmlTables(processed); processed = cleanInlineStyles(processed); processed = convertHtmlTags(processed); processed = processed.replace(/<[^>]+>/g, ''); processed = processed.replace(/\n{3,}/g, '\n\n'); return processed.trim(); } function convertCardComponents(content) { // content → ### X\n\ncontent\n\n[Read more](Y) return content .replace(/]*title="([^"]*)"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/Card>/g, (match, title, href, cardContent) => `\n### ${title}\n\n${cardContent.trim()}\n\n[Read more](${href})\n`) .replace(/]*>([\s\S]*?)<\/CardGroup>/g, '$1') .replace(/]*title="([^"]*)"[^>]*>([\s\S]*?)<\/Card>/g, (match, title, cardContent) => `\n**${title}:** ${cardContent.trim()}\n`); } function convertAccordionComponents(content) { // content → ### X\n\ncontent return content.replace(/]*title="([^"]*)"[^>]*>([\s\S]*?)<\/Accordion>/g, (match, title, accordionContent) => `\n### ${title}\n\n${accordionContent.trim()}\n`); } function convertInfoComponents(content) { // content → > **Note:** content return content.replace(/]*>([\s\S]*?)<\/Info>/gi, (match, infoContent) => `\n> **Note:** ${infoContent.trim()}\n`); } function convertCodeGroupComponents(content) { // ...code blocks... → unwrap, keep code blocks return content.replace(/]*>([\s\S]*?)<\/CodeGroup>/g, '$1'); } function convertHtmlTables(content) { // Convert HTML tables to Markdown tables return content.replace( /]*>[\s\S]*?]*>([\s\S]*?)<\/thead>[\s\S]*?]*>([\s\S]*?)<\/tbody>[\s\S]*?<\/table>/g, (match, thead, tbody) => { // Extract headers const headers = []; thead.replace(/]*>([\s\S]*?)<\/th>/g, (m, content) => { headers.push(content.replace(/<[^>]+>/g, '').trim()); }); // Extract rows const rows = []; const trMatches = tbody.match(/]*>[\s\S]*?<\/tr>/g) || []; trMatches.forEach(tr => { const cells = []; tr.replace(/]*>([\s\S]*?)<\/td>/g, (m, content) => { cells.push(content.replace(/<[^>]+>/g, '').trim()); }); if (cells.length > 0) rows.push(cells); }); // Build Markdown table if (headers.length === 0) return ''; let table = '\n| ' + headers.join(' | ') + ' |\n'; table += '| ' + headers.map(() => '---').join(' | ') + ' |\n'; rows.forEach(row => { table += '| ' + row.join(' | ') + ' |\n'; }); return table + '\n'; } ); } function cleanInlineStyles(content) { // Remove JSX style={{...}} and className return content .replace(/style=\{\{[^}]*\}\}/g, '') .replace(/className="[^"]*"/g, '') .replace(/className='[^']*'/g, ''); } function convertHtmlTags(content) { // Convert common HTML tags to Markdown return content .replace(/]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/g, '[$2]($1)') .replace(/(.*?)<\/b>/g, '**$1**') .replace(/(.*?)<\/strong>/g, '**$1**') .replace(/(.*?)<\/code>/g, '`$1`') .replace(//g, '\n') .replace(/(.*?)<\/em>/g, '*$1*') .replace(/(.*?)<\/i>/g, '*$1*'); } /** * Generate Common Errors & Troubleshooting section */ function generateTroubleshootingSection() { const lines = []; lines.push('This section covers common errors for frequently used endpoints.'); lines.push(''); const troubleshooting = [ { title: 'Get token balances for address', errors: [ { error: '400 Bad Request - Invalid address', solution: 'Ensure address starts with 0x and is 40 hex characters', example: 'Valid: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`' }, { error: '404 Not Found - Chain not found', solution: 'Use exact chain name (case-sensitive): `eth-mainnet` not "ethereum"', example: 'Correct: `eth-mainnet` | Wrong: `ethereum`' }, { error: 'Response contains spam tokens', solution: 'Filter by `is_spam: false` or use minimum quote threshold', example: 'Filter: `items.filter(t => !t.is_spam && parseFloat(t.quote) > 0.01)`' } ] }, { title: 'Get paginated transactions for address (v3)', errors: [ { error: '400 Bad Request - Invalid pagination', solution: 'Page numbers are 0-indexed. First page is 0, not 1.', example: 'First: `page-number=0` | Second: `page-number=1`' }, { error: 'Incomplete transaction history', solution: 'Check `pagination.has_more` field. Continue until `has_more: false`.', example: 'Loop: `while (response.data.pagination.has_more)`' } ] }, { title: 'Get a transaction', errors: [ { error: '404 Not Found - Transaction not found', solution: 'Verify tx hash format (0x + 64 hex chars) and wait for confirmation', example: 'Valid: `0x1234...` (66 chars total)' }, { error: 'Tracing costs extra credits', solution: 'Each trace flag adds 0.05 credits. Only on Foundational chains.', example: 'Base: 0.1 | With traces: 0.25 credits' } ] }, { title: 'Wallet Activity Stream', errors: [ { error: 'WebSocket connection failed', solution: 'Verify URL (wss://streaming.covalenthq.com/graphql) and auth header', example: 'Header: `Authorization: Bearer YOUR_API_KEY`' }, { error: 'Subscription not receiving data', solution: 'Use enum format: `ETH_MAINNET` not `eth-mainnet`. Check chain supports Streaming.', example: 'GraphQL: `ETH_MAINNET` | REST: `eth-mainnet`' } ] } ]; troubleshooting.forEach(endpoint => { lines.push(`### ${endpoint.title}`); lines.push(''); endpoint.errors.forEach((err, idx) => { lines.push(`**${idx + 1}. ${err.error}**`); lines.push(`- Solution: ${err.solution}`); if (err.example) lines.push(`- Example: ${err.example}`); lines.push(''); }); }); lines.push('### General Tips'); lines.push('- Always check `response.error` field before accessing `response.data`'); lines.push('- Chain names are case-sensitive: use exact values from Chain Capabilities Matrix'); lines.push('- Token balances are strings: use BigInt or decimal libraries for math'); lines.push('- Pagination is 0-indexed: first page is 0, not 1'); lines.push('- Check Chain Capabilities Matrix for feature availability'); lines.push(''); return lines.join('\n'); } /** * Generate LLM Integration Guide */ function generateLlmIntegrationGuide(chainFiles) { const lines = []; lines.push('# LLM Integration Guide'); lines.push(''); lines.push('# GoldRush API - LLM Integration Guide (Condensed)'); lines.push(''); lines.push('**Purpose:** Quick reference for LLMs and AI agents to correctly use the GoldRush API, focusing on error prevention and critical validation rules.'); lines.push(''); lines.push('---'); lines.push(''); lines.push('## Quick Reference'); lines.push(''); lines.push('| Item | Value |'); lines.push('|------|-------|'); lines.push('| **Base URL** | `https://api.covalenthq.com/v1` |'); lines.push('| **Authentication** | Bearer token in `Authorization` header |'); lines.push('| **API Key** | Sign up at goldrush.dev/platform (starts with `cqt_` or `ckey_`) |'); lines.push('| **TypeScript SDK** | `@covalenthq/client-sdk` |'); lines.push('| **Response Format** | JSON |'); lines.push('| **Protocol** | HTTPS only (HTTP will fail) |'); lines.push(''); lines.push('**Rate Limits:**'); lines.push('- Free 14 day trial: 25,000 API credits/month, 4 requests/second, no overages'); lines.push('- Vibe Coding tier: $10/month for 10,000 included API credits, 4 requests/second, overages at $0.001/credit'); lines.push('- Professional: $250/month for 300,000 included API credits, 50 requests/second, overages at $0.00077/credit'); lines.push(''); lines.push('---'); lines.push(''); lines.push('## Chain Names (CRITICAL)'); lines.push(''); lines.push('Chain names use the format: `{network}-{environment}`. These are **case-sensitive** and must match exactly.'); lines.push(''); // Generate chains table dynamically lines.push('### Supported Chain Names Table'); lines.push(''); lines.push('| Common Name | Chain Name (API Parameter) | Chain ID | Support Level |'); lines.push('|-------------|---------------------------|----------|---------------|'); const sortedChains = [...chainFiles].sort((a, b) => { const levelOrder = { foundational: 0, frontier: 1, community: 2, archived: 3 }; const aLevel = levelOrder[a.frontmatter.support_level] ?? 99; const bLevel = levelOrder[b.frontmatter.support_level] ?? 99; if (aLevel !== bLevel) return aLevel - bLevel; return (a.frontmatter.title || '').localeCompare(b.frontmatter.title || ''); }); sortedChains.forEach(chain => { const fm = chain.frontmatter; const title = fm.title || 'Unknown'; const chainName = fm.chain_name || ''; const chainId = fm.chain_id || 'N/A'; const supportLevel = fm.support_level || ''; if (chainName) { lines.push(`| ${title} | \`${chainName}\` | ${chainId} | ${supportLevel} |`); } }); lines.push(''); lines.push('**Note:** Always use the "Chain Name (API Parameter)" value in API calls. Using common names will result in errors.'); lines.push(''); lines.push(''); lines.push('**Chain Support Levels:**'); lines.push(''); lines.push('Chains are categorized into four support levels. See [Chain Documentation](#chain-documentation) for complete definitions.'); lines.push(''); lines.push('- **Foundational** (6 chains) - Full feature parity including historical balances, token holders at any block, and DEX spot prices'); lines.push('- **Frontier** (28 chains) - Core features with expanding coverage; includes all non-EVM chains'); lines.push('- **Community** (14 chains) - Growing integration with all core onchain data'); lines.push('- **Archived** (5 chains) - Limited data availability, no live data'); lines.push(''); lines.push('---'); lines.push(''); // Parameter Naming Convention lines.push('## Parameter Naming Convention'); lines.push(''); lines.push('GoldRush uses different naming conventions depending on the context:'); lines.push(''); lines.push('| Context | Convention | Example |'); lines.push('|---------|-----------|----------|'); lines.push('| TypeScript SDK | camelCase | `chainName`, `walletAddress` |'); lines.push('| REST API Path Parameters | camelCase | `{chainName}`, `{walletAddress}` |'); lines.push('| REST API Query Parameters | kebab-case | `quote-currency`, `block-height` |'); lines.push('| JSON Response Fields | snake_case | `chain_id`, `updated_at` |'); lines.push(''); lines.push('### Parameter Mapping (SDK ↔ REST API)'); lines.push(''); lines.push('| SDK Parameter | REST Query Parameter |'); lines.push('|--------------|---------------------|'); lines.push('| chainName | N/A (path parameter) |'); lines.push('| walletAddress | N/A (path parameter) |'); lines.push('| quoteCurrency | quote-currency |'); lines.push('| blockHeight | block-height |'); lines.push('| noLogs | no-logs |'); lines.push('| withInternal | with-internal |'); lines.push('| withState | with-state |'); lines.push('| withInputData | with-input-data |'); lines.push(''); lines.push('---'); lines.push(''); // Input Validation Rules lines.push('## Input Validation Rules'); lines.push(''); lines.push('### Ethereum Addresses'); lines.push(''); lines.push('- **Format:** `0x` followed by 40 hexadecimal characters'); lines.push('- **Regex:** `^0x[a-fA-F0-9]{40}$`'); lines.push('- **Case:** Insensitive (both `0xabc...` and `0xABC...` are valid)'); lines.push('- **Special Values:** Also accepts ENS names (e.g., `vitalik.eth`), RNS, Lens Handles, Unstoppable Domains'); lines.push(''); lines.push('**Examples:**'); lines.push('- ✅ Valid: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`'); lines.push('- ✅ Valid: `vitalik.eth`'); lines.push('- ❌ Invalid: `d8dA6BF26964aF9D7eEd9e03E53415D37aA96045` (missing 0x)'); lines.push('- ❌ Invalid: `0xd8dA6BF` (too short)'); lines.push(''); lines.push('### Chain Names'); lines.push(''); lines.push('- **Format:** Exact match from supported chains table (case-sensitive)'); lines.push(''); lines.push('**Examples:**'); lines.push('- ✅ Valid: `eth-mainnet`'); lines.push('- ❌ Invalid: `ethereum` (use `eth-mainnet`)'); lines.push('- ❌ Invalid: `Eth-Mainnet` (case-sensitive)'); lines.push('- ❌ Invalid: `eth_mainnet` (use hyphen, not underscore)'); lines.push(''); lines.push('### Block Heights'); lines.push(''); lines.push('- **Type:** Integer ≥ 0'); lines.push('- **Special Value:** `"latest"` for current block'); lines.push('- **Maximum:** Current chain height (varies by chain)'); lines.push(''); lines.push('**Examples:**'); lines.push('- ✅ Valid: `12345678`'); lines.push('- ✅ Valid: `latest`'); lines.push('- ❌ Invalid: `-1`'); lines.push(''); lines.push('### Quote Currency'); lines.push(''); lines.push('- **Type:** String (case-insensitive)'); lines.push('- **Supported Values:** `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, `GBP`'); lines.push('- **Default:** `USD`'); lines.push(''); lines.push('### Pagination'); lines.push(''); lines.push('- **Page Numbers:** 0-indexed (first page is `0`)'); lines.push('- **Page Size:** 100 items per page (default, not configurable for most endpoints)'); lines.push('- **End Detection:**'); lines.push(' - If returned page has < 100 items, it\'s the last page'); lines.push(' - Check `has_more` field in response (where available)'); lines.push(' - Use `links.next` for next page URL (where available)'); lines.push(''); lines.push('---'); lines.push(''); // Understanding Balance Fields lines.push('## Understanding Balance Fields'); lines.push(''); lines.push('```json'); lines.push('{'); lines.push(' "contract_decimals": 18,'); lines.push(' "balance": "1500000000000000000",'); lines.push(' "quote_rate": 2500.50,'); lines.push(' "quote": 3750.75,'); lines.push(' "pretty_quote": "$3,750.75"'); lines.push('}'); lines.push('```'); lines.push(''); lines.push('**Field Explanations:**'); lines.push('- `balance`: Raw token amount as string (to handle large numbers/BigInt). This is **NOT** the human-readable value.'); lines.push('- `contract_decimals`: Number of decimal places for this token'); lines.push('- `quote_rate`: Current price of 1 token in quote currency (e.g., USD)'); lines.push('- `quote`: Total value of this token holding in quote currency'); lines.push('- `pretty_quote`: Formatted currency string for display'); lines.push(''); lines.push('**To get human-readable balance:**'); lines.push(''); lines.push('```javascript'); lines.push('const humanReadable = parseFloat(balance) / Math.pow(10, contract_decimals);'); lines.push('// Example: "1500000000000000000" / 10^18 = 1.5 tokens'); lines.push('```'); lines.push(''); lines.push('---'); lines.push(''); // Understanding Transaction Fields lines.push('## Understanding Transaction Fields'); lines.push(''); lines.push('```json'); lines.push('{'); lines.push(' "successful": true,'); lines.push(' "value": "0",'); lines.push(' "gas_spent": 21000,'); lines.push(' "gas_price": 50000000000,'); lines.push(' "fees_paid": "1050000000000000",'); lines.push(' "gas_quote": 2.75,'); lines.push(' "gas_quote_rate": 2500.00'); lines.push('}'); lines.push('```'); lines.push(''); lines.push('**Field Explanations:**'); lines.push('- `successful`: Boolean indicating if transaction succeeded'); lines.push('- `value`: Amount of native token transferred (as string, in wei for EVM chains)'); lines.push('- `gas_spent`: Actual gas units consumed'); lines.push('- `gas_price`: Gas price in wei (for EVM chains)'); lines.push('- `fees_paid`: Total fee in wei (`gas_spent × gas_price`)'); lines.push('- `gas_quote`: Total fee in quote currency (e.g., USD)'); lines.push('- `gas_quote_rate`: Native token price used for conversion'); lines.push(''); lines.push('---'); lines.push(''); // Error Responses lines.push('## Error Responses'); lines.push(''); lines.push('All error responses follow this schema:'); lines.push(''); lines.push('```json'); lines.push('{'); lines.push(' "data": null,'); lines.push(' "error": true,'); lines.push(' "error_message": "Human-readable error description",'); lines.push(' "error_code": 401'); lines.push('}'); lines.push('```'); lines.push(''); lines.push('### Common Error Codes'); lines.push(''); lines.push('| HTTP Status | error_code | Meaning | Solution |'); lines.push('|------------|-----------|---------|----------|'); lines.push('| 401 | 401 | Invalid or missing API key | Check Authorization header format: `Bearer YOUR_API_KEY` |'); lines.push('| 400 | 400 | Invalid request parameters | Verify chain name, address format, or other parameters |'); lines.push('| 404 | 404 | Resource not found | Check if chain name is valid or address has activity |'); lines.push('| 429 | 429 | Rate limit exceeded | Reduce request frequency or upgrade plan |'); lines.push('| 500 | 500 | Internal server error | Retry request, contact support if persists |'); lines.push(''); lines.push('---'); lines.push(''); // Best Practices for LLMs lines.push('## Best Practices for LLMs'); lines.push(''); lines.push('### 1. Always Validate Chain Names'); lines.push(''); lines.push('```typescript'); lines.push('const VALID_CHAINS = ['); lines.push(' "eth-mainnet", "matic-mainnet", "base-mainnet",'); lines.push(' "arbitrum-mainnet", "optimism-mainnet", "bsc-mainnet"'); lines.push('];'); lines.push(''); lines.push('function isValidChain(chainName: string): boolean {'); lines.push(' return VALID_CHAINS.includes(chainName);'); lines.push('}'); lines.push('```'); lines.push(''); lines.push('### 2. Handle BigInt Balance Values Correctly'); lines.push(''); lines.push('```typescript'); lines.push('// ❌ WRONG'); lines.push('const balance = parseInt(item.balance); // Will overflow for large values'); lines.push(''); lines.push('// ✅ CORRECT'); lines.push('const balance = parseFloat(item.balance) / Math.pow(10, item.contract_decimals);'); lines.push('```'); lines.push(''); lines.push('### 3. Implement Pagination Properly'); lines.push(''); lines.push('```typescript'); lines.push('// ✅ CORRECT'); lines.push('let page = 0;'); lines.push('let allItems = [];'); lines.push('let hasMore = true;'); lines.push(''); lines.push('while (hasMore) {'); lines.push(' const resp = await fetchPage(page);'); lines.push(' allItems.push(...resp.items);'); lines.push(' hasMore = resp.items.length === 100; // Full page = more data likely exists'); lines.push(' page++;'); lines.push('}'); lines.push('```'); lines.push(''); lines.push('### 4. Use Appropriate Error Handling'); lines.push(''); lines.push('```typescript'); lines.push('const resp = await client.BalanceService.getTokenBalancesForWalletAddress('); lines.push(' chainName,'); lines.push(' address'); lines.push(');'); lines.push(''); lines.push('if (resp.error) {'); lines.push(' // Handle error - don\'t try to access resp.data'); lines.push(' console.error(resp.error_message);'); lines.push(' return;'); lines.push('}'); lines.push(''); lines.push('// Safe to access resp.data here'); lines.push('const balances = resp.data.items;'); lines.push('```'); lines.push(''); lines.push('---'); lines.push(''); // Common Mistakes to Avoid lines.push('## Common Mistakes to Avoid'); lines.push(''); lines.push('### ❌ Using Wrong Chain Name Format'); lines.push(''); lines.push('```typescript'); lines.push('// WRONG'); lines.push('const chain = "ethereum";'); lines.push('const chain = "polygon";'); lines.push(''); lines.push('// CORRECT'); lines.push('const chain = "eth-mainnet";'); lines.push('const chain = "matic-mainnet";'); lines.push('```'); lines.push(''); lines.push('### ❌ Treating Balance as Number'); lines.push(''); lines.push('```typescript'); lines.push('// WRONG'); lines.push('const balance = parseInt(item.balance); // Overflow!'); lines.push(''); lines.push('// CORRECT'); lines.push('const balance = parseFloat(item.balance) / Math.pow(10, item.contract_decimals);'); lines.push('```'); lines.push(''); lines.push('### ❌ Forgetting to Check Error Response'); lines.push(''); lines.push('```typescript'); lines.push('// WRONG'); lines.push('const resp = await client.getSomething();'); lines.push('const data = resp.data.items; // May crash if error'); lines.push(''); lines.push('// CORRECT'); lines.push('const resp = await client.getSomething();'); lines.push('if (!resp.error) {'); lines.push(' const data = resp.data.items;'); lines.push('}'); lines.push('```'); lines.push(''); lines.push('### ❌ Not Handling Pagination'); lines.push(''); lines.push('```typescript'); lines.push('// WRONG - only gets first 100 transactions'); lines.push('const resp = await client.getTransactions(chain, address, { page: 0 });'); lines.push(''); lines.push('// CORRECT - gets all transactions'); lines.push('let page = 0;'); lines.push('let allTxs = [];'); lines.push('while (true) {'); lines.push(' const resp = await client.getTransactions(chain, address, { page });'); lines.push(' if (resp.error || resp.data.items.length === 0) break;'); lines.push(' allTxs.push(...resp.data.items);'); lines.push(' if (resp.data.items.length < 100) break;'); lines.push(' page++;'); lines.push('}'); lines.push('```'); lines.push(''); lines.push('### ❌ Missing Bearer Prefix in Authorization'); lines.push(''); lines.push('```bash'); lines.push('# WRONG'); lines.push('curl -H "Authorization: YOUR_API_KEY"'); lines.push(''); lines.push('# CORRECT'); lines.push('curl -H "Authorization: Bearer YOUR_API_KEY"'); lines.push('```'); lines.push(''); lines.push('### ❌ Using HTTP Instead of HTTPS'); lines.push(''); lines.push('```bash'); lines.push('# WRONG'); lines.push('http://api.covalenthq.com/v1/...'); lines.push(''); lines.push('# CORRECT'); lines.push('https://api.covalenthq.com/v1/...'); lines.push('```'); lines.push(''); lines.push('---'); lines.push(''); // FAQs lines.push('## Frequently Asked Questions (LLM-Specific)'); lines.push(''); lines.push('### Q: How do I convert balance to human-readable format?'); lines.push(''); lines.push('**A:** Divide the balance string by 10^contract_decimals:'); lines.push(''); lines.push('```typescript'); lines.push('const humanReadable = parseFloat(balance) / Math.pow(10, contract_decimals);'); lines.push('// Example:'); lines.push('// balance = "1500000000000000000"'); lines.push('// contract_decimals = 18'); lines.push('// humanReadable = 1.5 tokens'); lines.push('```'); lines.push(''); lines.push('### Q: What\'s the difference between `quote` and `quote_rate`?'); lines.push(''); lines.push('**A:**'); lines.push('- `quote_rate`: Price of 1 token in quote currency (e.g., $2,500.50 per ETH)'); lines.push('- `quote`: Total value of the balance in quote currency (balance × quote_rate)'); lines.push(''); lines.push('### Q: How do I know which chains support internal transactions?'); lines.push(''); lines.push('**A:** Only Foundational chains support tracing features (`with-internal`, `with-state`, `with-input-data`). Currently, only `eth-mainnet` fully supports all tracing features. Check the endpoint documentation for "Foundational Chains" support.'); lines.push(''); lines.push('### Q: How do I handle ENS names?'); lines.push(''); lines.push('**A:** Just pass the ENS name directly as the wallet address. GoldRush automatically resolves it:'); lines.push(''); lines.push('```typescript'); lines.push('const resp = await client.BalanceService.getTokenBalancesForWalletAddress('); lines.push(' "eth-mainnet",'); lines.push(' "vitalik.eth" // Automatically resolved'); lines.push(');'); lines.push('```'); lines.push(''); lines.push('### Q: What\'s the difference between `balances_v2` and `balances_native`?'); lines.push(''); lines.push('**A:**'); lines.push('- `balances_v2`: Returns ALL tokens (native + ERC20 + NFTs)'); lines.push('- `balances_native`: Returns ONLY the native token (ETH, MATIC, etc.)'); lines.push(''); lines.push('Use `balances_native` for lightweight queries when you only need the native token balance.'); lines.push(''); lines.push('### Q: How do I filter out spam tokens?'); lines.push(''); lines.push('**A:** Use the `no-spam` query parameter:'); lines.push(''); lines.push('```bash'); lines.push('curl "https://api.covalenthq.com/v1/eth-mainnet/address/0x.../balances_v2/?no-spam=true"'); lines.push('```'); lines.push(''); lines.push('### Q: When should I use the SDK vs direct REST calls?'); lines.push(''); lines.push('**A:**'); lines.push('- **Use SDK:** TypeScript/JavaScript projects, automatic pagination, type safety'); lines.push('- **Use REST:** Python, Go, or any other language; curl testing; maximum flexibility'); lines.push(''); lines.push('### Q: How often does data update?'); lines.push(''); lines.push('**A:**'); lines.push('- Real-time endpoints: 30 seconds or 2 blocks (whichever is faster)'); lines.push('- Historical data: Indexed from genesis block'); lines.push('- NFT metadata: Cached, use `with-uncached=true` to force refresh'); lines.push(''); lines.push('---'); lines.push(''); // Quick Reference: Endpoint URL Patterns lines.push('## Quick Reference: Endpoint URL Patterns'); lines.push(''); lines.push('| Data Type | URL Pattern |'); lines.push('|-----------|------------|'); lines.push('| Token Balances | `/v1/{chain}/address/{address}/balances_v2/` |'); lines.push('| Native Balance Only | `/v1/{chain}/address/{address}/balances_native/` |'); lines.push('| Transaction History | `/v1/{chain}/address/{address}/transactions_v3/page/{page}/` |'); lines.push('| Single Transaction | `/v1/{chain}/transaction_v2/{txHash}/` |'); lines.push('| NFT Metadata | `/v1/{chain}/tokens/{contract}/nft_metadata/{tokenId}/` |'); lines.push('| Token Holders | `/v1/{chain}/tokens/{contract}/token_holders_v2/` |'); lines.push('| Cross-Chain Activity | `/v1/address/{address}/activity/` |'); lines.push('| Security Approvals | `/v1/{chain}/approvals/{address}/` |'); lines.push('| ERC20 Transfers | `/v1/{chain}/address/{address}/transfers_v2/` |'); lines.push('| Historical Prices | `/v1/pricing/historical_by_address/{chain}/{contract}/` |'); lines.push(''); lines.push('---'); lines.push(''); // Additional Resources lines.push('## Additional Resources'); lines.push(''); lines.push('- **Full API Documentation:** https://goldrush.dev/docs/'); lines.push('- **API Reference:** https://goldrush.dev/docs/api-reference/'); lines.push('- **Guides & Tutorials:** https://goldrush.dev/guides/'); lines.push('- **Supported Chains:** https://goldrush.dev/docs/chains/overview'); lines.push('- **Status Page:** https://status.goldrush.dev/'); lines.push('- **Get API Key:** https://goldrush.dev/platform'); lines.push('- **Discord Community:** https://discord.gg/8ZWgu2pWY4'); lines.push('- **GitHub:** https://github.com/covalenthq'); lines.push(''); lines.push('---'); lines.push(''); // System Prompt Suggestion lines.push('## System Prompt Suggestion for AI Agents'); lines.push(''); lines.push('When building AI agents that use GoldRush API, include this in your system prompt:'); lines.push(''); lines.push('```'); lines.push('You have access to the GoldRush API for blockchain data. Key points:'); lines.push(''); lines.push('1. Chain names use format like "eth-mainnet", "matic-mainnet", "base-mainnet" - never use common names like "ethereum" or "polygon"'); lines.push('2. Balance fields are strings representing large numbers. Divide by 10^contract_decimals to get human-readable values'); lines.push('3. All requests require "Authorization: Bearer YOUR_API_KEY" header'); lines.push('4. Pagination returns 100 items per page. If result has 100 items, more pages likely exist'); lines.push('5. Base URL: https://api.covalenthq.com/v1'); lines.push('6. Always check resp.error before accessing resp.data'); lines.push('7. Ethereum addresses: 0x + 40 hex chars, or ENS names'); lines.push('8. For detailed integration guidance, refer to the LLM Integration Guide'); lines.push('```'); lines.push(''); lines.push('---'); lines.push(''); lines.push('**Last Updated:** January 2025'); lines.push('**API Version:** v1'); lines.push('**Documentation Version:** 2.0 (LLM-Optimized Condensed)'); lines.push(''); return lines.join('\n'); } /** * Generate Chain Capabilities Matrix */ function generateChainCapabilitiesMatrix(chainFiles) { const lines = []; lines.push('This matrix helps you quickly identify which chains support specific features.'); lines.push(''); lines.push('### Legend'); lines.push('- ✓ = Supported'); lines.push('- F = Foundational API, S = Streaming API'); lines.push('- HB = Historical Balances, NFT = NFT Assets & Metadata'); lines.push(''); // Group chains by support level const groupedChains = { foundational: [], frontier: [], community: [], archived: [] }; chainFiles.forEach(chain => { const level = chain.frontmatter.support_level || 'community'; if (groupedChains[level]) groupedChains[level].push(chain); }); // Generate table for each support level ['foundational', 'frontier', 'community', 'archived'].forEach(level => { const chains = groupedChains[level]; if (chains.length === 0) return; lines.push(`#### ${level.charAt(0).toUpperCase() + level.slice(1)} Chains`); lines.push(''); lines.push('| Chain Name | APIs | Advanced Features | Block Time | Network |'); lines.push('|------------|------|-------------------|------------|---------|'); chains.sort((a, b) => (a.frontmatter.title || '').localeCompare(b.frontmatter.title || '')) .forEach(chain => { const fr = chain.frontmatter; const dato = chain.datoRecord; if (!dato) return; const apis = []; if (dato.foundationalapi) apis.push('F'); if (dato.streamingapi) apis.push('S'); if (dato.increment) apis.push('I'); const apiStr = apis.length > 0 ? apis.join(', ') : '—'; const features = []; if (dato.historicalBalances) features.push('HB'); if (dato.nftAssetsAndMetadata) features.push('NFT'); const featuresStr = features.length > 0 ? features.join(', ') : '—'; const blockTime = dato.blocktime ? `${dato.blocktime}s` : 'N/A'; const network = dato.testnet ? 'Testnet' : 'Mainnet'; lines.push(`| ${fr.title} (\`${fr.chain_name}\`) | ${apiStr} | ${featuresStr} | ${blockTime} | ${network} |`); }); lines.push(''); }); lines.push('**Quick Filters:**'); lines.push('- **Historical Balances**: Only chains with "HB" support historical balance queries'); lines.push('- **Real-time Streaming**: Chains with "S" support WebSocket subscriptions'); lines.push('- **Fast Chains**: Chains with block time <2s are ideal for real-time apps'); lines.push(''); return lines.join('\n'); } /** * Generate llms.txt (simple version with paths and titles) */ function generateLlmsTxt(apiFiles, streamingFiles, chainFiles) { const lines = []; lines.push('# GoldRush API Documentation - LLM Index'); lines.push(''); lines.push('## Purpose'); lines.push('This file provides a quick index of all available API endpoints and chain documentation for LLM consumption.'); lines.push(''); lines.push('## Base URL'); lines.push('https://goldrush.dev/docs/'); lines.push(''); lines.push('## API Selection Guide'); lines.push(''); lines.push('Choose the right API for your use case:'); lines.push(''); lines.push('### Foundational API (Historical & Near Real-Time)'); lines.push('API Type: REST'); lines.push('Best for: Wallets, Portfolio Trackers, Tax Tools, Accounting, Compliance, RWA Registries, Block Explorers'); lines.push(''); lines.push('### Streaming API (Real-time/Sub-second)'); lines.push('API Types: graphql-subscription (real-time push), graphql-query (one-time fetch)'); lines.push('Best for: Trading Bots, AI Agents, Alerts, Gaming, Real-time Analytics, Live Price Tracking'); lines.push(''); lines.push('### Hybrid Approach (Both APIs)'); lines.push('Use Foundational for historical data and Streaming for live updates:'); lines.push('- DeFi Dashboards'); lines.push('- Advanced Portfolio Trackers'); lines.push('- Trading Platforms (backtest + live execution)'); lines.push('- RWA Monitoring (ownership history + live transfer events)'); lines.push(''); lines.push('## Endpoint Roles'); lines.push(''); lines.push('Determines how prominently LLMs should recommend each endpoint:'); lines.push(''); lines.push('- **primary** - Essential endpoints for common applications (wallets, portfolios, basic queries). Use these as the default recommendation.'); lines.push('- **specialized** - Advanced endpoints for specific use cases (analytics, block explorers, historical snapshots). Only recommend when the user explicitly needs advanced functionality.'); lines.push('- **legacy** - Kept for backwards compatibility but outdated or replaced by better alternatives. Avoid recommending unless specifically requested.'); lines.push(''); lines.push('## Credit Cost Model'); lines.push(''); lines.push('API credits are charged based on the endpoint type:'); lines.push(''); lines.push('- **per call** - One credit charged per successful HTTP request (200 response)'); lines.push('- **per item** - One credit charged per returned record (default max: 100 items per page)'); lines.push(''); lines.push('## Critical Rules'); lines.push(''); lines.push('- Chain names are **case-sensitive** and must match the supported chain list (e.g. `eth-mainnet`, not "ethereum").'); lines.push('- Always send `Authorization: Bearer YOUR_API_KEY` (no HTTP).'); lines.push('- Pagination is 0-indexed and returns up to 100 items per page.'); lines.push('- Always check `resp.error` before accessing `resp.data`.'); lines.push('- Token balances are large strings; convert using `balance / 10^contract_decimals`.'); lines.push(''); lines.push('## Rate Limits'); lines.push(''); lines.push('- Free 14 day trial: 25,000 API credits/month, 4 requests/second, no overages'); lines.push('- Vibe Coding tier: $10/month for 10,000 included API credits, 4 requests/second, overages at $0.001/credit'); lines.push('- Professional: $250/month for 300,000 included API credits, 50 requests/second, overages at $0.00077/credit'); lines.push(''); // Process API reference files if (apiFiles.length > 0) { lines.push('## Foundational API'); lines.push(''); apiFiles.forEach(file => { const relativePath = path.relative(path.resolve(__dirname, '..'), file.path); const urlPath = relativePath.replace(/\.mdx$/, '').replace(/\\/g, '/'); const fm = file.frontmatter; lines.push(`- ${fm.title}`); lines.push(` Path: ${urlPath}`); // Operation Identity (canonical identifiers) if (fm.operation_identity) { const opId = fm.operation_identity; lines.push(` Operation ID: ${opId.operation_id}`); if (opId.method && opId.path) { lines.push(` Method: ${opId.method}`); lines.push(` Endpoint Path: ${opId.path}`); } if (opId.sdk_service && opId.sdk_method) { lines.push(` SDK: ${opId.sdk_service}.${opId.sdk_method}()`); } } if (fm.api_type) { lines.push(` API Type: ${fm.api_type}`); } if (fm.endpoint_role) { lines.push(` Role: ${fm.endpoint_role}`); } if (fm.category) { lines.push(` Category: ${fm.category}`); } if (fm.credit_cost !== null && fm.credit_cost !== undefined) { lines.push(` Credit Cost: ${fm.credit_cost}`); } if (fm.use_cases && Array.isArray(fm.use_cases) && fm.use_cases.length > 0) { lines.push(` Use Cases: ${fm.use_cases.join(', ')}`); } lines.push(''); }); } // Process streaming API files if (streamingFiles.length > 0) { lines.push('## Streaming API'); lines.push(''); streamingFiles.forEach(file => { const relativePath = path.relative(path.resolve(__dirname, '..'), file.path); const urlPath = relativePath.replace(/\.mdx$/, '').replace(/\\/g, '/'); const fm = file.frontmatter; lines.push(`- ${fm.title}`); lines.push(` Path: ${urlPath}`); // Operation Identity (canonical identifiers) if (fm.operation_identity) { const opId = fm.operation_identity; lines.push(` Operation ID: ${opId.operation_id}`); if (opId.type) { lines.push(` GraphQL Type: ${opId.type}`); } if (opId.field) { lines.push(` GraphQL Field: ${opId.field}`); } if (opId.sdk_service && opId.sdk_method) { lines.push(` SDK: ${opId.sdk_service}.${opId.sdk_method}()`); } } if (fm.category) { lines.push(` Category: ${fm.category}`); } if (fm.api_type) { lines.push(` API Type: ${fm.api_type}`); } if (fm.endpoint_role) { lines.push(` Role: ${fm.endpoint_role}`); } if (fm.beta) { lines.push(` Status: Beta`); } if (fm.use_cases && Array.isArray(fm.use_cases) && fm.use_cases.length > 0) { lines.push(` Use Cases: ${fm.use_cases.join(', ')}`); } lines.push(''); }); } // Process chain files if (chainFiles.length > 0) { lines.push('## Chain Documentation'); lines.push(''); // Add support level definitions const supportLevelDefs = extractSupportLevelDefinitions(); if (Object.keys(supportLevelDefs).length > 0) { lines.push('### Support Levels'); lines.push(''); if (supportLevelDefs.foundational) { lines.push('**Foundational:** ' + supportLevelDefs.foundational.replace(/\n/g, ' ')); lines.push(''); } if (supportLevelDefs.frontier) { lines.push('**Frontier:** ' + supportLevelDefs.frontier.replace(/\n/g, ' ')); lines.push(''); } if (supportLevelDefs.community) { lines.push('**Community:** ' + supportLevelDefs.community.replace(/\n/g, ' ')); lines.push(''); } if (supportLevelDefs.archived) { lines.push('**Archived:** ' + supportLevelDefs.archived.replace(/\n/g, ' ')); lines.push(''); } } chainFiles.forEach(file => { const relativePath = path.relative(path.resolve(__dirname, '..'), file.path); const urlPath = relativePath.replace(/\.mdx$/, '').replace(/\\/g, '/'); const fm = file.frontmatter; lines.push(`- ${fm.title}`); lines.push(` Path: ${urlPath}`); if (fm.chain_name) { lines.push(` Chain Name: ${fm.chain_name}`); } if (fm.chain_id) { lines.push(` Chain ID: ${fm.chain_id}`); } if (fm.support_level) { lines.push(` Support Level: ${fm.support_level}`); } if (fm.use_cases && Array.isArray(fm.use_cases) && fm.use_cases.length > 0) { lines.push(` Use Cases: ${fm.use_cases.join(', ')}`); } lines.push(''); }); } return lines.join('\n'); } /** * Generate llms-full.txt (complete version with frontmatter + content) */ function generateLlmsFullTxt(apiFiles, streamingFiles, chainFiles) { const lines = []; lines.push('# GoldRush API Documentation - Complete LLM Reference'); lines.push(''); lines.push('> This file is optimized for Large Language Models (LLMs) and AI agents.'); lines.push('> It contains structured frontmatter metadata and full content for all API endpoints and chain documentation.'); lines.push(''); lines.push('---'); lines.push(''); // Add Table of Contents lines.push('## Table of Contents'); lines.push(''); lines.push('### Quick Reference'); lines.push('- [API Selection Guide](#api-selection-guide) - Choose between Foundational, Streaming, or Hybrid approach'); lines.push('- [Endpoint Roles](#endpoint-roles) - Understanding primary vs specialized endpoints'); lines.push('- [Credit Cost Model](#credit-cost-model) - How API credits are charged'); lines.push('- [Quick Decision Tree](#quick-decision-tree) - Fast endpoint selection for common scenarios'); lines.push('- [Chain Names & Validation](#chain-names-critical) - Supported chains and parameter rules'); lines.push('- [Common Query Patterns](#common-multi-endpoint-workflows) - Real-world endpoint combinations'); lines.push(''); lines.push('### API Documentation'); lines.push(`- [Foundational API](#foundational-api-documentation) - ${apiFiles.length} REST endpoints`); lines.push(`- [Streaming API](#streaming-api-documentation) - ${streamingFiles.length} GraphQL endpoints`); lines.push(`- [Chain Documentation](#chain-documentation) - ${chainFiles.length} supported chains`); lines.push(''); lines.push('---'); lines.push(''); // Add API Selection Guide lines.push('# API Selection Guide'); lines.push(''); lines.push('## Choosing Between Foundational and Streaming APIs'); lines.push(''); lines.push('### Foundational API - Historical & Near Real-Time'); lines.push('**API Type:** REST'); lines.push(''); lines.push('**When to use:** Your application needs historical blockchain data, batch queries, or near real-time updates (block-by-block).'); lines.push(''); lines.push('**Primary use cases:**'); lines.push('- Wallets (balance checks, transaction history)'); lines.push('- Portfolio Trackers (historical performance, P&L)'); lines.push('- Tax Tools & Accounting (transaction history, cost basis)'); lines.push('- Compliance & Auditing (historical records, audit trails)'); lines.push('- RWA Registries (ownership records, asset provenance, transfer history)'); lines.push('- Block Explorers (historical blockchain data)'); lines.push(''); lines.push('### Streaming API - Real-time/Sub-second'); lines.push('**API Types:** graphql-subscription (real-time push via WebSocket), graphql-query (one-time GraphQL fetch)'); lines.push(''); lines.push('**When to use:** Your application needs sub-second latency updates and real-time event notifications.'); lines.push(''); lines.push('**Primary use cases:**'); lines.push('- Trading Bots (real-time OHLCV, DEX activity)'); lines.push('- AI Agents (real-time event reactions)'); lines.push('- Alerts & Notifications (real-time monitoring)'); lines.push('- Gaming (live game state, real-time events)'); lines.push('- Real-time Analytics (live metrics, dashboards)'); lines.push('- Price Tracking (live price feeds)'); lines.push(''); lines.push('### Hybrid Approach - Best of Both'); lines.push('**When to use:** Your application needs both historical context and real-time updates.'); lines.push(''); lines.push('**Common patterns:**'); lines.push('- **DeFi Dashboards:** Foundational for historical charts/TVL + Streaming for live prices/transactions'); lines.push('- **Advanced Portfolio Trackers:** Foundational for historical performance + Streaming for live balance updates'); lines.push('- **Trading Platforms:** Foundational for backtesting + Streaming for live trade execution'); lines.push('- **RWA Monitoring & Compliance:** Foundational for ownership history/audit trails + Streaming for live transfer events/alerts'); lines.push(''); lines.push('## Endpoint Roles'); lines.push(''); lines.push('Each endpoint is classified with a role that determines how prominently LLMs should recommend it:'); lines.push(''); lines.push('- **primary** - Essential endpoints for common applications (wallets, portfolios, basic queries). These are the default recommendations for typical use cases.'); lines.push('- **specialized** - Advanced endpoints for specific use cases (analytics, block explorers, historical snapshots at specific block heights). Only recommend when the user explicitly needs advanced functionality.'); lines.push('- **legacy** - Kept for backwards compatibility but outdated or replaced by better alternatives. Avoid recommending unless specifically requested.'); lines.push(''); lines.push('## Credit Cost Model'); lines.push(''); lines.push('API credits are charged based on the endpoint pricing model:'); lines.push(''); lines.push('- **per call** - One credit charged per successful HTTP request (200 response). The total cost is fixed regardless of response size.'); lines.push('- **per item** - One credit charged per returned record in the response. Default pagination limit is 100 items per page.'); lines.push(''); lines.push('Example: An endpoint with "0.1 per item" returning 50 records costs 5 credits (0.1 × 50 = 5).'); lines.push(''); lines.push('---'); lines.push(''); // Add Chain Capabilities Matrix lines.push('## Chain Capabilities Matrix'); lines.push(''); lines.push(generateChainCapabilitiesMatrix(chainFiles)); lines.push(''); lines.push('---'); lines.push(''); // Add Quick Decision Tree lines.push('## Quick Decision Tree'); lines.push(''); lines.push('**Select the right endpoint based on what the user wants to do:**'); lines.push(''); lines.push('### Balance & Portfolio Queries'); lines.push('- Check wallet balance → `getTokenBalancesForWalletAddress` (primary, REST, 1 per call)'); lines.push('- Get historical balance at block → `getHistoricalTokenBalancesForWalletAddress` (specialized, REST, 1 per call)'); lines.push('- Get portfolio value over time → `getHistoricalPortfolioForWalletAddress` (primary, REST, 2 per item)'); lines.push('- Get native token only → `getNativeTokenBalance` (primary, REST, 0.5 per call)'); lines.push(''); lines.push('### Transaction Queries'); lines.push('- Get recent transactions → `getRecentTransactionsForAddress` (primary, REST, 0.1 per item)'); lines.push('- Get paginated history → `getTransactionsForAddressV3` (primary, REST, 0.1 per item)'); lines.push('- Get single transaction details → `getTransaction` (primary, REST, 0.1 per call)'); lines.push('- Get ERC20 transfers → `getErc20TransfersForWalletAddress` (primary, REST, 0.05 per item)'); lines.push('- Get transaction summary → `getTransactionSummary` (primary, REST, 1 per call)'); lines.push(''); lines.push('### Security & Approvals'); lines.push('- Check token approvals → `getApprovals` (primary, REST, 2 per call)'); lines.push('- Check NFT approvals → `getNftApprovals` (primary, REST, 1 per call)'); lines.push(''); lines.push('### Real-time Monitoring (Streaming)'); lines.push('- Track real-time prices → `subscribeToOHLCVTokens` (primary, subscription)'); lines.push('- Monitor wallet activity → `subscribeToWalletActivity` (primary, subscription)'); lines.push('- Detect new DEX pairs → `subscribeToNewPairs` (primary, subscription)'); lines.push('- Track specific pair prices → `subscribeToOHLCVPairs` (primary, subscription)'); lines.push(''); lines.push('### NFT & Token Queries'); lines.push('- Get NFT holdings → `getNftsForAddress` (primary, REST, 1 per call)'); lines.push('- Search for tokens → `searchToken` (primary, query)'); lines.push('- Get token holders → `getTokenHoldersV2ForTokenAddress` (specialized, REST, 0.02 per item)'); lines.push(''); lines.push('### Multi-chain Queries'); lines.push('- Check which chains address is active on → `getAddressActivity` (primary, REST, 0.5 per call)'); lines.push('- Get balances across chains → `getMultiChainBalances` (specialized, REST, 2.5 per call)'); lines.push('- Get transactions across chains → `getMultiChainMultiAddressTransactions` (specialized, REST, 0.25 per item)'); lines.push(''); lines.push('### Token & Price Queries'); lines.push('- Search for token by name/symbol → `searchToken` (primary, query)'); lines.push('- Get token price history → `getTokenPrices` (primary, REST, 1 per call)'); lines.push('- Get DEX pool prices → `getPoolSpotPrices` (specialized, REST, Foundational only)'); lines.push('- Track real-time token prices → `subscribeToOHLCVTokens` (primary, subscription)'); lines.push(''); lines.push('### Block & Event Queries'); lines.push('- Get block details → `getBlock` (specialized, REST, 1 per call)'); lines.push('- Get block heights by date → `getBlockHeights` (specialized, REST, 1 per call)'); lines.push('- Get contract event logs → `getLogEventsByAddress` (specialized, REST, 0.01 per item)'); lines.push('- Get logs by topic hash → `getLogEventsByTopicHash` (specialized, REST, 0.01 per item)'); lines.push(''); lines.push('### DeFi & Trading'); lines.push('- Track DEX pair creation → `subscribeToNewPairs` (primary, subscription)'); lines.push('- Monitor DEX pair updates → `subscribeToUpdatePairs` (primary, subscription)'); lines.push('- Get OHLCV candles for pairs → `subscribeToOHLCVPairs` (primary, subscription)'); lines.push(''); lines.push('### Compliance & Auditing'); lines.push('- Get token holder snapshots → `getTokenHoldersV2ForTokenAddress` (specialized, REST, Foundational only)'); lines.push('- Get historical balances at block → `getHistoricalTokenBalancesForWalletAddress` (specialized, REST, Foundational only)'); lines.push('- Audit transaction history → `getTransactionsForAddressV3` (primary, REST, 0.1 per item)'); lines.push(''); lines.push('---'); lines.push(''); // Add LLM Integration Guide lines.push(generateLlmIntegrationGuide(chainFiles)); lines.push(''); lines.push('---'); lines.push(''); // Add LLM Operational Guide (deeper dive) lines.push('## LLM Operational Guide (Deeper Dive)'); lines.push(''); lines.push('This section is optimized for real-world task routing and error prevention. Use it after `llms.txt`.'); lines.push(''); lines.push('### Task-to-Endpoint Map'); lines.push('- Current wallet balances → `getTokenBalancesForWalletAddress`'); lines.push('- Native token only → `getNativeTokenBalance`'); lines.push('- ERC20 transfers → `getErc20TransfersForWalletAddress`'); lines.push('- Recent transactions → `getRecentTransactionsForAddress`'); lines.push('- Full history (paged) → `getTransactionsForAddressV3` (page 0 = earliest)'); lines.push('- Transaction summary → `getTransactionSummary`'); lines.push('- Single transaction → `getTransaction`'); lines.push('- Token holders snapshot → `getTokenHoldersV2ForTokenAddress` (Foundational chains only)'); lines.push('- Historical balances at block → `getHistoricalTokenBalancesForWalletAddress` (Foundational chains only)'); lines.push('- Historical token prices → `getTokenPrices`'); lines.push('- Pool spot prices → `getPoolSpotPrices` (Foundational chains only)'); lines.push('- Approvals (ERC20/NFT) → `getApprovals`, `getNftApprovals`'); lines.push('- Multi-chain activity → `getAddressActivity`'); lines.push('- Multi-chain balances → `getMultiChainBalances` (no ENS/domain names)'); lines.push('- Multi-chain txs → `getMultiChainMultiAddressTransactions` (no ENS/domain names)'); lines.push('- Streaming wallet activity → `subscribeToWalletActivity`'); lines.push('- Streaming OHLCV tokens/pairs → `subscribeToOHLCVTokens`, `subscribeToOHLCVPairs`'); lines.push('- Streaming new pairs/updates → `subscribeToNewPairs`, `subscribeToUpdatePairs`'); lines.push('- Streaming token search → `searchToken` (GraphQL query)'); lines.push(''); lines.push('### Parameter & Naming Rules'); lines.push('- Chain names are case-sensitive; use the exact `chain_name` values from the chain table.'); lines.push('- REST path params are camelCase; REST query params are kebab-case.'); lines.push('- Pagination is 0-indexed; 100 items per page is the default.'); lines.push('- Always check `resp.error` before accessing `resp.data`.'); lines.push('- Token balances are strings; convert with decimals to avoid overflow.'); lines.push(''); lines.push('### Chain Support Boundaries'); lines.push('- Foundational-only features: historical token balances, token holders at any block, pool spot prices, tracing flags.'); lines.push('- Non-EVM chains have partial coverage (e.g. Bitcoin has dedicated endpoints; Solana supports balances only).'); lines.push('- Streaming uses enum chain names like `ETH_MAINNET` in GraphQL.'); lines.push(''); lines.push('### Common Mistakes to Avoid'); lines.push('- Using common chain names (e.g. "ethereum") instead of `eth-mainnet`.'); lines.push('- Treating `balance` fields as numbers without decimals conversion.'); lines.push('- Forgetting pagination or assuming a single page is complete.'); lines.push('- Mixing Streaming subscriptions when historical data is required (or vice versa).'); lines.push(''); lines.push('---'); lines.push(''); // Add Common Errors & Troubleshooting lines.push('## Common Errors & Troubleshooting'); lines.push(''); lines.push(generateTroubleshootingSection()); lines.push(''); lines.push('---'); lines.push(''); // Add Common Multi-Endpoint Workflows lines.push('## Common Multi-Endpoint Workflows'); lines.push(''); lines.push('Real-world scenarios often require combining multiple endpoints. Here are proven patterns:'); lines.push(''); lines.push('### Portfolio Valuation & Analysis'); lines.push('```'); lines.push('1. getTokenBalancesForWalletAddress → Get current token holdings with spot prices'); lines.push('2. getHistoricalPortfolioForWalletAddress → Get historical portfolio value over time'); lines.push('3. getTransactionsForAddressV3 → Get full transaction history for cost basis'); lines.push('```'); lines.push('**Use case:** Building portfolio trackers, tax calculators, wealth management dashboards'); lines.push(''); lines.push('### Transaction Deep Dive'); lines.push('```'); lines.push('1. getRecentTransactionsForAddress → Get latest transactions'); lines.push('2. getTransaction(txHash) → Get detailed decoded data for specific transaction'); lines.push('3. getLogEventsByAddress → Get contract event logs for context'); lines.push('```'); lines.push('**Use case:** Transaction explorers, audit trails, forensic analysis'); lines.push(''); lines.push('### Security Audit'); lines.push('```'); lines.push('1. getApprovals → Check ERC20 token approvals'); lines.push('2. getNftApprovals → Check NFT approvals'); lines.push('3. getRecentTransactionsForAddress → Review recent approval transactions'); lines.push('```'); lines.push('**Use case:** Security dashboards, wallet protection tools, approval management'); lines.push(''); lines.push('### Trading Bot Setup (Hybrid: Foundational + Streaming)'); lines.push('```'); lines.push('Historical Data (Foundational API):'); lines.push('1. getTokenPrices → Get historical price data for backtesting'); lines.push('2. getHistoricalPortfolioForWalletAddress → Analyze historical performance'); lines.push(''); lines.push('Live Monitoring (Streaming API):'); lines.push('3. subscribeToNewPairs → Detect newly created DEX pairs'); lines.push('4. subscribeToOHLCVPairs → Track real-time price movements'); lines.push('5. subscribeToWalletActivity → Monitor whale wallet transactions'); lines.push('```'); lines.push('**Use case:** Automated trading systems, arbitrage bots, market monitoring'); lines.push(''); lines.push('### Multi-Chain Portfolio'); lines.push('```'); lines.push('1. getAddressActivity → Discover which chains the address is active on'); lines.push('2. getMultiChainBalances → Get balances across all active chains'); lines.push('3. getMultiChainMultiAddressTransactions → Get transaction history across chains'); lines.push('```'); lines.push('**Use case:** Cross-chain wallets, multi-chain portfolio trackers, aggregated analytics'); lines.push(''); lines.push('### RWA Monitoring & Compliance (Hybrid)'); lines.push('```'); lines.push('Historical Records (Foundational API):'); lines.push('1. getHistoricalTokenBalancesForWalletAddress → Ownership history at specific blocks'); lines.push('2. getTransactionsForAddressV3 → Complete transfer history'); lines.push('3. getTokenHoldersV2ForTokenAddress → Token holder snapshots'); lines.push(''); lines.push('Live Monitoring (Streaming API):'); lines.push('4. subscribeToWalletActivity → Real-time transfer notifications'); lines.push('5. subscribeToUpdatePairs → Live asset valuation updates'); lines.push('```'); lines.push('**Use case:** RWA registries, compliance platforms, real-time asset tracking'); lines.push(''); lines.push('### NFT Collection Analysis'); lines.push('```'); lines.push('1. getNftsForAddress → Get NFT holdings for an address'); lines.push('2. checkOwnershipInNft → Verify NFT ownership for token gating'); lines.push('3. getRecentTransactionsForAddress → Get recent NFT transaction history'); lines.push('```'); lines.push('**Use case:** NFT galleries, token-gated access, collection tracking'); lines.push(''); lines.push('---'); lines.push(''); // Process API reference files if (apiFiles.length > 0) { lines.push('# Foundational API Documentation'); lines.push(''); apiFiles.forEach((file, index) => { const relativePath = path.relative(path.resolve(__dirname, '..'), file.path); const urlPath = relativePath.replace(/\.mdx$/, '').replace(/\\/g, '/'); const fm = file.frontmatter; lines.push(`## ${index + 1}. ${fm.title}`); lines.push(''); lines.push(`**Path:** ${urlPath}`); lines.push(''); // Add operation identity if available if (fm.operation_identity) { const opId = fm.operation_identity; lines.push('**Operation Identity:**'); lines.push(`- Operation ID: \`${opId.operation_id}\``); if (opId.method && opId.path) { lines.push(`- Method: \`${opId.method}\``); lines.push(`- Endpoint Path: \`${opId.path}\``); } if (opId.sdk_service && opId.sdk_method) { lines.push(`- TypeScript SDK: \`${opId.sdk_service}.${opId.sdk_method}()\``); } lines.push(''); } // Add response schema if (file.datoRecord) { const responseSchema = getResponseSchema(file.datoRecord, fm.api_type); if (responseSchema) { lines.push('**Expected Response:**'); lines.push(responseSchema.description); lines.push('```json'); lines.push(responseSchema.schema); lines.push('```'); lines.push(''); } } // Add frontmatter as structured metadata lines.push('**Metadata:**'); lines.push('```yaml'); Object.entries(fm).forEach(([key, value]) => { if (typeof value === 'object' && value !== null) { lines.push(`${key}: ${JSON.stringify(value)}`); } else { lines.push(`${key}: ${value}`); } }); lines.push('```'); lines.push(''); // Add content lines.push('**Content:**'); lines.push(''); lines.push(stripMdxToPlainMarkdown(file.content)); lines.push(''); lines.push('---'); lines.push(''); }); } // Process streaming API files if (streamingFiles.length > 0) { lines.push('# Streaming API Documentation'); lines.push(''); streamingFiles.forEach((file, index) => { const relativePath = path.relative(path.resolve(__dirname, '..'), file.path); const urlPath = relativePath.replace(/\.mdx$/, '').replace(/\\/g, '/'); const fm = file.frontmatter; lines.push(`## ${index + 1}. ${fm.title}`); lines.push(''); lines.push(`**Path:** ${urlPath}`); lines.push(''); // Add operation identity if available if (fm.operation_identity) { const opId = fm.operation_identity; lines.push('**Operation Identity:**'); lines.push(`- Operation ID: \`${opId.operation_id}\``); if (opId.type) { lines.push(`- GraphQL Type: \`${opId.type}\``); } if (opId.field) { lines.push(`- GraphQL Field: \`${opId.field}\``); } if (opId.sdk_service && opId.sdk_method) { lines.push(`- TypeScript SDK: \`${opId.sdk_service}.${opId.sdk_method}()\``); } lines.push(''); } // Add response schema if (file.datoRecord) { const responseSchema = getResponseSchema(file.datoRecord, fm.api_type); if (responseSchema) { lines.push('**Expected Response:**'); lines.push(responseSchema.description); lines.push('```json'); lines.push(responseSchema.schema); lines.push('```'); lines.push(''); } } // Add frontmatter as structured metadata lines.push('**Metadata:**'); lines.push('```yaml'); Object.entries(fm).forEach(([key, value]) => { if (typeof value === 'object' && value !== null) { lines.push(`${key}: ${JSON.stringify(value)}`); } else { lines.push(`${key}: ${value}`); } }); lines.push('```'); lines.push(''); // Add content lines.push('**Content:**'); lines.push(''); lines.push(stripMdxToPlainMarkdown(file.content)); lines.push(''); lines.push('---'); lines.push(''); }); } // Process chain files if (chainFiles.length > 0) { lines.push('# Chain Documentation'); lines.push(''); // Add support level definitions const supportLevelDefs = extractSupportLevelDefinitions(); if (Object.keys(supportLevelDefs).length > 0) { lines.push('## Support Levels'); lines.push(''); if (supportLevelDefs.foundational) { lines.push('### Foundational Chains'); lines.push(supportLevelDefs.foundational); lines.push(''); } if (supportLevelDefs.frontier) { lines.push('### Frontier Chains'); lines.push(supportLevelDefs.frontier); lines.push(''); } if (supportLevelDefs.community) { lines.push('### Community Chains'); lines.push(supportLevelDefs.community); lines.push(''); } if (supportLevelDefs.archived) { lines.push('### Archived Chains'); lines.push(supportLevelDefs.archived); lines.push(''); } lines.push('---'); lines.push(''); } chainFiles.forEach((file, index) => { const relativePath = path.relative(path.resolve(__dirname, '..'), file.path); const urlPath = relativePath.replace(/\.mdx$/, '').replace(/\\/g, '/'); const fm = file.frontmatter; lines.push(`## ${index + 1}. ${fm.title}`); lines.push(''); lines.push(`**Path:** ${urlPath}`); lines.push(''); // Add frontmatter as structured metadata lines.push('**Metadata:**'); lines.push('```yaml'); Object.entries(fm).forEach(([key, value]) => { if (typeof value === 'object' && value !== null) { lines.push(`${key}: ${JSON.stringify(value)}`); } else { lines.push(`${key}: ${value}`); } }); lines.push('```'); lines.push(''); // Add content lines.push('**Content:**'); lines.push(''); lines.push(stripMdxToPlainMarkdown(file.content)); lines.push(''); lines.push('---'); lines.push(''); }); } return lines.join('\n'); } /** * Main function */ function main() { console.log('🔍 Finding and processing MDX files...'); console.log(''); // Log DatoCMS filtering statistics const totalEndpoints = datoApiData.data.allApiendpoints.length; const publishedEndpoints = apiEndpoints.length; console.log(`📋 Loaded ${publishedEndpoints} published endpoints from DatoCMS (filtered from ${totalEndpoints} total)`); console.log(''); // Find all MDX files const apiMdxFiles = findMdxFiles(apiReferenceDir); const streamingMdxFiles = findMdxFiles(streamingApiDir).filter(f => { const basename = path.basename(f); // Exclude documentation files return !['overview.mdx', 'quickstart.mdx', 'sdk.mdx', 'authentication.mdx', 'graphql-endpoints.mdx', 'decoded-events.mdx'].includes(basename); }); const chainMdxFiles = findMdxFiles(chainsDir).filter(f => { const basename = path.basename(f); // Exclude overview file return basename !== 'overview.mdx'; }); console.log(`📊 Found ${apiMdxFiles.length} Foundational API files`); console.log(`📊 Found ${streamingMdxFiles.length} Streaming API files`); console.log(`📊 Found ${chainMdxFiles.length} Chain files`); console.log(''); // Parse and enrich with DatoCMS data console.log('🔄 Enriching with DatoCMS data...'); const allEnrichedApiFiles = apiMdxFiles.map(f => parseAndEnrichEndpoint(f, apiEndpoints)); const allEnrichedStreamingFiles = streamingMdxFiles.map(f => parseAndEnrichEndpoint(f, apiEndpoints)); const enrichedChainFiles = chainMdxFiles.map(f => parseAndEnrichChain(f, chains)); // Filter to only include endpoints with published DatoCMS records const enrichedApiFiles = allEnrichedApiFiles.filter(f => f.datoRecord !== null); const enrichedStreamingFiles = allEnrichedStreamingFiles.filter(f => f.datoRecord !== null); const filteredOutApiCount = allEnrichedApiFiles.length - enrichedApiFiles.length; const filteredOutStreamingCount = allEnrichedStreamingFiles.length - enrichedStreamingFiles.length; console.log(`✅ Matched ${enrichedApiFiles.length} Foundational API endpoints with published DatoCMS records`); console.log(`✅ Matched ${enrichedStreamingFiles.length} Streaming API endpoints with published DatoCMS records`); if (filteredOutApiCount > 0) { console.log(`⚠️ Filtered out ${filteredOutApiCount} Foundational API files without published DatoCMS records`); } if (filteredOutStreamingCount > 0) { console.log(`⚠️ Filtered out ${filteredOutStreamingCount} Streaming API files without published DatoCMS records`); } console.log(''); console.log('✍️ Generating llms.txt...'); const llmsTxt = generateLlmsTxt(enrichedApiFiles, enrichedStreamingFiles, enrichedChainFiles); fs.writeFileSync(llmsTxtPath, llmsTxt, 'utf8'); console.log('✅ Created:', llmsTxtPath); console.log('✍️ Generating llms-full.txt...'); const llmsFullTxt = generateLlmsFullTxt(enrichedApiFiles, enrichedStreamingFiles, enrichedChainFiles); fs.writeFileSync(llmsFullTxtPath, llmsFullTxt, 'utf8'); console.log('✅ Created:', llmsFullTxtPath); console.log(''); console.log('🎉 Done! Generated:'); console.log(` - llms.txt (${Math.round(llmsTxt.length / 1024)} KB)`); console.log(` - llms-full.txt (${Math.round(llmsFullTxt.length / 1024)} KB)`); console.log(''); console.log('📈 Statistics:'); console.log(` - ${enrichedApiFiles.length} Foundational API endpoints`); console.log(` - ${enrichedStreamingFiles.length} Streaming API endpoints`); console.log(` - ${enrichedChainFiles.length} Chains`); } // Run the script if (require.main === module) { main(); } module.exports = { generateLlmsTxt, generateLlmsFullTxt, parseAndEnrichEndpoint, parseAndEnrichChain, findMdxFiles };

Chain	Chain Name	Chain ID
ApeChain Mainnet	apechain-mainnet	33139
World Chain Mainnet	world-mainnet	480
World Chain Testnet	world-sepolia-testnet	4801
Unichain Testnet	unichain-sepolia-testnet	1301

Learn about GoldRush

Components