const fs = require('fs'); const path = require('path'); const matter = require('gray-matter'); const { HYPERCORE_START_BLOCK, HYPERCORE_START_TIMESTAMP } = require('./lib/hypercore-coverage'); // 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 hyperliquidDocsDir = path.resolve(__dirname, '../goldrush-hyperliquid'); const hyperliquidInfoApiReferenceDir = path.resolve(__dirname, '../api-reference/hyperliquid-info'); const hyperliquidWebsocketApiReferenceDir = path.resolve(__dirname, '../api-reference/hyperliquid-websocket'); const solanaDocsDir = path.resolve(__dirname, '../goldrush-solana'); 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'); const hyperliquidSkillsRefDir = path.resolve(skillsDir, 'goldrush-hyperliquid/references'); const jsonRpcSkillsRefDir = path.resolve(skillsDir, 'goldrush-json-rpc/references'); const solanaSkillsRefDir = path.resolve(skillsDir, 'goldrush-solana/references'); // JSON-RPC source paths const rpcOverviewPath = path.resolve(__dirname, '../goldrush-json-rpc/overview.mdx'); const rpcQuickstartPath = path.resolve(__dirname, '../goldrush-json-rpc/quickstart.mdx'); const rpcAuthPath = path.resolve(__dirname, '../goldrush-json-rpc/authentication.mdx'); const rpcEdgeTierPath = path.resolve(__dirname, '../goldrush-json-rpc/edge-tier.mdx'); const rpcDebugTracePath = path.resolve(__dirname, '../goldrush-json-rpc/debug-trace.mdx'); const rpcPricingPath = path.resolve(__dirname, '../goldrush-json-rpc/pricing.mdx'); const rpcMethodsYamlPath = path.resolve(__dirname, '../api-defn/rpc/methods.yaml'); const rpcSolanaMethodsYamlPath = path.resolve(__dirname, '../api-defn/rpc/solana-methods.yaml'); // 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 hyperliquidOverviewPath = path.resolve(__dirname, '../goldrush-hyperliquid/overview.mdx'); const hyperliquidQuickstartPath = path.resolve(__dirname, '../goldrush-hyperliquid/quickstart.mdx'); const hyperliquidInfoOverviewPath = path.resolve(__dirname, '../goldrush-hyperliquid/info-api/overview.mdx'); const hyperliquidInfoMigrationPath = path.resolve(__dirname, '../goldrush-hyperliquid/info-api/migration.mdx'); const hyperliquidInfoSdkPath = path.resolve(__dirname, '../goldrush-hyperliquid/info-api/sdk-compatibility.mdx'); const hyperliquidInfoLimitsPath = path.resolve(__dirname, '../goldrush-hyperliquid/info-api/limits.mdx'); const hyperliquidStreamingWalletPath = path.resolve(__dirname, '../goldrush-hyperliquid/streaming/wallet-firehose.mdx'); const hyperliquidStreamingHip3Path = path.resolve(__dirname, '../goldrush-hyperliquid/streaming/hip3-markets.mdx'); const hyperliquidStreamingHip4Path = path.resolve(__dirname, '../goldrush-hyperliquid/streaming/hip4-markets.mdx'); const hyperliquidStreamingLiquidationsPath = path.resolve(__dirname, '../goldrush-hyperliquid/streaming/liquidations-vaults.mdx'); const hyperliquidWebsocketOverviewPath = path.resolve(__dirname, '../goldrush-hyperliquid/websocket-api/overview.mdx'); const hyperliquidWebsocketMigrationPath = path.resolve(__dirname, '../goldrush-hyperliquid/websocket-api/migration.mdx'); const hyperliquidWebsocketSdkPath = path.resolve(__dirname, '../goldrush-hyperliquid/websocket-api/sdk-compatibility.mdx'); const hyperliquidWebsocketLimitsPath = path.resolve(__dirname, '../goldrush-hyperliquid/websocket-api/limits.mdx'); const hyperliquidWebsocketL2RecipePath = path.resolve(__dirname, '../goldrush-hyperliquid/websocket-api/l2-book.mdx'); const hyperliquidWebsocketL2DiffRecipePath = path.resolve(__dirname, '../goldrush-hyperliquid/websocket-api/l2-book-diff.mdx'); const hyperliquidWebsocketL4RecipePath = path.resolve(__dirname, '../goldrush-hyperliquid/websocket-api/l4-book.mdx'); const solanaOverviewPath = path.resolve(__dirname, '../goldrush-solana/overview.mdx'); const solanaQuickstartPath = path.resolve(__dirname, '../goldrush-solana/quickstart.mdx'); const solanaRoadmapPath = path.resolve(__dirname, '../goldrush-solana/roadmap.mdx'); const solanaAnalyticsAppPath = path.resolve(__dirname, '../goldrush-solana/analytics-app.mdx'); const solanaFoundationalOverviewPath = path.resolve(__dirname, '../goldrush-solana/foundational/overview.mdx'); const solanaFoundationalWalletPath = path.resolve(__dirname, '../goldrush-solana/foundational/wallet.mdx'); const solanaFoundationalTransactionsPath = path.resolve(__dirname, '../goldrush-solana/foundational/transactions.mdx'); const solanaFoundationalNftsPath = path.resolve(__dirname, '../goldrush-solana/foundational/nfts.mdx'); const solanaFoundationalPricingPath = path.resolve(__dirname, '../goldrush-solana/foundational/pricing.mdx'); const solanaFoundationalNativePath = path.resolve(__dirname, '../goldrush-solana/foundational/solana-native.mdx'); const solanaStreamingDexFirehosePath = path.resolve(__dirname, '../goldrush-solana/streaming/dex-firehose.mdx'); const solanaStreamingPumpFunPath = path.resolve(__dirname, '../goldrush-solana/streaming/pumpfun-launchpad.mdx'); const solanaStreamingWalletPath = path.resolve(__dirname, '../goldrush-solana/streaming/wallet-activity.mdx'); const solanaStreamingOhlcvPath = path.resolve(__dirname, '../goldrush-solana/streaming/ohlcv-markets.mdx'); const solanaStreamingNftMintsPath = path.resolve(__dirname, '../goldrush-solana/streaming/nft-mints.mdx'); const solanaWarehouseDexSwapsPath = path.resolve(__dirname, '../goldrush-solana/warehouse/dex-swaps.mdx'); const solanaWarehouseSplTransfersPath = path.resolve(__dirname, '../goldrush-solana/warehouse/spl-transfers.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 from DatoCMS, matching the per-product MDX generators: * - fixed model → "{rate} per call" (convert-openapi.js) * - linear model → "{rate} per {creditrateunit}" (convert-streaming.js, convert-openapi.js) */ function getCreditCostDisplay(endpoint) { if (endpoint.creditrate === null || endpoint.creditrate === undefined) { return null; } const cost = endpoint.creditrate; const model = endpoint.creditratemodel; const unit = endpoint.creditrateunit; if (model === 'fixed') return `${cost} per call`; if (model === 'linear') return unit ? `${cost} per ${unit}` : `${cost} per item`; 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.grouping === 'streaming' ? false : (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 substituteHypercoreCoverageTokens(content) { // Inline the HyperCore coverage constants and snippet components since the // MDX stripper doesn't evaluate JSX. Source of truth: s/lib/hypercore-coverage.js. return content .replace(//g, `GoldRush retains every fill, every funding payment, and every ledger event going back to HyperCore block **${HYPERCORE_START_BLOCK}** (${HYPERCORE_START_TIMESTAMP}).`) .replace(//g, `block \`${HYPERCORE_START_BLOCK}\` (\`${HYPERCORE_START_TIMESTAMP}\`)`) .replace(/\{HYPERCORE_START_BLOCK\}/g, HYPERCORE_START_BLOCK) .replace(/\{HYPERCORE_START_TIMESTAMP\}/g, HYPERCORE_START_TIMESTAMP); } function stripMdxToPlainMarkdown(content) { let processed = substituteHypercoreCoverageTokens(content); // Drop MDX import statements (single-line and multi-line `import { ... } from "...";`). // They're JS, not markdown — meaningless once JSX is stripped. const codeBlocks = []; processed = processed.replace(/```[\s\S]*?```/g, (m) => { codeBlocks.push(m); return `__CODE_BLOCK_${codeBlocks.length - 1}__`; }); processed = processed.replace(/^import\s+[\s\S]+?from\s+["'][^"']+["'];?\s*$/gm, ''); processed = processed.replace(/__CODE_BLOCK_(\d+)__/g, (_, idx) => codeBlocks[idx]); // 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 trimTrailingWhitespace(content) { return content.split('\n').map(line => line.trimEnd()).join('\n').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 `' }, { 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 ` |'); 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: "'); lines.push(''); lines.push('# CORRECT'); lines.push('curl -H "Authorization: Bearer "'); 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 " 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, hyperliquidFiles, solanaFiles, chainFiles) { const lines = []; const BASE_URL = 'https://goldrush.dev/docs/'; const linkItem = (title, urlPath, parts) => { const desc = parts.filter(Boolean).join(' · '); const link = `- [${title}](${BASE_URL}${urlPath})`; return desc ? `${link}: ${desc}` : link; }; 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 ` (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; const opId = fm.operation_identity || {}; lines.push(linkItem(fm.title, urlPath, [ opId.method && opId.path && `${opId.method} ${opId.path}`, fm.endpoint_role && `role: ${fm.endpoint_role}`, fm.category && `category: ${fm.category}`, fm.credit_cost != null && `credit: ${fm.credit_cost}`, opId.sdk_service && opId.sdk_method && `SDK: ${opId.sdk_service}.${opId.sdk_method}()`, opId.operation_id && `op: ${opId.operation_id}`, fm.use_cases?.length && `uses: ${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(linkItem('List all available x402 endpoints', 'goldrush-x402/overview', ['GET /v1/x402/endpoints', 'Free', 'role: primary'])); lines.push(linkItem('Search x402 endpoints', 'goldrush-x402/overview', ['GET /v1/x402/search?q={query}', 'Free', 'role: primary'])); lines.push(linkItem('Get details for a specific x402 endpoint', 'goldrush-x402/overview', ['GET /v1/x402/endpoints/{endpoint-name}', 'Free', '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(linkItem('Get token balances for address (x402)', 'goldrush-x402/overview', ['GET /v1/{chainName}/address/{walletAddress}/balances_v2/', 'pricing: fixed per call'])); lines.push(linkItem('Get recent transactions for address (x402)', 'goldrush-x402/overview', ['GET /v1/{chainName}/address/{walletAddress}/transactions_v3/', 'pricing: tiered (?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; const opId = fm.operation_identity || {}; lines.push(linkItem(fm.title, urlPath, [ fm.api_type, opId.field && `field: ${opId.field}`, fm.endpoint_role && `role: ${fm.endpoint_role}`, fm.category && `category: ${fm.category}`, fm.beta && 'status: beta', opId.sdk_service && opId.sdk_method && `SDK: ${opId.sdk_service}.${opId.sdk_method}()`, opId.operation_id && `op: ${opId.operation_id}`, fm.use_cases?.length && `uses: ${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(linkItem( fm.title || path.basename(file.path, '.mdx'), urlPath, [fm.description] )); }); lines.push(''); } // Process Hyperliquid API files if (hyperliquidFiles.length > 0) { lines.push('## Hyperliquid API'); lines.push(''); lines.push('Complete data layer for Hyperliquid: a no-rate-limit drop-in `/info` API at `https://hypercore.goldrushdata.com/info`, real-time HyperCore wallet and OHLCV streams, HIP-3 and HIP-4 market coverage, HyperCore warehouse delivery, and HyperEVM Foundational API support.'); lines.push(''); hyperliquidFiles.forEach(file => { const relativePath = path.relative(path.resolve(__dirname, '..'), file.path); const urlPath = relativePath.replace(/\.mdx$/, '').replace(/\\/g, '/'); const fm = file.frontmatter; lines.push(linkItem( fm.title || path.basename(file.path, '.mdx'), urlPath, [fm.api && `API: ${fm.api}`, fm.description] )); }); lines.push(''); } // Process Solana API files if (solanaFiles && solanaFiles.length > 0) { lines.push('## Solana API'); lines.push(''); lines.push('Complete data layer for Solana: REST endpoints for SPL token balances (Token + Token-2022), historical balances by slot, SPL transfers, transactions by base58 signature, NFTs (Metaplex + Bubblegum cNFTs), historical and spot prices, and Solana-native primitives. Real-time DEX firehose across Raydium / Orca / Meteora / Jupiter / PumpFun, OHLCV candles, and wallet activity. Warehouse delivery for decoded swaps and SPL transfers.'); lines.push(''); solanaFiles.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(linkItem(fm.title, urlPath, [ fm.chain_name && `chain: ${fm.chain_name}`, fm.chain_id && `chain id: ${fm.chain_id}`, fm.support_level && `support: ${fm.support_level}`, fm.use_cases?.length && `uses: ${fm.use_cases.join(', ')}`, ])); }); lines.push(''); } return lines.join('\n'); } /** * Generate llms-full.txt (complete version with frontmatter + content) */ function generateLlmsFullTxt(apiFiles, streamingFiles, pipelineFiles, hyperliquidFiles, solanaFiles, 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(`- [Hyperliquid API](#hyperliquid-api-documentation) - ${hyperliquidFiles.length} pages (Info API, streaming recipes, and API reference)`); lines.push(`- [Solana API](#solana-api-documentation) - ${(solanaFiles || []).length} pages (Foundational walkthroughs, streaming recipes, warehouse recipes)`); 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(''); }); } // Process Hyperliquid API files if (hyperliquidFiles.length > 0) { lines.push('# Hyperliquid API Documentation'); lines.push(''); lines.push('GoldRush Hyperliquid API is the complete data layer for Hyperliquid: a no-rate-limit drop-in Info API at `https://hypercore.goldrushdata.com/info`, real-time HyperCore wallet and OHLCV streams, HIP-3 and HIP-4 market coverage, Pipeline delivery for HyperCore data, and HyperEVM coverage through the Foundational API.'); lines.push(''); hyperliquidFiles.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(trimTrailingWhitespace(stripMdxToPlainMarkdown(file.content))); lines.push(''); lines.push('---'); lines.push(''); }); } // Process Solana API files if (solanaFiles && solanaFiles.length > 0) { lines.push('# Solana API Documentation'); lines.push(''); lines.push('GoldRush API for Solana is the complete data layer for Solana: REST endpoints for SPL token balances, transactions by signature, NFTs (Metaplex + Bubblegum cNFTs), pricing, and Solana-native primitives; real-time GraphQL streams for the DEX firehose (Raydium, Orca, Meteora, Jupiter, PumpFun), OHLCV, and wallet activity on `SOLANA_MAINNET`; and Pipeline warehouse delivery for decoded `swaps`, `transfers`, and PumpFun lifecycle (`sol_pf_*`) tables.'); lines.push(''); solanaFiles.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(trimTrailingWhitespace(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). // Matches single-line `import X from "...";` and multi-line `import { ... } from "...";`. processed = processed.replace(/^import\s+[\s\S]+?from\s+["'][^"']+["'];?\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`); } /** * Generate Hyperliquid reference files */ function generateHyperliquidReferences() { const overview = readAndStripMdx(hyperliquidOverviewPath); const quickstart = readAndStripMdx(hyperliquidQuickstartPath); const infoOverview = readAndStripMdx(hyperliquidInfoOverviewPath); const infoMigration = readAndStripMdx(hyperliquidInfoMigrationPath); const infoSdk = readAndStripMdx(hyperliquidInfoSdkPath); const infoLimits = readAndStripMdx(hyperliquidInfoLimitsPath); const streamingWallet = readAndStripMdx(hyperliquidStreamingWalletPath); const wsOverview = readAndStripMdx(hyperliquidWebsocketOverviewPath); const wsMigration = readAndStripMdx(hyperliquidWebsocketMigrationPath); const wsSdk = readAndStripMdx(hyperliquidWebsocketSdkPath); const wsLimits = readAndStripMdx(hyperliquidWebsocketLimitsPath); const wsL2Recipe = readAndStripMdx(hyperliquidWebsocketL2RecipePath); const wsL2DiffRecipe = readAndStripMdx(hyperliquidWebsocketL2DiffRecipePath); const wsL4Recipe = readAndStripMdx(hyperliquidWebsocketL4RecipePath); const streamingHip3 = readAndStripMdx(hyperliquidStreamingHip3Path); const streamingHip4 = readAndStripMdx(hyperliquidStreamingHip4Path); const streamingLiquidations = readAndStripMdx(hyperliquidStreamingLiquidationsPath); const infoApiReferences = findMdxFiles(hyperliquidInfoApiReferenceDir) .sort() .map(readAndStripMdx); const websocketApiReferences = findMdxFiles(hyperliquidWebsocketApiReferenceDir) .sort() .map(readAndStripMdx); // 1. overview.md writeReferenceFile(hyperliquidSkillsRefDir, 'overview.md', trimTrailingWhitespace([ '# GoldRush Hyperliquid API Overview', '', '## Quick Reference', '', '| Item | Value |', '|------|-------|', '| **Info API URL** | `https://hypercore.goldrushdata.com/info` |', '| **Method** | `POST` |', '| **Authentication** | `Authorization: Bearer ` (same key as Foundational/Streaming/Pipeline) |', '| **Rate Limit** | None |', '| **Wire compatibility** | Byte-for-byte with `POST api.hyperliquid.xyz/info` for implemented types |', '| **Networks** | Mainnet only |', `| **HyperCore historical depth** | Block ${HYPERCORE_START_BLOCK} onward (${HYPERCORE_START_TIMESTAMP}) |`, '| **HyperEVM historical depth** | Genesis |', '', '## Surfaces', '', '| Surface | What it provides |', '|---------|------------------|', '| Info API | Drop-in replacement for `POST /info` (30 current types, including `activeAssetData`, `outcomeMeta`, and GoldRush-native `batchClearinghouseState`/`batchSpotClearinghouseState`; unsupported types return a JSON error) |', '| WebSocket API | Drop-in replacement for `wss://api.hyperliquid.xyz/ws` at `wss://hypercore.goldrushdata.com/ws?key=`. No 1000-subscription-per-IP cap. Channels: `l2Book` (aggregated, optional `coin`), `l2BookDiff` (GoldRush-native L2 snapshot + per-block diffs, single coin / list / wildcard), `l4Book` (GoldRush-native order-level snapshot + per-block diffs) |', '| Streaming API | Real-time `walletTxs`, `ohlcvCandlesForPair`, `ohlcvCandlesForToken` |', '| Pipeline API | `hl_fills`, `hl_trades`, `hl_orders`, `hl_funding`, `hl_misc_events` to your warehouse |', '| Foundational API | HyperEVM (chain `999`) token balances, transfers, NFTs, gas |', '', '---', '', overview.content, '', '---', '', quickstart.content, ].join('\n'))); // 2. info-api.md writeReferenceFile(hyperliquidSkillsRefDir, 'info-api.md', trimTrailingWhitespace([ '# Hyperliquid Info API', '', '## Available Types (today)', '', '| Type | Body | Returns |', '|------|------|---------|', '| `metaAndAssetCtxs` | `{type:"metaAndAssetCtxs",dex:""}` | Tuple [meta, assetCtxs[]] - perp universe + per-asset mark, funding, OI, day volume |', '| `meta` | `{type:"meta",dex:""}` | Perp universe metadata only - size decimals, max leverage, margin tiers (no live context) |', '| `spotMetaAndAssetCtxs` | `{type:"spotMetaAndAssetCtxs"}` | Tuple [spotMeta, assetCtxs[]] - spot universe + per-pair mark, mid, day volume |', '| `spotMeta` | `{type:"spotMeta"}` | Spot universe metadata only - pairs and the full token registry (no live context) |', '| `outcomeMeta` | `{type:"outcomeMeta"}` | Active HIP-4 outcome universe with outcome IDs, descriptions, and Yes/No side specs |', '| `l2Book` | `{type:"l2Book",coin:"BTC"}` | Aggregated Level-2 order book snapshot for one coin (bid/ask {px, sz, n} levels) |', '| `candleSnapshot` | `{type:"candleSnapshot",req:{coin:"BTC",interval:"1h",startTime:...}}` | Historical OHLCV candles for a coin and interval over a time window |', '| `fundingHistory` | `{type:"fundingHistory",coin:"BTC",startTime:...}` | Market-wide historical funding rates and premiums for a coin over a time window |', '| `clearinghouseState` | `{type:"clearinghouseState",user:"0x...",dex:""}` | Perp account state |', '| `spotClearinghouseState` | `{type:"spotClearinghouseState",user:"0x...",dex:""}` | Spot balances |', '| `frontendOpenOrders` | `{type:"frontendOpenOrders",user:"0x...",dex:""}` | Open orders w/ TP/SL metadata |', '| `activeAssetData` | `{type:"activeAssetData",user:"0x...",coin:"ETH"}` | Per-user, per-asset leverage, max trade sizes, available-to-trade amounts, and mark price |', '| `subAccounts` | `{type:"subAccounts",user:"0x..."}` | Sub-accounts owned by a master, each with inlined perp and spot state |', '| `userFills` | `{type:"userFills",user:"0x..."}` | Most recent fills for a user |', '| `userFillsByTime` | `{type:"userFillsByTime",user:"0x...",startTime:...}` | Fills bounded by a time window |', '| `userTwapSliceFills` | `{type:"userTwapSliceFills",user:"0x..."}` | Most recent TWAP slice fills tagged with parent `twapId` |', '| `userFunding` | `{type:"userFunding",user:"0x...",startTime:...}` | Funding payment history with rate, applied size, USDC delta |', '| `userNonFundingLedgerUpdates` | `{type:"userNonFundingLedgerUpdates",user:"0x...",startTime:...}` | Ledger events except funding - deposits, withdrawals, transfers, vault flows, liquidations |', '| `userVaultEquities` | `{type:"userVaultEquities",user:"0x..."}` | Per-vault locked equity with unlock timestamps |', '| `delegatorSummary` | `{type:"delegatorSummary",user:"0x..."}` | Current delegated, undelegated, pending-withdrawal HYPE totals |', '| `delegatorHistory` | `{type:"delegatorHistory",user:"0x..."}` | Delegate, undelegate, deposit, and withdrawal staking events |', '| `delegatorRewards` | `{type:"delegatorRewards",user:"0x..."}` | Accrued staking rewards (delegation and validator commission) |', '| `batchClearinghouseState` | `{type:"batchClearinghouseState",users:["0x...",...],dex:""}` | Array of clearinghouseState slots, 1-50 wallets. **GoldRush-native** (no upstream equivalent) |', '| `batchSpotClearinghouseState` | `{type:"batchSpotClearinghouseState",users:["0x...",...]}` | Array of spotClearinghouseState slots, 1-50 wallets. **GoldRush-native** (no upstream equivalent) |', '', 'Any other `type` value returns `{"error":"unsupported_type","type":""}` with HTTP 400. Requests are not forwarded to upstream Hyperliquid.', '', '## Migration Pattern', '', '```typescript', '// Before', 'fetch("https://api.hyperliquid.xyz/info", {', ' method: "POST",', ' headers: { "Content-Type": "application/json" },', ' body: JSON.stringify(body),', '});', '', '// After -same body, no rate limits', 'fetch("https://hypercore.goldrushdata.com/info", {', ' method: "POST",', ' headers: {', ' "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`,', ' "Content-Type": "application/json",', ' },', ' body: JSON.stringify(body),', '});', '```', '', '---', '', infoOverview.content, '', '---', '', infoMigration.content, '', '---', '', infoSdk.content, '', '---', '', infoLimits.content, '', '---', '', '# Hyperliquid Info API Reference', '', ...infoApiReferences.flatMap(ref => [ `## ${ref.title}`, '', ref.content, '', '---', '', ]), ].join('\n'))); // 3. streaming.md writeReferenceFile(hyperliquidSkillsRefDir, 'streaming.md', trimTrailingWhitespace([ '# Hyperliquid Streaming Recipes', '', '## Critical Rules', '', '1. GraphQL WebSocket URL: `wss://streaming.goldrushdata.com/graphql` (this is the GraphQL Streaming API endpoint - distinct from the Hyperliquid WebSocket API at `wss://hypercore.goldrushdata.com/ws?key=`, which is covered in `websocket-api.md`)', '2. Chain enum: `HYPERCORE_MAINNET` (SCREAMING_SNAKE_CASE)', '3. HIP-3 and HIP-4 pair address syntax: `:-` (e.g. `xyz:GOLD-USDC`)', '4. HIP-3 and HIP-4 token address syntax: plain symbol (e.g. `GOLD`, `OIL`)', '5. `walletTxs` accepts up to thousands of wallet addresses per subscription', '6. Pre-decoded events: `HypercoreFillTransaction` (with `liquidation`), `HypercoreLedgerEvent` (20+ subtypes), `HypercoreFundingEvent`, `HypercoreDepositEvent`, `HypercoreWithdrawalEvent`, `HypercoreDelegationEvent`', '', '## Common Recipes', '', '| Goal | Endpoint | Filter |', '|------|----------|--------|', '| Wallet firehose | `walletTxs` | `chain_name: HYPERCORE_MAINNET, wallet_addresses: [...]` |', '| HIP-3 / HIP-4 OHLCV by pair | `ohlcvCandlesForPair` | `pair_addresses: ["xyz:GOLD-USDC", ...]` |', '| HIP-3 / HIP-4 OHLCV by token | `ohlcvCandlesForToken` | `token_addresses: ["GOLD", "OIL", ...]` |', '| Liquidation tape | `walletTxs` → `HypercoreFillTransaction.liquidation` non-null | filter client-side |', '| Vault leaderboard | `walletTxs` → `HypercoreLedgerEvent.delta` (`LedgerVaultLeaderCommission`, `LedgerVaultDistribution`) | aggregate per vault |', '', '---', '', streamingWallet.content, '', '---', '', streamingHip3.content, '', '---', '', streamingHip4.content, '', '---', '', streamingLiquidations.content, ].join('\n'))); // 4. websocket-api.md writeReferenceFile(hyperliquidSkillsRefDir, 'websocket-api.md', trimTrailingWhitespace([ '# Hyperliquid WebSocket API', '', '## Critical Rules', '', '1. WebSocket URL: `wss://hypercore.goldrushdata.com/ws?key=` (note: `hypercore`, not `hyperliquid`; auth is a `?key=` query parameter, not an `Authorization` header).', '2. Wire-compatible with `wss://api.hyperliquid.xyz/ws` for shared subscription types (e.g. `l2Book`).', '3. No 1000-subscription-per-IP cap. Multiplex many subscriptions on one connection.', '4. **`l2Book`** - aggregated price-level snapshots `{px, sz, n}`. `coin` is **optional** - omit it to stream every asset over a single subscription. When `coin` is omitted, `marketTypes` defaults to `["perp"]` (perps only); pass `["spot"]`, `["outcome"]`, a mix, or `["*"]` to opt into spot, outcome, and any future market types.', '5. **`l2BookDiff`** - GoldRush-native L2 diff transport. Same aggregated `{px, sz, n}` shape as `l2Book`, but emits one `Snapshot` per subscribed coin and then per-block `Updates` carrying only changed levels. `coin` accepts a single asset, an array of assets, or can be omitted for wildcard (same `marketTypes` default - perps only - applies when `coin` is omitted). Treat `sz: "0"` (with `n: 0`) as level removal. Not available on the public Hyperliquid WebSocket.', '6. **`l4Book`** - GoldRush-native order-level stream with `user`, `oid`, `cloid`, `tif`, and trigger metadata per order. `coin` is **required**. Emits a single `Snapshot` on subscribe, then per-block `Updates` (`order_statuses` + `book_diffs`). Not available on the public Hyperliquid WebSocket.', '', '## Available Subscriptions', '', '| Channel | Subscription body | Returns |', '|---------|-------------------|---------|', '| `l2Book` | `{"type":"l2Book","coin":"BTC"}` (or omit `coin`) | Full L2 book snapshot per tick with bids/asks aggregated by significant figures. Self-healing - every message is a complete snapshot. |', '| `l2BookDiff` | `{"type":"l2BookDiff","coin":"HYPE"}`, `{"type":"l2BookDiff","coin":["HYPE","BTC","ETH"]}`, or omit `coin` for wildcard | Initial `Snapshot` per coin (aggregated `{px, sz, n}`), then per-block `Updates` with `book_diffs` grouped by coin carrying only changed levels. `sz: "0"` means level removed. **GoldRush-native, no upstream equivalent.** |', '| `l4Book` | `{"type":"l4Book","coin":"BTC"}` | Initial `Snapshot` of every resting order, then per-block `Updates` with `order_statuses` (lifecycle) and `book_diffs` (per-order changes). **GoldRush-native, no upstream equivalent.** |', '', '## Subscribe / Unsubscribe Pattern', '', '```json', '// Subscribe', '{"method":"subscribe","subscription":{"type":"l2Book","coin":"BTC"}}', '', '// Unsubscribe (same subscription body, method swapped)', '{"method":"unsubscribe","subscription":{"type":"l2Book","coin":"BTC"}}', '```', '', '## When to use which channel', '', '| Need | Use |', '|------|-----|', '| Top-of-book, spread, depth-weighted mid, slippage / impact estimator | `l2Book` |', '| Stream every asset on one subscription | `l2Book` (omit `coin`) or `l2BookDiff` (omit `coin`) |', '| Aggregated `{px, sz, n}` book state with diff-only bandwidth, single coin / list / wildcard | `l2BookDiff` |', '| Multi-coin coverage with a fixed list of assets in one subscription | `l2BookDiff` with `coin: ["HYPE","BTC","ETH"]` |', '| Queue position, per-user flow attribution, microstructure analytics | `l4Book` |', '| Reconstruct an L2-style aggregated view but keep order-level detail | `l4Book` (aggregate client-side) |', '| OHLCV candles instead of raw book state | Streaming API `ohlcvCandlesForPair` (see `streaming.md`) |', '', '---', '', wsOverview.content, '', '---', '', wsMigration.content, '', '---', '', wsSdk.content, '', '---', '', wsLimits.content, '', '---', '', '# WebSocket API Reference', '', ...websocketApiReferences.flatMap(ref => [ `## ${ref.title}`, '', ref.content, '', '---', '', ]), '', '# Recipes', '', wsL2Recipe.content, '', '---', '', wsL2DiffRecipe.content, '', '---', '', wsL4Recipe.content, ].join('\n'))); const fileCount = fs.readdirSync(hyperliquidSkillsRefDir).filter(f => f.endsWith('.md')).length; console.log(` 📁 Hyperliquid: ${fileCount} reference files`); } /** * Generate Solana reference files for the goldrush-solana skill */ function generateSolanaReferences() { const overview = readAndStripMdx(solanaOverviewPath); const quickstart = readAndStripMdx(solanaQuickstartPath); const roadmap = readAndStripMdx(solanaRoadmapPath); const fOverview = readAndStripMdx(solanaFoundationalOverviewPath); const fWallet = readAndStripMdx(solanaFoundationalWalletPath); const fTransactions = readAndStripMdx(solanaFoundationalTransactionsPath); const fNfts = readAndStripMdx(solanaFoundationalNftsPath); const fPricing = readAndStripMdx(solanaFoundationalPricingPath); const fNative = readAndStripMdx(solanaFoundationalNativePath); const sDexFirehose = readAndStripMdx(solanaStreamingDexFirehosePath); const sPumpFun = readAndStripMdx(solanaStreamingPumpFunPath); const sWallet = readAndStripMdx(solanaStreamingWalletPath); const sOhlcv = readAndStripMdx(solanaStreamingOhlcvPath); const sNftMints = readAndStripMdx(solanaStreamingNftMintsPath); const wDexSwaps = readAndStripMdx(solanaWarehouseDexSwapsPath); const wSplTransfers = readAndStripMdx(solanaWarehouseSplTransfersPath); // 1. overview.md writeReferenceFile(solanaSkillsRefDir, 'overview.md', trimTrailingWhitespace([ '# GoldRush API for Solana - Overview', '', '## Quick Reference', '', '| Item | Value |', '|------|-------|', '| **Foundational base URL** | `https://api.covalenthq.com/v1/solana-mainnet/...` |', '| **Streaming WebSocket URL** | `wss://streaming.goldrushdata.com/graphql` |', '| **Authentication** | `Authorization: Bearer ` (same key for all surfaces) |', '| **REST chain name** | `solana-mainnet` (kebab-case) |', '| **Streaming chain enum** | `SOLANA_MAINNET` (SCREAMING_SNAKE_CASE) |', '| **Wallet address format** | base58, 32-44 chars, case-preserved |', '| **Transaction id** | `signature` (base58, ~88 chars) |', '| **Block identifier** | `slot` (primary) / `block_height` (secondary, ~5% gaps) / `block_time` (unix seconds) |', '| **Native unit** | lamports (1 SOL = 10^9 lamports) |', '| **Default commitment** | `confirmed` (~1s). `finalized` (~13s) via `?commitment=finalized` |', '', '## Surfaces', '', '| Surface | What it provides |', '|---------|------------------|', '| Foundational API | REST endpoints for SPL balances (Token + Token-2022), historical balances by slot, SPL transfers, transactions by signature, NFTs (Metaplex + Bubblegum cNFTs), pricing, and Solana-native primitives. |', '| Streaming API | Real-time `newPairs` (DEX firehose across Raydium / Orca / Meteora / Jupiter / PumpFun), `ohlcvCandlesForPair`, `ohlcvCandlesForToken`, `walletTxs`. |', '| Pipeline API | Decoded `swaps`, `transfers`, and PumpFun lifecycle (`sol_pf_create` / `sol_pf_swap` / `sol_pf_complete` / `sol_pf_withdraw`) to ClickHouse, BigQuery, Postgres, Kafka, S3, or webhooks. |', '', '---', '', overview.content, '', '---', '', quickstart.content, '', '---', '', '# Roadmap', '', roadmap.content, ].join('\n'))); // 2. foundational.md writeReferenceFile(solanaSkillsRefDir, 'foundational.md', trimTrailingWhitespace([ '# GoldRush Foundational API on Solana', '', '## Critical Rules', '', '1. Base URL: `https://api.covalenthq.com/v1/solana-mainnet/...` (kebab-case chain name).', '2. Wallet address format: base58, **case-preserved** (unlike EVM 0x-hex which is lowercased).', '3. Token mints: base58 mint pubkey - takes the `contract_address` / `tokenMint` slot. USDC = `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`, wrapped SOL = `So11111111111111111111111111111111111111112`.', '4. Transaction id: base58 `signature` (~88 chars), addressed via `/transaction_v2/{signature}/` - **not** `tx_hash` and **not** `/transaction_v2/{txHash}/`.', '5. Slot is primary; `block_height` is secondary and can be null because ~5% of slots are skipped.', '6. SPL Token + Token-2022 are aggregated by default in every balance/transfer/holder response. Opt out with `?include-token-2022=false`.', '7. cNFTs surface alongside Metaplex NFTs with `compressed: true`. For cNFTs, `contract_address` is the Bubblegum Merkle tree (not a mint), and `token_id` is the Merkle leaf index.', '8. ALT references in versioned transactions (`v0`) are pre-resolved at index time - clients always see the full `account_keys`.', '9. `processed` commitment is not exposed via Foundational (too unstable for REST semantics). Default is `confirmed`; use `?commitment=finalized` for rollback-impossible reads.', '', '---', '', fOverview.content, '', '---', '', fWallet.content, '', '---', '', fTransactions.content, '', '---', '', fNfts.content, '', '---', '', fPricing.content, '', '---', '', fNative.content, ].join('\n'))); // 3. streaming.md writeReferenceFile(solanaSkillsRefDir, 'streaming.md', trimTrailingWhitespace([ '# GoldRush Streaming on Solana', '', '## Critical Rules', '', '1. GraphQL WebSocket URL: `wss://streaming.goldrushdata.com/graphql`.', '2. Chain enum: `SOLANA_MAINNET` (SCREAMING_SNAKE_CASE) - **not** `solana-mainnet` (that is the Foundational REST chain name).', '3. `newPairs` on `SOLANA_MAINNET` covers Raydium AMM/CLMM, Orca Whirlpool, Meteora DLMM/Dynamic, Jupiter, and PumpFun on one subscription. Filter client-side on the `exchange` field.', '4. PumpFun launches surface as `exchange: pumpfun`. Raydium graduations surface seconds later as `exchange: raydium-amm` with the same `base_token.address`.', '5. `ohlcvCandlesForPair` takes pool addresses (base58); `ohlcvCandlesForToken` takes SPL mints and aggregates across every pool carrying that token.', '6. `walletTxs` accepts thousands of wallet addresses per subscription on one WebSocket.', '7. No rate limits on Streaming for Solana; no per-IP subscription cap.', '', '## Common Recipes', '', '| Goal | Subscription | Filter / Args |', '|------|-------------|---------------|', '| New-pool firehose across every Solana DEX | `newPairs` | `chain_name: SOLANA_MAINNET` |', '| PumpFun launches only | `newPairs` → filter `exchange === "pumpfun"` | client-side |', '| Graduation detection | `newPairs` → track `(base_token.address, exchange)` pairs | client-side |', '| Live OHLCV for a specific pool | `ohlcvCandlesForPair` | `pair_addresses: [""]` |', '| Aggregated price for an SPL mint | `ohlcvCandlesForToken` | `token_addresses: [""]` |', '| Wallet activity firehose | `walletTxs` | `chain_name: SOLANA_MAINNET, wallet_addresses: [...]` |', '', '---', '', sDexFirehose.content, '', '---', '', sPumpFun.content, '', '---', '', sWallet.content, '', '---', '', sOhlcv.content, '', '---', '', sNftMints.content, '', '---', '', '# Warehouse Recipes', '', wDexSwaps.content, '', '---', '', wSplTransfers.content, ].join('\n'))); const fileCount = fs.readdirSync(solanaSkillsRefDir).filter(f => f.endsWith('.md')).length; console.log(` 📁 Solana: ${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(hyperliquidSkillsRefDir); clearReferencesDir(solanaSkillsRefDir); clearReferencesDir(cliSkillsRefDir); clearReferencesDir(jsonRpcSkillsRefDir); generateFoundationalReferences(apiFiles, chainFiles); generateStreamingReferences(streamingFiles, chainFiles); generateX402References(); generateHyperliquidReferences(); generateSolanaReferences(); generateCliReferences(); generateJsonRpcReferences(); } /** * Generate JSON-RPC reference files. * * Three reference files: * - overview.md product positioning, tier comparison, endpoint shape * - methods.md full method catalog (from api-defn/rpc/methods.yaml) * - quickstart.md per-library setup boilerplate (auth via header) */ function generateJsonRpcReferences() { const yaml = require('js-yaml'); const rpcMethods = yaml.load(fs.readFileSync(rpcMethodsYamlPath, 'utf8')).methods; const methodNames = Object.keys(rpcMethods); const rpcOverview = readAndStripMdx(rpcOverviewPath); const rpcQuickstart = readAndStripMdx(rpcQuickstartPath); const rpcAuth = readAndStripMdx(rpcAuthPath); const rpcEdgeTier = readAndStripMdx(rpcEdgeTierPath); const rpcDebugTrace = readAndStripMdx(rpcDebugTracePath); const rpcPricing = readAndStripMdx(rpcPricingPath); // 1. overview.md writeReferenceFile(jsonRpcSkillsRefDir, 'overview.md', [ '# GoldRush JSON-RPC Overview', '', '## Quick Reference', '', '| Item | Value |', '|------|-------|', '| **Endpoint** | `https://rpc.goldrushdata.com/v1/{chain}` |', '| **Authentication** | `Authorization: Bearer ` (same key as Foundational/Streaming/x402) |', '| **EVM methods** | `eth_*`, `net_*`, `web3_*`, `debug_*`, `trace_*` |', '| **Solana methods** | account/block/transaction/token/slot/network/inflation reads + WebSocket subscriptions |', '| **Launch chains** | Ethereum, Polygon, BNB, Arbitrum, Base, HyperEVM, MegaETH, Monad, Tempo, Solana |', '| **Archive depth** | full archive |', '| **Pricing** | pay-per-call from GoldRush credit balance |', '| **SLA** | 99.9% monthly uptime for production accounts |', '| **Compatibility** | EVM: viem, ethers, web3.js, web3.py. Solana: @solana/kit, @solana/web3.js, solana-py. All via custom-headers transport. |', '', '## Decision matrix', '', 'Use **JSON-RPC** when you need raw, untyped, opcode-level access for wallets, indexers, simulators, or anything that calls an EVM node directly.', '', 'Use **Foundational API** (REST) when you need decoded, typed, multi-chain reads such as token balances, NFT metadata, USD pricing, and transaction histories.', '', 'Use **Streaming API** (WebSocket) when you need real-time event streams.', '', 'Use **Pipeline** for bulk historical analytics and event-table exports.', '', 'Use **Hyperliquid** for Hyperliquid-specific perp/spot account, market, and L2 book data.', '', 'Use **x402** when an autonomous agent needs blockchain data without an API key.', '', '---', '', rpcOverview.content, '', '---', '', rpcEdgeTier.content, '', '---', '', rpcPricing.content, ].join('\n')); // 2. methods.md const methodLines = ['# GoldRush JSON-RPC Methods', '']; const grouped = { eth: [], net: [], web3: [], debug: [], trace: [] }; for (const name of methodNames) { const m = rpcMethods[name]; if (grouped[m.namespace]) grouped[m.namespace].push(name); } for (const ns of ['eth', 'net', 'web3', 'debug', 'trace']) { const list = grouped[ns]; if (list.length === 0) continue; methodLines.push(`## \`${ns}_*\``); methodLines.push(''); methodLines.push('| Method | Credits | Summary |'); methodLines.push('|--------|--------:|---------|'); for (const name of list) { const m = rpcMethods[name]; methodLines.push(`| \`${name}\` | ${m.creditRate} | ${m.summary} |`); } methodLines.push(''); } methodLines.push('## Per-method details'); methodLines.push(''); for (const name of methodNames) { const m = rpcMethods[name]; methodLines.push(`### \`${name}\``); methodLines.push(''); methodLines.push(`**Summary:** ${m.summary}`); methodLines.push(''); if (m.parameters && m.parameters.length > 0) { methodLines.push('**Parameters:**'); methodLines.push(''); methodLines.push('| Name | Type | Required | Description |'); methodLines.push('|------|------|----------|-------------|'); for (const p of m.parameters) { const pType = String(p.type).replace(/\|/g, '\\|'); const pDesc = String(p.description).replace(/\|/g, '\\|'); methodLines.push(`| \`${p.name}\` | \`${pType}\` | ${p.required ? 'yes' : 'no'} | ${pDesc} |`); } methodLines.push(''); } else { methodLines.push('**Parameters:** none'); methodLines.push(''); } if (m.returns) { methodLines.push(`**Returns:** \`${m.returns.type}\`. ${m.returns.description}`); methodLines.push(''); } methodLines.push('---'); methodLines.push(''); } methodLines.push('---'); methodLines.push(''); methodLines.push(rpcDebugTrace.content); writeReferenceFile(jsonRpcSkillsRefDir, 'methods.md', methodLines.join('\n')); // 2b. methods-solana.md const solMethods = yaml.load(fs.readFileSync(rpcSolanaMethodsYamlPath, 'utf8')).methods; const solNames = Object.keys(solMethods); const SVM_CATEGORY_ORDER = [ 'Blocks info', 'Transactions info', 'Node info', 'Account info', 'Network info', 'Slot info', 'Token info', 'Subscriptions', 'Network inflation info', ]; const solLines = ['# GoldRush Solana JSON-RPC Methods', '']; solLines.push('Endpoint: `https://rpc.goldrushdata.com/v1/solana-mainnet` (HTTP); `wss://rpc.goldrushdata.com/v1/solana-mainnet` (subscriptions).'); solLines.push('Auth: `Authorization: Bearer ` header. Commitment levels: `processed`, `confirmed`, `finalized`. Balances in lamports (1 SOL = 1e9 lamports).'); solLines.push(''); const solByCategory = {}; for (const cat of SVM_CATEGORY_ORDER) solByCategory[cat] = []; for (const name of solNames) { const cat = solMethods[name].category; if (solByCategory[cat]) solByCategory[cat].push(name); } for (const cat of SVM_CATEGORY_ORDER) { const list = solByCategory[cat]; if (!list || list.length === 0) continue; solLines.push(`## ${cat}`); solLines.push(''); solLines.push('| Method | Transport | Credits | Summary |'); solLines.push('|--------|-----------|--------:|---------|'); for (const name of list) { const m = solMethods[name]; const transport = m.transport === 'websocket' ? 'WebSocket' : 'HTTP'; const dep = m.deprecated ? ' (deprecated)' : ''; solLines.push(`| \`${name}\`${dep} | ${transport} | ${m.creditRate} | ${m.summary} |`); } solLines.push(''); } solLines.push('## Per-method details'); solLines.push(''); for (const name of solNames) { const m = solMethods[name]; solLines.push(`### \`${name}\``); solLines.push(''); if (m.deprecated) { solLines.push(`**Deprecated.**${m.deprecatedFor ? ` Use \`${m.deprecatedFor}\` instead.` : ''}`); solLines.push(''); } solLines.push(`**Summary:** ${m.summary}`); solLines.push(''); if (m.parameters && m.parameters.length > 0) { solLines.push('**Parameters:**'); solLines.push(''); solLines.push('| Name | Type | Required | Description |'); solLines.push('|------|------|----------|-------------|'); for (const p of m.parameters) { const pType = String(p.type).replace(/\|/g, '\\|'); const pDesc = String(p.description).replace(/\|/g, '\\|'); solLines.push(`| \`${p.name}\` | \`${pType}\` | ${p.required ? 'yes' : 'no'} | ${pDesc} |`); } solLines.push(''); } else { solLines.push('**Parameters:** none'); solLines.push(''); } if (m.returns) { solLines.push(`**Returns:** \`${m.returns.type}\`. ${m.returns.description}`); solLines.push(''); } solLines.push('---'); solLines.push(''); } writeReferenceFile(jsonRpcSkillsRefDir, 'methods-solana.md', solLines.join('\n')); // 3. quickstart.md writeReferenceFile(jsonRpcSkillsRefDir, 'quickstart.md', [ '# GoldRush JSON-RPC Quickstart', '', '## Header-based authentication', '', 'API keys are sent as an `Authorization: Bearer ` header, never in the URL. The same GoldRush API key works across all GoldRush products.', '', '## Per-library setup', '', 'See the rendered reference for copy-paste examples. The pattern in each library:', '', '- **ethers v6**: `new ethers.FetchRequest(url)` + `.setHeader("Authorization", ...)`, pass to `new ethers.JsonRpcProvider(req)`', '- **viem**: `http(url, { fetchOptions: { headers: { Authorization: ... } } })`', '- **web3.js**: `new Web3.providers.HttpProvider(url, { headers: [{ name, value }] })`', '- **web3.py**: `Web3.HTTPProvider(url, request_kwargs={"headers": {...}})`', '- **curl**: `-H "Authorization: Bearer $GOLDRUSH_API_KEY"`', '', '## Endpoint shape', '', '```', 'https://rpc.goldrushdata.com/v1/{chain}', '```', '', 'Replace `{chain}` with one of: `eth-mainnet`, `matic-mainnet`, `bsc-mainnet`, `arbitrum-mainnet`, `base-mainnet`, `hyperevm-mainnet`, `megaeth-mainnet`, `monad-mainnet`, `tempo-mainnet`, `solana-mainnet`.', '', '---', '', rpcQuickstart.content, '', '---', '', rpcAuth.content, ].join('\n')); const fileCount = fs.readdirSync(jsonRpcSkillsRefDir).filter(f => f.endsWith('.md')).length; console.log(` 📁 JSON-RPC: ${fileCount} reference files`); } /** * 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); const hyperliquidMdxFiles = [ ...findMdxFiles(hyperliquidDocsDir).sort(), ...findMdxFiles(hyperliquidInfoApiReferenceDir).sort(), ...findMdxFiles(hyperliquidWebsocketApiReferenceDir).sort() ]; const solanaMdxFiles = findMdxFiles(solanaDocsDir).sort(); 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 ${hyperliquidMdxFiles.length} Hyperliquid API files`); console.log(`📊 Found ${solanaMdxFiles.length} Solana 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); const enrichedHyperliquidFiles = hyperliquidMdxFiles.map(parsePipelineFile); const enrichedSolanaFiles = solanaMdxFiles.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, enrichedHyperliquidFiles, enrichedSolanaFiles, enrichedChainFiles); fs.writeFileSync(llmsTxtPath, llmsTxt, 'utf8'); console.log('✅ Created:', llmsTxtPath); console.log('✍️ Generating llms-full.txt...'); const llmsFullTxt = generateLlmsFullTxt(enrichedApiFiles, enrichedStreamingFiles, enrichedPipelineFiles, enrichedHyperliquidFiles, enrichedSolanaFiles, 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(` - ${enrichedHyperliquidFiles.length} Hyperliquid API pages`); console.log(` - ${enrichedSolanaFiles.length} Solana API pages`); console.log(` - ${enrichedChainFiles.length} Chains`); } // Run the script if (require.main === module) { main(); } module.exports = { generateLlmsTxt, generateLlmsFullTxt, generateSkillsReferences, parseAndEnrichEndpoint, parseAndEnrichChain, parsePipelineFile, findMdxFiles };

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