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 pipelineApiDir = path.resolve(__dirname, '../goldrush-pipeline-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'); // Skills reference paths const skillsDir = path.resolve(__dirname, '../skills'); const foundationalSkillsRefDir = path.resolve(skillsDir, 'goldrush-foundational-api/references'); const streamingSkillsRefDir = path.resolve(skillsDir, 'goldrush-streaming-api/references'); const x402SkillsRefDir = path.resolve(skillsDir, 'goldrush-x402/references'); // Hand-authored source paths const foundationalOverviewPath = path.resolve(__dirname, '../goldrush-foundational-api/overview.mdx'); const foundationalQuickstartPath = path.resolve(__dirname, '../goldrush-foundational-api/quickstart.mdx'); const foundationalAuthPath = path.resolve(__dirname, '../goldrush-foundational-api/authentication.mdx'); const streamingOverviewPath = path.resolve(__dirname, '../goldrush-streaming-api/overview.mdx'); const streamingQuickstartPath = path.resolve(__dirname, '../goldrush-streaming-api/quickstart.mdx'); const streamingAuthPath = path.resolve(__dirname, '../goldrush-streaming-api/authentication.mdx'); const streamingSdkPath = path.resolve(__dirname, '../goldrush-streaming-api/sdk.mdx'); const streamingDecodedEventsPath = path.resolve(__dirname, '../goldrush-streaming-api/decoded-events.mdx'); const x402OverviewPath = path.resolve(__dirname, '../goldrush-x402/overview.mdx'); const x402QuickstartPath = path.resolve(__dirname, '../goldrush-x402/quickstart.mdx'); const x402AiAgentsPath = path.resolve(__dirname, '../goldrush-x402/ai-agents.mdx'); const errorHandlingPath = path.resolve(__dirname, '../error-handling.mdx'); const faqPath = path.resolve(__dirname, '../faq.mdx'); const bitcoinSupportPath = path.resolve(__dirname, '../resources/enhanced-bitcoin-support.mdx'); const spamListsPath = path.resolve(__dirname, '../resources/enhanced-spam-lists.mdx'); const streamingChainsDexesPath = path.resolve(__dirname, '../data/streaming-chains-dexes.json'); const cliOverviewPath = path.resolve(__dirname, '../goldrush-cli/overview.mdx'); const cliQuickstartPath = path.resolve(__dirname, '../goldrush-cli/quickstart.mdx'); const cliCommandsPath = path.resolve(__dirname, '../goldrush-cli/commands.mdx'); const cliSkillsRefDir = path.resolve(skillsDir, 'goldrush-cli/references'); // 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().replace(/^\[([^\]]+)\]\([^)]+\)$/, '$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(); /** * 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 a Pipeline API MDX file. No DatoCMS enrichment — these pages are * generated from normalizers.yml and hand-authored guides. */ function parsePipelineFile(filePath) { const fileContent = fs.readFileSync(filePath, 'utf8'); const { data, content } = matter(fileContent); return { path: filePath, frontmatter: data, content: content.trim() }; } /** * 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 = convertCalloutComponents(processed); processed = convertCodeGroupComponents(processed); processed = convertTabComponents(processed); processed = convertStepComponents(processed); processed = processed.replace(/]*>([\s\S]*?)<\/Columns>/g, '$1'); processed = processed.replace(/]*>([\s\S]*?)<\/AccordionGroup>/g, '$1'); processed = convertParamFieldComponents(processed); processed = convertResponseFieldComponents(processed); 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 convertCalloutComponents(content) { // , , → blockquote (same pattern as ) return content .replace(/]*>([\s\S]*?)<\/Note>/gi, (m, c) => `\n> **Note:** ${c.trim()}\n`) .replace(/]*>([\s\S]*?)<\/Tip>/gi, (m, c) => `\n> **Tip:** ${c.trim()}\n`) .replace(/]*>([\s\S]*?)<\/Warning>/gi, (m, c) => `\n> **Warning:** ${c.trim()}\n`); } function convertCodeGroupComponents(content) { // ...code blocks... → unwrap, keep code blocks return content.replace(/]*>([\s\S]*?)<\/CodeGroup>/g, '$1'); } function convertTabComponents(content) { // → unwrap; → ### X heading return content .replace(/]*>([\s\S]*?)<\/Tabs>/g, '$1') .replace(/]*>([\s\S]*?)<\/Tab>/g, (m, title, c) => `\n### ${title}\n\n${c.trim()}\n`); } function convertStepComponents(content) { // → unwrap; → bold title return content .replace(/]*>([\s\S]*?)<\/Steps>/g, '$1') .replace(/]*>([\s\S]*?)<\/Step>/g, (m, title, c) => `\n**${title}**\n\n${c.trim()}\n`); } function escapePipeForTable(text) { return text .replace(/\|/g, '\\|') .replace(/\n+/g, ' ') .replace(/\s{2,}/g, ' ') .trim(); } function convertParamFieldComponents(content) { // Step 1: Replace each with a tab-delimited row marker let processed = content.replace( /]*>([\s\S]*?)<\/ParamField>/g, (match, name, type, reqFlag, desc) => { const required = reqFlag === 'required' ? 'Yes' : 'No'; const cleanDesc = escapePipeForTable(desc); return `__PARAM_ROW__${name}\t${type}\t${required}\t${cleanDesc}`; } ); // Step 2: Group consecutive __PARAM_ROW__ lines into a markdown table processed = processed.replace( /(?:^|\n)(__PARAM_ROW__[^\n]+(?:\n\s*__PARAM_ROW__[^\n]+)*)/gm, (match, block) => { const rows = block.trim().split(/\n\s*/).filter(l => l.startsWith('__PARAM_ROW__')); let table = '\n| Parameter | Type | Required | Description |\n'; table += '| --- | --- | --- | --- |\n'; for (const row of rows) { const payload = row.replace('__PARAM_ROW__', ''); const parts = payload.split('\t'); const name = parts[0]; const type = parts[1]; const required = parts[2]; const desc = parts.slice(3).join('\t'); table += `| \`${name}\` | \`${type}\` | ${required} | ${desc} |\n`; } return '\n' + table; } ); return processed; } function convertResponseFieldComponents(content) { // Pass 1: Nested ResponseFields (containing with child ResponseFields) // Group 3 uses negative lookahead to prevent matching across ResponseField boundaries let processed = content.replace( /]*>((?:(?!<\/?ResponseField)[\s\S])*?)]*>([\s\S]*?)<\/Expandable>\s*<\/ResponseField>/g, (match, parentName, parentType, parentDesc, expandableContent) => { const rows = []; // Clean parent description (text before ) const cleanParentDesc = escapePipeForTable(parentDesc); rows.push(`__RESPONSE_ROW__${parentName}\t${parentType}\t${cleanParentDesc}`); // Extract child ResponseFields from Expandable content const childRegex = /]*>([\s\S]*?)<\/ResponseField>/g; let childMatch; while ((childMatch = childRegex.exec(expandableContent)) !== null) { const childName = childMatch[1]; const childType = childMatch[2]; const cleanChildDesc = escapePipeForTable(childMatch[3]); rows.push(`__RESPONSE_ROW__${parentName}.${childName}\t${childType}\t${cleanChildDesc}`); } return rows.join('\n'); } ); // Pass 2: Flat ResponseFields (remaining after Pass 1) processed = processed.replace( /]*>([\s\S]*?)<\/ResponseField>/g, (match, name, type, desc) => { const cleanDesc = escapePipeForTable(desc); return `__RESPONSE_ROW__${name}\t${type}\t${cleanDesc}`; } ); // Pass 3: Group consecutive __RESPONSE_ROW__ lines into a markdown table processed = processed.replace( /(?:^|\n)(__RESPONSE_ROW__[^\n]+(?:\n\s*__RESPONSE_ROW__[^\n]+)*)/gm, (match, block) => { const rows = block.trim().split(/\n\s*/).filter(l => l.startsWith('__RESPONSE_ROW__')); let table = '\n| Field | Type | Description |\n'; table += '| --- | --- | --- |\n'; for (const row of rows) { const payload = row.replace('__RESPONSE_ROW__', ''); const parts = payload.split('\t'); const name = parts[0]; const type = parts[1]; const desc = parts.slice(2).join('\t'); table += `| \`${name}\` | \`${type}\` | ${desc} |\n`; } return '\n' + table; } ); return processed; } 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.goldrushdata.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('- x402 (Pay-Per-Request): No subscription required, 100 requests/minute per wallet, pay with stablecoins on Base'); 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, pipelineFiles, 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('WebSocket Endpoint: wss://streaming.goldrushdata.com/graphql'); lines.push('Best for: Trading Bots, AI Agents, Alerts, Gaming, Real-time Analytics, Live Price Tracking'); lines.push('Data Sources: Major token prices (BTC, ETH, SOL) on MegaETH powered by Redstone Bolt — 2.4ms updates sourced from Binance, Coinbase, OKX, Bitget, Kraken.'); lines.push(''); lines.push('### x402 API (Pay-Per-Request for AI Agents)'); lines.push('API Type: REST (via x402 payment-gated proxy)'); lines.push('Base URL: https://x402.goldrush.dev/v1'); lines.push('Best for: AI Agents, Autonomous Systems, Serverless/No-Account Access'); lines.push('No API key required — pay per request with stablecoins on Base via the x402 protocol (HTTP 402).'); lines.push('Provides access to 60+ Foundational API endpoints through a transparent reverse proxy.'); 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('- x402 (Pay-Per-Request): No subscription required, 100 requests/minute per wallet, pay with stablecoins on Base'); 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(''); }); } // x402 API section lines.push('## x402 API (Pay-Per-Request)'); lines.push(''); lines.push('The x402 API is a payment-gated proxy in front of the GoldRush Foundational API. AI agents pay per request using the x402 protocol (HTTP 402) with stablecoins on Base — no API keys, accounts, or subscriptions needed.'); lines.push(''); lines.push('Base URL: https://x402.goldrush.dev/v1'); lines.push('Protocol: x402 (HTTP 402 Payment Required)'); lines.push('Network: Base Sepolia testnet (Base mainnet coming soon)'); lines.push('Rate Limit: 100 requests/minute per wallet'); lines.push('Client Libraries: @x402/core, @x402/evm'); lines.push(''); lines.push('### How It Works'); lines.push('1. Agent calls an endpoint without payment'); lines.push('2. Server responds with HTTP 402 and payment instructions'); lines.push('3. Agent pays with stablecoins on Base and retries with proof of payment'); lines.push('4. Server validates the request before charging, then returns data'); lines.push(''); lines.push('### Pricing Model'); lines.push('- Fixed-Price Endpoints: One price per call (e.g., token balances, NFT holdings)'); lines.push('- Tiered Pricing: For variable-length data — Small (1-50 items), Medium (51-200), Large (201-500), XL (501+)'); lines.push('- Response Caching: Cached responses cost less (TTLs: 30s for balances, 5m for pricing data)'); lines.push(''); lines.push('### Discovery Endpoints (Free)'); lines.push(''); lines.push('- List all available x402 endpoints'); lines.push(' Endpoint Path: /v1/x402/endpoints'); lines.push(' Method: GET'); lines.push(' Cost: Free'); lines.push(' Role: primary'); lines.push(''); lines.push('- Search x402 endpoints'); lines.push(' Endpoint Path: /v1/x402/search?q={query}'); lines.push(' Method: GET'); lines.push(' Cost: Free'); lines.push(' Role: primary'); lines.push(''); lines.push('- Get details for a specific x402 endpoint'); lines.push(' Endpoint Path: /v1/x402/endpoints/{endpoint-name}'); lines.push(' Method: GET'); lines.push(' Cost: Free'); lines.push(' Role: primary'); lines.push(''); lines.push('### Data Endpoints (Paid via x402)'); lines.push(''); lines.push('All 60+ Foundational API endpoints are available through the x402 proxy. Key examples:'); lines.push(''); lines.push('- Get token balances for address (x402)'); lines.push(' Endpoint Path: /v1/{chainName}/address/{walletAddress}/balances_v2/'); lines.push(' Method: GET'); lines.push(' Pricing: Fixed-price per call'); lines.push(''); lines.push('- Get recent transactions for address (x402)'); lines.push(' Endpoint Path: /v1/{chainName}/address/{walletAddress}/transactions_v3/'); lines.push(' Method: GET'); lines.push(' Pricing: Tiered (use ?tier=small|medium|large|xl)'); 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 Pipeline API files if (pipelineFiles.length > 0) { lines.push('## Pipeline API'); lines.push(''); lines.push('Streaming blockchain data into customer-managed destinations (ClickHouse, Kafka, Postgres, S3, SQS, webhooks). Includes normalizer schemas (column-level field definitions for EVM, HyperCore, and Solana entities), destination guides, ABI decoding reference, and SQL transforms.'); lines.push(''); pipelineFiles.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 || path.basename(file.path, '.mdx')}`); lines.push(` Path: ${urlPath}`); if (fm.description) { lines.push(` Description: ${fm.description}`); } 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, pipelineFiles, 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(`- [Pipeline API](#pipeline-api-documentation) - ${pipelineFiles.length} pages (normalizers, destinations, guides)`); lines.push('- [x402 API](#x402-api-documentation) - Pay-per-request access for AI agents (60+ 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('**WebSocket Endpoint:** `wss://streaming.goldrushdata.com/graphql`'); 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('**Data Sources:**'); lines.push('- Major token prices (BTC, ETH, SOL) on MegaETH are powered by Redstone Bolt — ultra-low-latency CEX price feeds updated every 2.4ms (~400 updates/sec), sourced from Binance, Coinbase, OKX, Bitget, and Kraken via co-located Bolt nodes.'); lines.push(''); lines.push('### x402 API - Pay-Per-Request for AI Agents'); lines.push('**API Type:** REST (via x402 payment-gated proxy)'); lines.push('**Base URL:** `https://x402.goldrush.dev/v1`'); lines.push(''); lines.push('**When to use:** Your AI agent needs blockchain data without API keys, accounts, or subscriptions. Agents pay per request using the x402 protocol with stablecoins on Base.'); lines.push(''); lines.push('**Primary use cases:**'); lines.push('- AI Agents (autonomous blockchain data access with wallet-based payments)'); lines.push('- Serverless Applications (no account setup, pay-as-you-go)'); lines.push('- Prototyping & Experimentation (instant access, no onboarding)'); lines.push(''); lines.push('**How it works:**'); lines.push('1. Agent calls an endpoint without payment'); lines.push('2. Server responds with HTTP 402 (Payment Required) and payment instructions'); lines.push('3. Agent pays with stablecoins on Base, retries with proof of payment'); lines.push('4. Server validates the request *before* charging, then returns data'); lines.push(''); lines.push('**Key details:**'); lines.push('- Transparent reverse proxy in front of `api.covalenthq.com` — same data, same endpoints'); lines.push('- 60+ Foundational API endpoints available'); lines.push('- Request validation before payment (no charge for malformed requests)'); lines.push('- Network: Base Sepolia testnet (Base mainnet coming soon)'); lines.push('- Rate limit: 100 requests/minute per wallet'); 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('### AI Agent Access (x402 — No API Key)'); lines.push('- Discover available endpoints → `GET /v1/x402/endpoints` (free, no payment)'); lines.push('- Search endpoints by keyword → `GET /v1/x402/search?q={query}` (free, no payment)'); lines.push('- Get token balances (pay-per-request) → `GET /v1/{chain}/address/{wallet}/balances_v2/` (x402, fixed-price)'); lines.push('- Get transactions (pay-per-request) → `GET /v1/{chain}/address/{wallet}/transactions_v3/?tier=small` (x402, tiered)'); 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 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 parameter & response field tables from OpenAPI spec const apiDetails = formatEndpointApiDetails(fm.operation_identity); if (apiDetails) { lines.push(apiDetails); 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(''); lines.push('## Connection Details'); lines.push('- **WebSocket Endpoint:** `wss://streaming.goldrushdata.com/graphql`'); lines.push('- **Protocol:** `graphql-transport-ws` (GraphQL over WebSocket)'); lines.push('- **Authentication:** Pass your GoldRush API key as `GOLDRUSH_API_KEY` in the `connection_init` payload'); lines.push('- **Recommended Client:** [@covalenthq/client-sdk](https://www.npmjs.com/package/@covalenthq/client-sdk)'); 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 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 Pipeline API files if (pipelineFiles.length > 0) { lines.push('# Pipeline API Documentation'); lines.push(''); lines.push('The Pipeline API streams blockchain data into customer-managed destinations (ClickHouse, Kafka, Postgres, S3, SQS, webhooks). Pages include normalizer schemas (per-entity column definitions for EVM, HyperCore, and Solana), destination integration guides, ABI decoding reference, SQL transforms, and end-to-end recipes.'); lines.push(''); pipelineFiles.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 || path.basename(file.path, '.mdx')}`); 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(''); }); } // x402 API Documentation section lines.push('# x402 API Documentation'); lines.push(''); lines.push('GoldRush x402 is a payment-gated proxy that provides access to the full GoldRush blockchain data API using the x402 protocol. AI agents pay per request with stablecoins on Base — no API keys, accounts, or subscriptions required. Only a wallet is needed.'); lines.push(''); lines.push('## Overview'); lines.push(''); lines.push('| Item | Value |'); lines.push('|------|-------|'); lines.push('| **Base URL** | `https://x402.goldrush.dev/v1` |'); lines.push('| **Protocol** | x402 (HTTP 402 Payment Required) |'); lines.push('| **Authentication** | None — payment replaces API keys |'); lines.push('| **Payment Network** | Base Sepolia testnet (Base mainnet coming soon) |'); lines.push('| **Payment Method** | Stablecoins on Base |'); lines.push('| **Rate Limit** | 100 requests/minute per wallet |'); lines.push('| **Available Endpoints** | 60+ Foundational API endpoints |'); lines.push('| **Client Libraries** | `@x402/core`, `@x402/evm` |'); lines.push('| **x402 Protocol Spec** | https://x402.org |'); lines.push(''); lines.push('## How It Works'); lines.push(''); lines.push('1. **Request:** Agent calls a GoldRush endpoint on `x402.goldrush.dev` without payment'); lines.push('2. **402 Response:** Server responds with HTTP 402 (Payment Required) including payment instructions (amount, token, recipient)'); lines.push('3. **Payment:** Agent pays with stablecoins on Base and retries the request with proof of payment'); lines.push('4. **Validation:** The proxy validates the request *before* charging — malformed addresses or unsupported chains are rejected without payment'); lines.push('5. **Data:** Server returns the requested blockchain data'); lines.push(''); lines.push('The entire payment flow occurs in a single request-response cycle when using the x402 client libraries.'); lines.push(''); lines.push('## Pricing Model'); lines.push(''); lines.push('### Fixed-Price Endpoints'); lines.push('One price, one call, one response. Used for endpoints like token balances and NFT holdings.'); lines.push(''); lines.push('### Tiered Pricing (Variable-Length Data)'); lines.push('For endpoints returning variable amounts of data (e.g., transaction history), pricing uses tiers:'); lines.push(''); lines.push('| Tier | Items Returned | Use Case |'); lines.push('|------|---------------|----------|'); lines.push('| Small | 1-50 | Quick lookups, recent activity |'); lines.push('| Medium | 51-200 | Standard queries |'); lines.push('| Large | 201-500 | Detailed analysis |'); lines.push('| XL | 501+ | Full history, comprehensive data |'); lines.push(''); lines.push('Select tier via query parameter: `?tier=small`'); lines.push(''); lines.push('### Response Caching'); lines.push('Cached responses cost less than fresh requests. Cache TTLs:'); lines.push('- **Balances:** 30 seconds'); lines.push('- **Pricing data:** 5 minutes'); lines.push(''); lines.push('## Discovery Endpoints (Free)'); lines.push(''); lines.push('These endpoints require no payment and are used to explore available x402 endpoints.'); lines.push(''); lines.push('### List All Available Endpoints'); lines.push(''); lines.push('**Endpoint:** `GET /v1/x402/endpoints`'); lines.push('**Cost:** Free'); lines.push(''); lines.push('```bash'); lines.push('curl https://x402.goldrush.dev/v1/x402/endpoints | jq'); lines.push('```'); lines.push(''); lines.push('Returns a list of all 60+ available endpoints with their pricing and descriptions.'); lines.push(''); lines.push('### Search Endpoints by Keyword'); lines.push(''); lines.push('**Endpoint:** `GET /v1/x402/search?q={query}`'); lines.push('**Cost:** Free'); lines.push(''); lines.push('```bash'); lines.push('curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq'); lines.push('```'); lines.push(''); lines.push('Returns endpoints matching the search query.'); lines.push(''); lines.push('### Get Endpoint Details'); lines.push(''); lines.push('**Endpoint:** `GET /v1/x402/endpoints/{endpoint-name}`'); lines.push('**Cost:** Free'); lines.push(''); lines.push('```bash'); lines.push('curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq'); lines.push('```'); lines.push(''); lines.push('Returns full details for a specific endpoint including pricing, parameters, and response schema.'); lines.push(''); lines.push('## Data Endpoints (Paid via x402)'); lines.push(''); lines.push('All 60+ Foundational API endpoints are accessible through the x402 proxy. The endpoint paths mirror the Foundational API — prepend `https://x402.goldrush.dev` instead of `https://api.covalenthq.com`.'); lines.push(''); lines.push('### Key Endpoints'); lines.push(''); lines.push('- **Token Balances:** `GET /v1/{chainName}/address/{walletAddress}/balances_v2/` (fixed-price)'); lines.push('- **Transaction History:** `GET /v1/{chainName}/address/{walletAddress}/transactions_v3/?tier=small` (tiered)'); lines.push('- **NFT Holdings:** `GET /v1/{chainName}/address/{walletAddress}/balances_nft/` (fixed-price)'); lines.push('- **Token Prices:** `GET /v1/pricing/historical_by_addresses_v2/{chainName}/{quoteCurrency}/{contractAddress}/` (fixed-price)'); lines.push('- **Block Details:** `GET /v1/{chainName}/block_v2/{blockHeight}/` (fixed-price)'); lines.push('- **Token Approvals:** `GET /v1/{chainName}/approvals/{walletAddress}/` (fixed-price)'); lines.push(''); lines.push('For the complete list, use the free discovery endpoint: `GET /v1/x402/endpoints`'); lines.push(''); lines.push('## Code Example'); lines.push(''); lines.push('```typescript'); lines.push('import { HTTPClient } from "@x402/core";'); lines.push('import { ExactEvmScheme } from "@x402/evm";'); lines.push(''); lines.push('const client = new HTTPClient({'); lines.push(' scheme: new ExactEvmScheme({'); lines.push(' network: "eip155:84532", // Base Sepolia'); lines.push(' privateKey: process.env.AGENT_WALLET_KEY,'); lines.push(' }),'); lines.push('});'); lines.push(''); lines.push('const BASE = "https://x402.goldrush.dev/v1";'); lines.push(''); lines.push('// Step 1: Discover available endpoints (free)'); lines.push('const { endpoints } = await client.get(`${BASE}/x402/endpoints`);'); lines.push(''); lines.push('// Step 2: Check token balances across chains'); lines.push('const chains = ["eth-mainnet", "base-mainnet", "arbitrum-mainnet"];'); lines.push('const balances = await Promise.all('); lines.push(' chains.map((chain) =>'); lines.push(' client.get(`${BASE}/${chain}/address/${walletAddress}/balances_v2/`)'); lines.push(' )'); lines.push(');'); lines.push(''); lines.push('// Step 3: Pull transaction history with tier'); lines.push('const txns = await client.get('); lines.push(' `${BASE}/eth-mainnet/address/${walletAddress}/transactions_v3/?tier=small`'); lines.push(');'); lines.push('```'); lines.push(''); lines.push('## x402 vs Traditional API Access'); lines.push(''); lines.push('| Feature | Traditional (API Key) | x402 (Pay-Per-Request) |'); lines.push('|---------|----------------------|----------------------|'); lines.push('| **Authentication** | API key (Bearer token) | Wallet-based payment |'); lines.push('| **Setup** | Account signup required | No account needed |'); lines.push('| **Billing** | Monthly subscription | Per-request payment |'); lines.push('| **Best for** | Applications, backends | AI agents, autonomous systems |'); lines.push('| **Rate Limit** | Tier-dependent (4-50 req/s) | 100 requests/minute per wallet |'); lines.push('| **Payment** | Credit card | Stablecoins on Base |'); 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'); } // ─── Skills Reference Generation ─────────────────────────────────────────── /** * Strip MDX import statements and convert local repository links to bold text. * Preserves same-page section links (#anchors) and external URLs (https://). * Removes [Read more](local-path) links entirely. */ function stripImportsAndLocalLinks(content) { // Protect code blocks from import stripping by replacing them with placeholders const codeBlocks = []; let processed = content.replace(/```[\s\S]*?```/g, (match) => { codeBlocks.push(match); return `__CODE_BLOCK_${codeBlocks.length - 1}__`; }); // Remove MDX import statements (only outside code blocks now) processed = processed.replace(/^import\s+.*$/gm, ''); // Remove [Read more](local-path) links entirely processed = processed.replace(/\[Read more\]\([^)]*\)\s*/gi, ''); // Convert local links [text](/path) or [text](./path) to **text** // Preserves [text](#section) and [text](https://...) processed = processed.replace(/\[([^\]]+)\]\((?!#|https?:\/\/)([^)]+)\)/g, '**$1**'); // Restore code blocks processed = processed.replace(/__CODE_BLOCK_(\d+)__/g, (_, idx) => codeBlocks[idx]); // Clean up excess blank lines processed = processed.replace(/\n{3,}/g, '\n\n'); return processed.trim(); } /** * Read an MDX file, parse frontmatter, strip JSX and local links, return { title, content } */ function readAndStripMdx(filePath) { if (!fs.existsSync(filePath)) { console.warn(`⚠️ File not found: ${filePath}`); return { title: '', content: '' }; } const raw = fs.readFileSync(filePath, 'utf8'); const { data, content } = matter(raw); let stripped = stripMdxToPlainMarkdown(content.trim()); stripped = stripImportsAndLocalLinks(stripped); return { title: data.title || path.basename(filePath, '.mdx'), content: stripped }; } /** * Write a markdown file to a references/ directory. Creates directory if needed. */ function writeReferenceFile(refDir, filename, content) { fs.mkdirSync(refDir, { recursive: true }); const filePath = path.join(refDir, filename); fs.writeFileSync(filePath, content, 'utf8'); return filePath; } /** * Remove all .md files in a references/ directory before writing fresh content */ function clearReferencesDir(dir) { if (!fs.existsSync(dir)) return; fs.readdirSync(dir).forEach(file => { if (file.endsWith('.md')) { fs.unlinkSync(path.join(dir, file)); } }); } /** * Get the foundational API category from a file's directory path */ function getCategoryFromPath(filePath) { const relPath = path.relative(apiReferenceDir, filePath); return relPath.split(path.sep)[0]; } /** * Look up an endpoint's full OpenAPI definition using method + path from operation identity. * Returns { parameters, responseSchema } or null if not found. */ function getEndpointOpenApiDetails(operationIdentity) { if (!operationIdentity || !operationIdentity.method || !operationIdentity.path) { return null; } const pathItem = openapiSpec.paths[operationIdentity.path]; if (!pathItem) return null; const operation = pathItem[operationIdentity.method.toLowerCase()]; if (!operation) return null; const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema || null; return { parameters: operation.parameters || [], responseSchema }; } /** * Format path parameters as a markdown table. */ function formatPathParametersTable(parameters) { const pathParams = parameters.filter(p => p.in === 'path'); if (pathParams.length === 0) return ''; const lines = []; lines.push('### Path Parameters'); lines.push(''); lines.push('| Parameter | Type | Required | Description |'); lines.push('|-----------|------|----------|-------------|'); for (const p of pathParams) { const type = p.schema?.type || 'string'; const required = p.required ? 'Yes' : 'No'; const desc = (p.description || '').replace(/\n/g, ' ').replace(/\|/g, '\\|'); lines.push(`| \`${p.name}\` | ${type} | ${required} | ${desc} |`); } lines.push(''); return lines.join('\n'); } /** * Try to extract a default value from a parameter's description text. * Looks for patterns like "defaults to 100", "default: USD", "Defaults to `false`". */ function extractDefaultFromDescription(description) { if (!description) return '-'; const patterns = [ /[Dd]efaults?\s+to\s+`([^`]+)`/, /[Dd]efaults?\s+to\s+(\S+)/, /[Dd]efault[\s:]+`([^`]+)`/, /[Dd]efault[\s:]+(\S+)/ ]; for (const pattern of patterns) { const match = description.match(pattern); if (match) { return match[1].replace(/[.,;]$/, ''); } } return '-'; } /** * Format query parameters as a markdown table with Default column. */ function formatQueryParametersTable(parameters) { const queryParams = parameters.filter(p => p.in === 'query'); if (queryParams.length === 0) return ''; const lines = []; lines.push('### Query Parameters'); lines.push(''); lines.push('| Parameter | Type | Required | Default | Description |'); lines.push('|-----------|------|----------|---------|-------------|'); for (const p of queryParams) { const type = p.schema?.type || 'string'; const required = p.required ? 'Yes' : 'No'; const defaultVal = extractDefaultFromDescription(p.description); const desc = (p.description || '').replace(/\n/g, ' ').replace(/\|/g, '\\|'); lines.push(`| \`${p.name}\` | ${type} | ${required} | ${defaultVal} | ${desc} |`); } lines.push(''); return lines.join('\n'); } /** * Humanize a field name for use as a sub-table heading. * e.g., "log_events" → "Log Event", "items" → "Item", "gas_metadata" → "Gas Metadata" */ function humanizeFieldName(fieldName) { // Remove trailing 's' for plurals (simple heuristic) let name = fieldName.replace(/_/g, ' '); if (name.endsWith('s') && name.length > 1) { name = name.slice(0, -1); } // Title case return name.replace(/\b\w/g, c => c.toUpperCase()); } /** * Format response fields section with top-level table and one level of nested sub-tables. */ function formatResponseFieldsSection(schema) { if (!schema || !schema.properties) return ''; const lines = []; const nestedTables = []; lines.push('### Response Fields'); lines.push(''); lines.push('| Field | Type | Description |'); lines.push('|-------|------|-------------|'); for (const [fieldName, fieldDef] of Object.entries(schema.properties)) { let type = fieldDef.type || 'unknown'; const desc = (fieldDef.description || '').replace(/\n/g, ' ').replace(/\|/g, '\\|'); // Determine if this field has nested properties we should expand let nestedProperties = null; let nestedHeading = null; if (type === 'array' && fieldDef.items?.type === 'object' && fieldDef.items?.properties) { nestedProperties = fieldDef.items.properties; nestedHeading = `${humanizeFieldName(fieldName)} Fields`; } else if (type === 'object' && fieldDef.properties) { nestedProperties = fieldDef.properties; nestedHeading = `${humanizeFieldName(fieldName)} Fields`; } lines.push(`| \`${fieldName}\` | \`${type}\` | ${desc} |`); // Collect nested table for later if (nestedProperties) { const subLines = []; subLines.push(`### ${nestedHeading}`); subLines.push(''); subLines.push('| Field | Type | Description |'); subLines.push('|-------|------|-------------|'); for (const [subName, subDef] of Object.entries(nestedProperties)) { // At this depth, don't expand further — just show the type let subType = subDef.type || 'unknown'; if (subType === 'array' && subDef.items?.type) { subType = `array<${subDef.items.type}>`; } const subDesc = (subDef.description || '').replace(/\n/g, ' ').replace(/\|/g, '\\|'); subLines.push(`| \`${subName}\` | \`${subType}\` | ${subDesc} |`); } subLines.push(''); nestedTables.push(subLines.join('\n')); } } lines.push(''); // Append nested tables after the main table if (nestedTables.length > 0) { lines.push(nestedTables.join('\n')); } return lines.join('\n'); } /** * Orchestrator: combine OpenAPI parameter and response field tables for an endpoint. * Returns combined markdown string, or empty string if no OpenAPI data found. */ function formatEndpointApiDetails(operationIdentity) { const details = getEndpointOpenApiDetails(operationIdentity); if (!details) return ''; const sections = []; const pathTable = formatPathParametersTable(details.parameters); if (pathTable) sections.push(pathTable); const queryTable = formatQueryParametersTable(details.parameters); if (queryTable) sections.push(queryTable); const responseFields = formatResponseFieldsSection(details.responseSchema); if (responseFields) sections.push(responseFields); return sections.join('\n'); } /** * Bump all markdown headings down by one level (## → ###, ### → ####, etc.). * Only affects lines starting with # that are actual headings (not inside code blocks). */ function bumpHeadingLevels(markdown) { const lines = markdown.split('\n'); let inCodeBlock = false; return lines.map(line => { if (line.startsWith('```')) { inCodeBlock = !inCodeBlock; } if (!inCodeBlock && /^#{1,5}\s/.test(line)) { return '#' + line; } return line; }).join('\n'); } /** * Format a single endpoint as a markdown section for reference files */ function formatEndpointSection(file) { const lines = []; const fm = file.frontmatter; lines.push(`## ${fm.title}`); lines.push(''); if (fm.operation_identity) { const opId = fm.operation_identity; lines.push('**Operation Identity:**'); if (opId.operation_id) lines.push(`- Operation ID: \`${opId.operation_id}\``); if (opId.method && opId.path) lines.push(`- \`${opId.method} ${opId.path}\``); if (opId.type && opId.field) lines.push(`- GraphQL \`${opId.type}\` → field: \`${opId.field}\``); if (opId.sdk_service && opId.sdk_method) lines.push(`- SDK: \`${opId.sdk_service}.${opId.sdk_method}()\``); lines.push(''); } const meta = []; if (fm.endpoint_role) meta.push(`**Role:** ${fm.endpoint_role}`); if (fm.credit_cost) meta.push(`**Credit Cost:** ${fm.credit_cost}`); if (fm.api_type) meta.push(`**API Type:** ${fm.api_type}`); if (fm.beta) meta.push(`**Status:** Beta`); if (meta.length > 0) { lines.push(meta.join(' | ')); lines.push(''); } if (fm.use_cases && fm.use_cases.length > 0) { lines.push(`**Use Cases:** ${fm.use_cases.join(', ')}`); lines.push(''); } if (fm.chains) { if (fm.chains === 'all') { lines.push('**Chains:** All supported chains'); } else if (Array.isArray(fm.chains) && fm.chains.length > 0) { lines.push(`**Chains:** ${fm.chains.slice(0, 10).join(', ')}${fm.chains.length > 10 ? ` (+${fm.chains.length - 10} more)` : ''}`); } lines.push(''); } // Parameter & Response Field tables from OpenAPI spec const apiDetails = formatEndpointApiDetails(fm.operation_identity); if (apiDetails) { lines.push(apiDetails); lines.push(''); } lines.push(bumpHeadingLevels(stripImportsAndLocalLinks(stripMdxToPlainMarkdown(file.content)))); lines.push(''); lines.push('---'); lines.push(''); return lines.join('\n'); } /** * Generate workflows content (decision tree + multi-endpoint workflows + troubleshooting) */ function generateWorkflowsContent() { const lines = []; lines.push('# Workflows & Decision Trees'); lines.push(''); 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, 1 per call)'); lines.push('- Get historical balance at block → `getHistoricalTokenBalancesForWalletAddress` (specialized, 1 per call)'); lines.push('- Get portfolio value over time → `getHistoricalPortfolioForWalletAddress` (primary, 2 per item)'); lines.push('- Get native token only → `getNativeTokenBalance` (primary, 0.5 per call)'); lines.push(''); lines.push('### Transaction Queries'); lines.push('- Get recent transactions → `getRecentTransactionsForAddress` (primary, 0.1 per item)'); lines.push('- Get paginated history → `getTransactionsForAddressV3` (primary, 0.1 per item)'); lines.push('- Get single transaction details → `getTransaction` (primary, 0.1 per call)'); lines.push('- Get ERC20 transfers → `getErc20TransfersForWalletAddress` (primary, 0.05 per item)'); lines.push('- Get transaction summary → `getTransactionSummary` (primary, 1 per call)'); lines.push(''); lines.push('### Security & Approvals'); lines.push('- Check token approvals → `getApprovals` (primary, 2 per call)'); lines.push('- Check NFT approvals → `getNftApprovals` (primary, 1 per call)'); lines.push(''); lines.push('### NFT & Token Queries'); lines.push('- Get NFT holdings → `getNftsForAddress` (primary, 1 per call)'); lines.push('- Get token holders → `getTokenHoldersV2ForTokenAddress` (specialized, 0.02 per item)'); lines.push(''); lines.push('### Multi-chain Queries'); lines.push('- Check which chains address is active on → `getAddressActivity` (primary, 0.5 per call)'); lines.push('- Get balances across chains → `getMultiChainBalances` (specialized, 2.5 per call)'); lines.push('- Get transactions across chains → `getMultiChainMultiAddressTransactions` (specialized, 0.25 per item)'); lines.push(''); lines.push('### Token & Price Queries'); lines.push('- Get token price history → `getTokenPrices` (primary, 1 per call)'); lines.push('- Get DEX pool prices → `getPoolSpotPrices` (specialized, Foundational only)'); lines.push(''); lines.push('### Block & Event Queries'); lines.push('- Get block details → `getBlock` (specialized, 1 per call)'); lines.push('- Get block heights by date → `getBlockHeights` (specialized, 1 per call)'); lines.push('- Get contract event logs → `getLogEventsByAddress` (specialized, 0.01 per item)'); lines.push('- Get logs by topic hash → `getLogEventsByTopicHash` (specialized, 0.01 per item)'); lines.push(''); lines.push('---'); lines.push(''); lines.push('## Common Multi-Endpoint Workflows'); 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:** 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'); 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'); 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(''); lines.push('## Common Errors & Troubleshooting'); lines.push(''); lines.push(generateTroubleshootingSection()); return lines.join('\n'); } /** * Generate Foundational API reference files */ function generateFoundationalReferences(apiFiles, chainFiles) { // Group files by category based on directory structure const filesByCategory = {}; apiFiles.forEach(file => { const cat = getCategoryFromPath(file.path); if (!filesByCategory[cat]) filesByCategory[cat] = []; filesByCategory[cat].push(file); }); // 1. overview.md const fOverview = readAndStripMdx(foundationalOverviewPath); const fQuickstart = readAndStripMdx(foundationalQuickstartPath); const fAuth = readAndStripMdx(foundationalAuthPath); writeReferenceFile(foundationalSkillsRefDir, 'overview.md', [ '# GoldRush Foundational API Overview', '', '## Quick Reference', '', '| Item | Value |', '|------|-------|', '| **Base URL** | `https://api.covalenthq.com/v1` |', '| **Protocol** | HTTPS (REST) |', '| **Authentication** | Bearer token in `Authorization` header |', '| **API Key** | Sign up at goldrush.dev/platform (starts with `cqt_` or `ckey_`) |', '| **SDK** | `@covalenthq/client-sdk` (TypeScript) |', '| **Response Format** | JSON |', '| **Rate Limits** | 4 RPS (Vibe Coding) / 50 RPS (Professional) |', '', '---', '', fOverview.content, '', '---', '', fQuickstart.content, '', '---', '', fAuth.content, ].join('\n')); // 2. endpoints-balances.md const balancesContent = ['# Balance Endpoints', '']; (filesByCategory['balances'] || []).forEach(file => { balancesContent.push(formatEndpointSection(file)); }); const btcSupport = readAndStripMdx(bitcoinSupportPath); if (btcSupport.content) { balancesContent.push('# Enhanced Bitcoin Support', '', btcSupport.content, ''); } writeReferenceFile(foundationalSkillsRefDir, 'endpoints-balances.md', balancesContent.join('\n')); // 3. endpoints-transactions.md const txContent = ['# Transaction Endpoints', '']; (filesByCategory['transactions'] || []).forEach(file => { txContent.push(formatEndpointSection(file)); }); writeReferenceFile(foundationalSkillsRefDir, 'endpoints-transactions.md', txContent.join('\n')); // 4. endpoints-nft-security-crosschain.md const nscContent = ['# NFT, Security & Cross-Chain Endpoints', '']; ['nft', 'security', 'cross-chain'].forEach(cat => { (filesByCategory[cat] || []).forEach(file => { nscContent.push(formatEndpointSection(file)); }); }); writeReferenceFile(foundationalSkillsRefDir, 'endpoints-nft-security-crosschain.md', nscContent.join('\n')); // 5. endpoints-utility.md const utilContent = ['# Utility Endpoints', '']; (filesByCategory['utility'] || []).forEach(file => { utilContent.push(formatEndpointSection(file)); }); const spamLists = readAndStripMdx(spamListsPath); if (spamLists.content) { utilContent.push('# Enhanced Spam Lists', '', spamLists.content, ''); } writeReferenceFile(foundationalSkillsRefDir, 'endpoints-utility.md', utilContent.join('\n')); // 6. integration-guide.md const integrationGuide = generateLlmIntegrationGuide(chainFiles); const errorHandling = readAndStripMdx(errorHandlingPath); const faq = readAndStripMdx(faqPath); writeReferenceFile(foundationalSkillsRefDir, 'integration-guide.md', [ integrationGuide, '', '---', '', '# Error Handling & Troubleshooting', '', errorHandling.content, '', '---', '', '# Frequently Asked Questions', '', faq.content, ].join('\n')); // 7. workflows.md writeReferenceFile(foundationalSkillsRefDir, 'workflows.md', generateWorkflowsContent()); const fileCount = fs.readdirSync(foundationalSkillsRefDir).filter(f => f.endsWith('.md')).length; console.log(` 📁 Foundational API: ${fileCount} reference files`); } /** * Generate Streaming API reference files */ function generateStreamingReferences(streamingFiles, chainFiles) { // Build chains & DEXes data for the overview const streamingChains = chainFiles.filter(c => c.datoRecord && c.datoRecord.streamingapi ); const chainsSection = []; chainsSection.push('## Supported Chains & DEXes'); chainsSection.push(''); chainsSection.push('### Chain Name Format'); chainsSection.push(''); chainsSection.push('The Streaming API uses `SCREAMING_SNAKE_CASE` enum names, unlike the REST API which uses `kebab-case`.'); chainsSection.push(''); chainsSection.push('| REST API (kebab-case) | Streaming API (SCREAMING_SNAKE_CASE) |'); chainsSection.push('|----------------------|--------------------------------------|'); streamingChains.forEach(chain => { const kebab = chain.frontmatter.chain_name; const screaming = kebab.toUpperCase().replace(/-/g, '_'); chainsSection.push(`| \`${kebab}\` | \`${screaming}\` |`); }); chainsSection.push(''); // Load streaming chains/DEXes data from the pipeline-generated JSON if (fs.existsSync(streamingChainsDexesPath)) { const chainsDexes = JSON.parse(fs.readFileSync(streamingChainsDexesPath, 'utf8')); const sorted = [...chainsDexes].sort((a, b) => a.chain_name.localeCompare(b.chain_name)); chainsSection.push('### Supported DEXes by Chain'); chainsSection.push(''); chainsSection.push('| Chain | Supported DEXes |'); chainsSection.push('|-------|----------------|'); sorted.forEach(entry => { chainsSection.push(`| \`${entry.chain_name}\` | ${entry.protocols.map(p => `\`${p}\``).join(', ')} |`); }); chainsSection.push(''); } chainsSection.push('### Capabilities Matrix'); chainsSection.push(''); chainsSection.push('| Chain | Chain Name | Chain ID | Block Time |'); chainsSection.push('|-------|-----------|----------|------------|'); [...streamingChains].sort((a, b) => (a.frontmatter.title || '').localeCompare(b.frontmatter.title || '')) .forEach(chain => { const fr = chain.frontmatter; const dato = chain.datoRecord; const blockTime = dato && dato.blocktime ? `${dato.blocktime}s` : 'N/A'; chainsSection.push(`| ${fr.title} | \`${fr.chain_name}\` | ${fr.chain_id || 'N/A'} | ${blockTime} |`); }); chainsSection.push(''); // 1. overview.md (includes chains data — no separate chains.md) const sOverview = readAndStripMdx(streamingOverviewPath); const sQuickstart = readAndStripMdx(streamingQuickstartPath); const sAuth = readAndStripMdx(streamingAuthPath); writeReferenceFile(streamingSkillsRefDir, 'overview.md', [ '# GoldRush Streaming API Overview', '', '## Quick Reference', '', '| Item | Value |', '|------|-------|', '| **WebSocket URL** | `wss://streaming.goldrushdata.com/graphql` |', '| **Protocol** | GraphQL over WebSocket (`graphql-transport-ws`) |', '| **Authentication** | API key via `connection_init` payload as `GOLDRUSH_API_KEY` |', '| **SDK** | `@covalenthq/client-sdk` (TypeScript) |', '| **Endpoint Types** | `subscription` (real-time push), `query` (one-time fetch) |', '| **Chain Name Format** | `SCREAMING_SNAKE_CASE` (e.g. `ETH_MAINNET`, `BASE_MAINNET`) |', '', '---', '', sOverview.content, '', '---', '', chainsSection.join('\n'), '', '---', '', sQuickstart.content, '', '---', '', sAuth.content, ].join('\n')); // 2. endpoints.md const endpointsContent = ['# Streaming API Endpoints', '']; endpointsContent.push('## Connection Details'); endpointsContent.push('- **WebSocket:** `wss://streaming.goldrushdata.com/graphql`'); endpointsContent.push('- **Protocol:** `graphql-transport-ws`'); endpointsContent.push('- **Auth:** `GOLDRUSH_API_KEY` in `connection_init` payload'); endpointsContent.push(''); streamingFiles.forEach(file => { endpointsContent.push(formatEndpointSection(file)); }); const decodedEvents = readAndStripMdx(streamingDecodedEventsPath); if (decodedEvents.content) { endpointsContent.push('# Decoded Events', '', decodedEvents.content, ''); } writeReferenceFile(streamingSkillsRefDir, 'endpoints.md', endpointsContent.join('\n')); // 3. sdk-guide.md const sdk = readAndStripMdx(streamingSdkPath); const graphqlEndpointsDoc = readAndStripMdx(graphqlEndpointsPath); writeReferenceFile(streamingSkillsRefDir, 'sdk-guide.md', [ '# Streaming API SDK Guide', '', sdk.content, '', '---', '', '# GraphQL Endpoints Reference', '', graphqlEndpointsDoc.content, '', '---', '', '## Streaming-Specific Troubleshooting', '', '### WebSocket Connection Issues', '- Verify URL: `wss://streaming.goldrushdata.com/graphql`', '- Set protocol header: `Sec-WebSocket-Protocol: graphql-transport-ws`', '- Auth errors only surface on subscription start, not on WebSocket connect', '', '### Chain Name Format', '- Streaming API uses `SCREAMING_SNAKE_CASE`: `ETH_MAINNET`, `BASE_MAINNET`', '- Foundational API uses `kebab-case`: `eth-mainnet`, `base-mainnet`', '- Using the wrong format will silently fail (no data received)', '', '### Subscription Not Receiving Data', '- Check chain supports Streaming (not all chains do)', '- Verify chain name format (SCREAMING_SNAKE_CASE)', '- Ensure API key is valid (connection_ack always succeeds regardless)', ].join('\n')); const fileCount = fs.readdirSync(streamingSkillsRefDir).filter(f => f.endsWith('.md')).length; console.log(` 📁 Streaming API: ${fileCount} reference files`); } /** * Generate x402 reference files */ function generateX402References() { // 1. overview.md const xOverview = readAndStripMdx(x402OverviewPath); const xQuickstart = readAndStripMdx(x402QuickstartPath); writeReferenceFile(x402SkillsRefDir, 'overview.md', [ '# GoldRush x402 Overview', '', '## Quick Reference', '', '| Item | Value |', '|------|-------|', '| **Base URL** | `https://x402.goldrush.dev/v1` |', '| **Protocol** | x402 (HTTP 402 Payment Required) |', '| **Authentication** | None — wallet-based micropayments replace API keys |', '| **Payment Network** | Base Sepolia testnet (Base mainnet coming soon) |', '| **Payment Method** | Stablecoins on Base |', '| **Rate Limit** | 100 requests/minute per wallet |', '| **Available Endpoints** | 60+ Foundational API endpoints |', '| **Client Libraries** | `@x402/core`, `@x402/evm` |', '', '## Pricing Model', '', '- **Fixed-Price:** One price per call (e.g., token balances, NFT holdings)', '- **Tiered Pricing:** For variable-length data — Small (1-50), Medium (51-200), Large (201-500), XL (501+)', '- **Response Caching:** Cached responses cost less (TTLs: 30s for balances, 5m for pricing)', '', '## Response Headers', '', '```', 'X-Pricing-Model: fixed', 'X-Base-Price: 0.000001', 'X-Cache: MISS', 'X-RateLimit-Remaining: 97', '```', '', '---', '', xOverview.content, '', '---', '', xQuickstart.content, ].join('\n')); // 2. ai-agents.md const aiAgents = readAndStripMdx(x402AiAgentsPath); writeReferenceFile(x402SkillsRefDir, 'ai-agents.md', [ '# x402 for AI Agents', '', '## Agent Workflow', '', '1. **Discover** — Call free discovery API to find endpoints', '2. **Evaluate** — Search and check pricing before committing', '3. **Pay** — Sign payment and get data in single request-response cycle', '4. **Consume** — Parse standard GoldRush JSON responses', '', '## x402 vs API Key for Agents', '', '| Concern | API Key | x402 |', '|---------|---------|------|', '| Provisioning | Requires signup, key management | Wallet is the credential |', '| Budget control | Monthly plan, overage charges | Pay exactly per request |', '| Human involvement | Account creation, billing setup | None — fully autonomous |', '| Discovery | Read docs or hardcode endpoints | Programmatic endpoint discovery |', '| Multi-agent | Share key or provision per agent | Each agent gets its own wallet |', '', '## Rate Limits', '', '100 requests/minute per wallet. Check `X-RateLimit-Remaining` response header.', '', '---', '', aiAgents.content, ].join('\n')); // 3. endpoints.md writeReferenceFile(x402SkillsRefDir, 'endpoints.md', [ '# x402 Endpoints', '', '## Discovery Endpoints (Free)', '', 'These endpoints require no payment and help agents explore available x402 endpoints.', '', '### List All Available Endpoints', '', '**Endpoint:** `GET /v1/x402/endpoints`', '**Cost:** Free', '', '```bash', 'curl https://x402.goldrush.dev/v1/x402/endpoints | jq', '```', '', '### Search Endpoints by Keyword', '', '**Endpoint:** `GET /v1/x402/search?q={query}`', '**Cost:** Free', '', '```bash', 'curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq', '```', '', '### Get Endpoint Details', '', '**Endpoint:** `GET /v1/x402/endpoints/{endpoint-name}`', '**Cost:** Free', '', '```bash', 'curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq', '```', '', '---', '', '## Data Endpoints (Paid via x402)', '', 'All 60+ Foundational API endpoints are available through the x402 proxy. Endpoint paths mirror the Foundational API.', '', '**Base URL:** `https://x402.goldrush.dev/v1` (replaces `https://api.covalenthq.com/v1`)', '', '### Key Data Endpoints', '', '| Endpoint | Path | Pricing |', '|----------|------|---------|', '| Token Balances | `/v1/{chain}/address/{wallet}/balances_v2/` | Fixed |', '| Native Balance | `/v1/{chain}/address/{wallet}/balances_native/` | Fixed |', '| Transaction History | `/v1/{chain}/address/{wallet}/transactions_v3/?tier={tier}` | Tiered |', '| Recent Transactions | `/v1/{chain}/address/{wallet}/transactions_v3/?tier=small` | Tiered |', '| Single Transaction | `/v1/{chain}/transaction_v2/{txHash}/` | Fixed |', '| NFT Holdings | `/v1/{chain}/address/{wallet}/balances_nft/` | Fixed |', '| Token Prices | `/v1/pricing/historical_by_addresses_v2/{chain}/{currency}/{contract}/` | Fixed |', '| Block Details | `/v1/{chain}/block_v2/{blockHeight}/` | Fixed |', '| Token Approvals | `/v1/{chain}/approvals/{wallet}/` | Fixed |', '| ERC20 Transfers | `/v1/{chain}/address/{wallet}/transfers_v2/` | Tiered |', '| Cross-Chain Activity | `/v1/address/{wallet}/activity/` | Fixed |', '| Multi-Chain Balances | `/v1/address/{wallet}/balances_multi/` | Fixed |', '', 'For the complete list, use: `GET /v1/x402/endpoints`', '', '---', '', '> **Note:** For detailed endpoint documentation (parameters, response schemas, use cases),', '> see the **GoldRush Foundational API** skill reference files. The x402 proxy serves the', '> exact same endpoints with the same parameters and response format.', ].join('\n')); const fileCount = fs.readdirSync(x402SkillsRefDir).filter(f => f.endsWith('.md')).length; console.log(` 📁 x402: ${fileCount} reference files`); } /** * Main entry point for skills reference generation. * Called from main() after llms.txt / llms-full.txt generation. */ /** * Generate CLI reference files */ function generateCliReferences() { const cliOverview = readAndStripMdx(cliOverviewPath); const cliQuickstart = readAndStripMdx(cliQuickstartPath); const cliCommands = readAndStripMdx(cliCommandsPath); writeReferenceFile(cliSkillsRefDir, 'overview.md', [ '# GoldRush CLI', '', '## Quick Reference', '', '| Item | Value |', '|------|-------|', '| **Install** | `npx @covalenthq/goldrush-cli` |', '| **Authentication** | `goldrush auth` (stores key in OS keychain) |', '| **MCP Setup** | `goldrush install` (registers as tool for Claude) |', '| **Commands** | 17 commands across portfolio, market, trading, and utilities |', '| **Chains** | 100+ chains (same as Foundational API) |', '| **Streaming** | Real-time data via Streaming API for `new_pairs`, `ohlcv_pairs`, `watch` |', '', '---', '', cliOverview.content, '', '---', '', cliQuickstart.content, '', '---', '', '# Command Reference', '', cliCommands.content, ].join('\n')); const fileCount = fs.readdirSync(cliSkillsRefDir).filter(f => f.endsWith('.md')).length; console.log(` 📁 CLI: ${fileCount} reference files`); } /** * Main entry point for skills reference generation. * Called from main() after llms.txt / llms-full.txt generation. */ function generateSkillsReferences(apiFiles, streamingFiles, chainFiles) { clearReferencesDir(foundationalSkillsRefDir); clearReferencesDir(streamingSkillsRefDir); clearReferencesDir(x402SkillsRefDir); clearReferencesDir(cliSkillsRefDir); generateFoundationalReferences(apiFiles, chainFiles); generateStreamingReferences(streamingFiles, chainFiles); generateX402References(); generateCliReferences(); } /** * 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'; }); const pipelineMdxFiles = findMdxFiles(pipelineApiDir); console.log(`📊 Found ${apiMdxFiles.length} Foundational API files`); console.log(`📊 Found ${streamingMdxFiles.length} Streaming API files`); console.log(`📊 Found ${pipelineMdxFiles.length} Pipeline 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)); const enrichedPipelineFiles = pipelineMdxFiles.map(parsePipelineFile); // 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, enrichedPipelineFiles, enrichedChainFiles); fs.writeFileSync(llmsTxtPath, llmsTxt, 'utf8'); console.log('✅ Created:', llmsTxtPath); console.log('✍️ Generating llms-full.txt...'); const llmsFullTxt = generateLlmsFullTxt(enrichedApiFiles, enrichedStreamingFiles, enrichedPipelineFiles, enrichedChainFiles); fs.writeFileSync(llmsFullTxtPath, llmsFullTxt, 'utf8'); console.log('✅ Created:', llmsFullTxtPath); console.log('✍️ Generating skills reference files...'); generateSkillsReferences(enrichedApiFiles, enrichedStreamingFiles, enrichedChainFiles); console.log('✅ Skills reference files generated'); 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(` - ${enrichedPipelineFiles.length} Pipeline API pages`); console.log(` - ${enrichedChainFiles.length} Chains`); } // Run the script if (require.main === module) { main(); } module.exports = { generateLlmsTxt, generateLlmsFullTxt, generateSkillsReferences, parseAndEnrichEndpoint, parseAndEnrichChain, parsePipelineFile, findMdxFiles };

Foundational API

Streaming API

Pipeline API

Documentation Index

​Fields

Fields