{"title":"JUNKCOIN API Documentation","version":"1.2.0","description":"Comprehensive REST API for JUNKCOIN blockchain statistics, supply analysis, halving schedules, and milestone projections. Real-time data with custom timeframe support.","baseUrl":"https://supply.junkcoinjkc.com","lastUpdated":"2025-01-30T00:00:00.000Z","endpoints":{"/api/junkcoin-stats":{"method":["GET","POST"],"description":"Basic JUNKCOIN blockchain statistics including current supply, block information, network difficulty, and hashrate","rateLimit":"300 requests per 5 minutes per IP","caching":"5 minutes public cache","parameters":{"query":[]},"response":{"structure":{"liveSupply":"number - Current circulating supply in JKC","refreshDataTimestamp":"string - ISO timestamp of data refresh","updatedTimestamp":"string - ISO timestamp of last update","currentSupply":"number - Current total supply","maxSupply":"number - Maximum possible supply (54,000,000)","percentageMined":"number - Percentage of max supply mined","currentBlock":"number - Current block height","blockHash":"string - Current block hash","blockReward":"number - Current block reward in JKC","inflationRate":"number - Current annual inflation rate","difficulty":"number - Current network difficulty","hashrate":"number - Current network hashrate in H/s","status":"string - Response status (success/error)","message":"string - Optional status message"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/junkcoin-stats\"","javascript":"const response = await fetch('https://supply.junkcoinjkc.com/api/junkcoin-stats');\nconst data = await response.json();\nconsole.log(`Current supply: ${data.currentSupply.toLocaleString()} JKC`);","python":"import requests\n\nresponse = requests.get('https://supply.junkcoinjkc.com/api/junkcoin-stats')\ndata = response.json()\nprint(f\"Current supply: {data['currentSupply']:,} JKC\")"},"response":{"success":{"liveSupply":19744776.323584,"refreshDataTimestamp":"2025-01-30T12:00:00.000Z","updatedTimestamp":"2025-01-30T12:00:00.000Z","currentSupply":19744776.323584,"maxSupply":54000000,"percentageMined":36.56,"currentBlock":540874,"blockHash":"0c936435c6ffe0e96319e2ee3bc2979198943b38aa064e0b94a6c4ece12dbfc1","blockReward":12.5,"inflationRate":2.34,"difficulty":31591048.45879784,"hashrate":2045119680462275.2,"status":"success"},"error":{"error":"Data fetch failed","message":"Unable to retrieve blockchain data","status":"error","timestamp":"2025-01-30T12:00:00.000Z"}}}},"/api/junkcoin-stats/formatted":{"method":["GET"],"description":"Human-readable formatted version of basic JUNKCOIN statistics with proper number formatting and units","rateLimit":"300 requests per 5 minutes per IP","caching":"5 minutes public cache","parameters":{"query":[]},"response":{"structure":{"currentSupply":"string - Formatted current supply with commas","maxSupply":"string - Formatted max supply","percentageMined":"string - Percentage with % symbol","currentBlock":"string - Formatted block number","blockReward":"string - Reward with JKC unit","inflationRate":"string - Rate with % symbol","difficulty":"string - Formatted difficulty","hashrate":"string - Formatted hashrate with units","lastUpdated":"string - Human-readable timestamp","status":"string - Response status"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/junkcoin-stats/formatted\""},"response":{"success":{"currentSupply":"19,744,776 JKC","maxSupply":"54,000,000 JKC","percentageMined":"36.56%","currentBlock":"540,874","blockReward":"12.5 JKC","inflationRate":"2.34%","difficulty":"31.59M","hashrate":"2.05 PH/s","lastUpdated":"January 30, 2025 at 12:00 PM","status":"success"}}}},"/api/junkcoin-supply-milestone":{"method":["GET","POST"],"description":"Calculate exact new JKC supply creation and projections for custom timeframes. Shows how much new supply will be created over specified periods with flexible timeframe formats.","rateLimit":"300 requests per 5 minutes per IP","caching":"5 minutes public cache (GET only)","parameters":{"query":[{"name":"timeframes","type":"string","required":false,"description":"Comma-separated list of timeframes to analyze. Supports flexible formats: d (days), m (months), y (years).","examples":["30d","30d,6m,1y","1w,1m,3m,6m,1y,2y,5y","365d","12m"],"default":"30d,6m,1y"},{"name":"blocks","type":"integer","required":false,"description":"Legacy parameter: Number of blocks in the future (for backward compatibility)","examples":["100000","525600"],"default":null},{"name":"days","type":"number","required":false,"description":"Legacy parameter: Number of days in the future (for backward compatibility)","examples":["30","365","730"],"default":null},{"name":"years","type":"number","required":false,"description":"Legacy parameter: Number of years in the future (for backward compatibility)","examples":["1","2","5"],"default":null}]},"response":{"structure":{"requestTimestamp":"string - ISO timestamp of request","currentSupply":"number - Current total supply","currentBlock":"number - Current block height","milestones":[{"timeframe":"string - Original timeframe string (e.g., '30d', '6m')","currentSupply":"number - Current supply at request time","projectedSupply":"number - Projected supply after timeframe","newSupply":"number - New JKC that will be created","percentageIncrease":"number - Percentage increase in supply","projectedBlock":"number - Projected block height","currentBlock":"number - Current block height","blocksToAdd":"number - Number of blocks to be mined","targetDate":"string - ISO timestamp of target date","daysFromNow":"number - Days from current time","estimatedReward":"number - Expected block reward at target time","projectedInflationRate":"number - Expected annual inflation rate","readableTimeframe":"string - Human-readable timeframe description"}],"metadata":{"responseTime":"number - Response time in milliseconds","cacheStatus":"string - Cache status","dataSource":"array - Data source APIs","requestedTimeframes":"array - List of requested timeframes","totalDataPoints":"number - Number of milestone projections returned"},"status":"string - Response status"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/junkcoin-supply-milestone?timeframes=30d,6m,1y\"","javascript":"// Get supply projections for multiple timeframes\nconst response = await fetch('https://supply.junkcoinjkc.com/api/junkcoin-supply-milestone?timeframes=30d,6m,1y');\nconst data = await response.json();\n\ndata.milestones.forEach(milestone => {\n  console.log(`${milestone.readableTimeframe}: +${milestone.newSupply.toLocaleString()} JKC (${milestone.percentageIncrease.toFixed(2)}%)`);\n});","python":"import requests\n\n# Get multiple timeframe projections\nresponse = requests.get('https://supply.junkcoinjkc.com/api/junkcoin-supply-milestone?timeframes=30d,6m,1y,2y')\ndata = response.json()\n\nfor milestone in data['milestones']:\n    print(f\"{milestone['readableTimeframe']}: +{milestone['newSupply']:,.0f} JKC ({milestone['percentageIncrease']:.2f}%)\")\n    print(f\"  Target Date: {milestone['targetDate'][:10]}\")\n    print(f\"  Inflation Rate: {milestone['projectedInflationRate']:.2f}%\")\n    print()"},"response":{"success":{"requestTimestamp":"2025-01-30T12:00:00.000Z","currentSupply":19744776.323584,"currentBlock":540874,"milestones":[{"timeframe":"30d","currentSupply":19744776.323584,"projectedSupply":20284776.323584,"newSupply":540000,"percentageIncrease":2.7356,"projectedBlock":584074,"currentBlock":540874,"blocksToAdd":43200,"targetDate":"2025-03-01T12:00:00.000Z","daysFromNow":30,"estimatedReward":12.5,"projectedInflationRate":32.1456,"readableTimeframe":"30 days"},{"timeframe":"6m","currentSupply":19744776.323584,"projectedSupply":23044776.323584,"newSupply":3300000,"percentageIncrease":16.7123,"projectedBlock":804074,"currentBlock":540874,"blocksToAdd":263200,"targetDate":"2025-07-30T12:00:00.000Z","daysFromNow":182,"estimatedReward":12.5,"projectedInflationRate":24.8934,"readableTimeframe":"6 months"},{"timeframe":"1y","currentSupply":19744776.323584,"projectedSupply":26344776.323584,"newSupply":6600000,"percentageIncrease":33.4246,"projectedBlock":1068074,"currentBlock":540874,"blocksToAdd":527200,"targetDate":"2026-01-30T12:00:00.000Z","daysFromNow":365,"estimatedReward":12.5,"projectedInflationRate":18.7234,"readableTimeframe":"1 year"}],"metadata":{"responseTime":245,"cacheStatus":"live-data","dataSource":["api.junkiewally.xyz"],"requestedTimeframes":["30d","6m","1y"],"totalDataPoints":3},"status":"success"},"error":{"status":"error","message":"No valid timeframes provided","invalidTimeframes":["invalid_format"],"supportedFormats":["d (days): 1d, 30d, 365d","m (months): 1m, 6m, 12m","y (years): 1y, 2y, 5y","Multiple: 30d,6m,1y,2y"],"examples":["/api/junkcoin-supply-milestone?timeframes=30d","/api/junkcoin-supply-milestone?timeframes=30d,6m,1y","/api/junkcoin-supply-milestone?timeframes=1w,1m,3m,6m,1y,2y,5y"]}}}},"/api/junkcoin-halving":{"method":["GET","POST"],"description":"Complete JUNKCOIN halving schedule with current status, next halving countdown, and emission rate analysis","rateLimit":"300 requests per 5 minutes per IP","caching":"5 minutes public cache (GET only)","parameters":{"query":[]},"response":{"structure":{"requestTimestamp":"string - ISO timestamp of request","currentBlock":"number - Current block height","currentSupply":"number - Current total supply","currentPeriod":{"phase":"string - Current halving phase name","blockStart":"number - Phase start block","blockEnd":"number - Phase end block","reward":"number - Current block reward","blocksRemaining":"number - Blocks until next halving","daysRemaining":"number - Days until next halving","percentComplete":"number - Percentage of current phase complete"},"nextHalving":{"phase":"string - Next halving phase name","blockStart":"number - Next halving start block","reward":"number - New block reward after halving","blocksRemaining":"number - Blocks until halving","daysRemaining":"number - Days until halving","estimatedDate":"string - ISO timestamp of estimated halving date"},"upcomingHalvings":"array - Next 10 upcoming halvings with details","emissionSchedule":{"totalEmissionPeriod":"string - Total emission period","finalBlock":"number - Final block with rewards","currentProgress":"number - Percentage of total emission complete","remainingSupply":"number - JKC remaining to be mined"},"metadata":{"responseTime":"number - Response time in milliseconds","cacheStatus":"string - Cache status","dataSource":"array - Data source APIs"},"status":"string - Response status"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/junkcoin-halving\"","javascript":"// Get next halving information\nconst response = await fetch('https://supply.junkcoinjkc.com/api/junkcoin-halving');\nconst data = await response.json();\n\nconsole.log(`Next halving in ${data.nextHalving.daysRemaining.toFixed(0)} days`);\nconsole.log(`Current reward: ${data.currentPeriod.reward} JKC`);\nconsole.log(`Next reward: ${data.nextHalving.reward} JKC`);","python":"import requests\nfrom datetime import datetime\n\nresponse = requests.get('https://supply.junkcoinjkc.com/api/junkcoin-halving')\ndata = response.json()\n\nnext_halving = data['nextHalving']\nprint(f\"Next halving: {next_halving['phase']}\")\nprint(f\"Days remaining: {next_halving['daysRemaining']:.0f}\")\nprint(f\"Estimated date: {next_halving['estimatedDate']}\")"},"response":{"success":{"requestTimestamp":"2025-01-30T12:00:00.000Z","currentBlock":540874,"currentSupply":19744776.323584,"currentPeriod":{"phase":"Second Halving","blockStart":394200,"blockEnd":656999,"reward":12.5,"blocksRemaining":116125,"daysRemaining":80.6,"percentComplete":55.8},"nextHalving":{"phase":"Third Halving","blockStart":657000,"reward":6.25,"blocksRemaining":116126,"daysRemaining":80.6,"estimatedDate":"2025-04-20T12:00:00.000Z"},"upcomingHalvings":[],"emissionSchedule":{"totalEmissionPeriod":"137 years","finalBlock":71862599,"currentProgress":0.753,"remainingSupply":34255223.676416},"metadata":{"responseTime":189,"cacheStatus":"no-cache","dataSource":["api.junkiewally.xyz"]},"status":"success"}}}},"/api/junkcoin-comprehensive":{"method":["GET","POST"],"description":"Comprehensive JUNKCOIN analytics combining basic stats, supply projections, and halving information for custom timeframes","rateLimit":"300 requests per 5 minutes per IP","caching":"5 minutes public cache (GET only)","parameters":{"query":[{"name":"timeframes","type":"string","required":false,"description":"Comma-separated list of timeframes for supply projections","examples":["1d,1w,1m","1y,2y,5y"],"default":"1d,1w,1m,1y"}]},"response":{"structure":{"basicStats":"object - Basic blockchain statistics","supplyProjections":"array - Supply projections for requested timeframes","halvingInfo":"object - Current and next halving information","metadata":"object - Request metadata and performance info","status":"string - Response status"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/junkcoin-comprehensive?timeframes=1d,1w,1m,1y\""},"response":{"success":{"basicStats":{},"supplyProjections":[],"halvingInfo":{},"metadata":{},"status":"success"}}}},"/api/junkcoin-comprehensive/formatted":{"method":["GET","POST"],"description":"Human-readable formatted version of comprehensive JUNKCOIN analytics","rateLimit":"300 requests per 5 minutes per IP","caching":"5 minutes public cache (GET only)","parameters":{"query":[{"name":"timeframes","type":"string","required":false,"description":"Comma-separated list of timeframes","default":"1d,1w,1m,1y"}]},"response":{"structure":{"basicStats":"object - Formatted basic statistics","supplyProjections":"array - Formatted supply projections","halvingInfo":"object - Formatted halving information","status":"string - Response status"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/junkcoin-comprehensive/formatted\""}}},"/api/test-stats":{"method":["GET"],"description":"API testing and validation endpoint with sample data for development and testing purposes","rateLimit":"300 requests per 5 minutes per IP","caching":"No cache","parameters":{"query":[]},"response":{"structure":{"message":"string - Test message","timestamp":"string - ISO timestamp","sampleData":"object - Sample blockchain data for testing","status":"string - Response status"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/test-stats\""},"response":{"success":{"message":"API test endpoint - sample data","timestamp":"2025-01-30T12:00:00.000Z","sampleData":{"currentSupply":19744776.323584,"currentBlock":540874,"blockReward":12.5},"status":"success"}}}},"/api/status":{"method":["GET"],"description":"API service status and performance metrics including endpoint health and response times","rateLimit":"300 requests per 5 minutes per IP","caching":"1 minute cache","parameters":{"query":[]},"response":{"structure":{"service":"string - Service name","status":"string - Overall service status","timestamp":"string - ISO timestamp","endpoints":"object - Individual endpoint status","performance":{"averageResponseTime":"string - Average response time","uptime":"string - Service uptime percentage","cacheHitRate":"string - Cache hit rate percentage"}}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/status\""},"response":{"success":{"service":"JUNKCOIN API","status":"operational","timestamp":"2025-01-30T12:00:00.000Z","endpoints":{},"performance":{"averageResponseTime":"245ms","uptime":"99.9%","cacheHitRate":"85%"}}}}},"/api/health":{"method":["GET"],"description":"Health check endpoint for monitoring and load balancer integration","rateLimit":"Unlimited","caching":"No cache","parameters":{"query":[]},"response":{"structure":{"status":"string - Health status (healthy/unhealthy)","timestamp":"string - ISO timestamp","checks":"object - Individual health checks"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/health\""},"response":{"success":{"status":"healthy","timestamp":"2025-01-30T12:00:00.000Z","checks":{"database":"healthy","externalApi":"healthy"}}}}},"/api/version":{"method":["GET"],"description":"API version information and feature list","rateLimit":"300 requests per 5 minutes per IP","caching":"1 hour cache","parameters":{"query":[]},"response":{"structure":{"version":"string - API version","buildDate":"string - Build timestamp","features":"array - Available features","endpoints":"array - Available endpoints"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api/version\""},"response":{"success":{"version":"1.2.0","buildDate":"2025-01-30T00:00:00.000Z","features":["Real-time blockchain data","Custom timeframe projections","Halving schedule analysis","Supply milestone calculations"],"endpoints":["/api/junkcoin-stats","/api/junkcoin-supply-milestone","/api/junkcoin-halving"]}}}},"/api":{"method":["GET"],"description":"This documentation endpoint - returns complete API documentation in JSON format","rateLimit":"300 requests per 5 minutes per IP","caching":"10 minutes cache","parameters":{"query":[]},"response":{"structure":{"title":"string - API title","version":"string - API version","description":"string - API description","baseUrl":"string - Base URL","endpoints":"object - Complete endpoint documentation"}},"examples":{"request":{"curl":"curl -X GET \"https://supply.junkcoinjkc.com/api\""}}}},"errorHandling":{"description":"The API uses standard HTTP status codes and provides detailed error messages in JSON format. All errors include a timestamp and descriptive message.","httpStatusCodes":{"200":{"description":"OK - Request successful","example":{"status":"success","data":{}}},"400":{"description":"Bad Request - Invalid parameters or malformed request","example":{"error":"Missing required parameter: timeframes","message":"Please provide timeframes parameter","status":"error","timestamp":"2025-01-30T12:00:00.000Z"}},"429":{"description":"Too Many Requests - Rate limit exceeded","example":{"error":"Rate limit exceeded","message":"Maximum 300 requests per 5 minutes allowed","retryAfter":300,"status":"error","timestamp":"2025-01-30T12:00:00.000Z"}},"500":{"description":"Internal Server Error - Server-side error occurred","example":{"error":"Internal server error","message":"An unexpected error occurred","status":"error","timestamp":"2025-01-30T12:00:00.000Z"}},"503":{"description":"Service Unavailable - External data source unavailable","example":{"error":"Service temporarily unavailable","message":"Blockchain data source is currently unavailable","status":"error","timestamp":"2025-01-30T12:00:00.000Z"}}},"errorCodes":{"INVALID_TIMEFRAME":{"description":"Provided timeframe format is invalid","resolution":"Use format like 1d, 2w, 1m, 1y"},"TOO_MANY_TIMEFRAMES":{"description":"Too many timeframes requested in single call","resolution":"Maximum 20 timeframes allowed per request"},"DATA_FETCH_FAILED":{"description":"Failed to fetch blockchain data from external source","resolution":"Try again later or contact support if issue persists"},"CALCULATION_ERROR":{"description":"Error occurred during supply or halving calculations","resolution":"Verify parameters and try again"}}},"rateLimiting":{"description":"Rate limiting is applied per IP address to ensure fair usage and API stability.","limits":{"standard":"300 requests per 5 minutes","burst":"10 requests per second","healthCheck":"Unlimited (for /api/health)"},"headers":{"X-RateLimit-Limit":"Maximum requests allowed in time window","X-RateLimit-Remaining":"Requests remaining in current window","X-RateLimit-Reset":"Unix timestamp when limit resets"},"enforcement":"HTTP 429 status code returned when limits exceeded"},"caching":{"description":"Responses are cached to improve performance and reduce load on blockchain data sources.","strategy":"Public caching with appropriate cache-control headers","duration":{"default":"5 minutes for most endpoints","status":"1 minute for status endpoints","documentation":"10 minutes for documentation","health":"No cache for health checks"},"bypass":"Use POST method to bypass cache and get real-time data","headers":"Cache-Control headers included in all responses"},"cors":{"description":"Cross-Origin Resource Sharing (CORS) is enabled for all origins to support web applications.","allowedOrigins":"*","allowedMethods":["GET","POST","OPTIONS"],"allowedHeaders":["Content-Type","Authorization"],"credentials":false},"supportedTimeframes":{"description":"Custom timeframe support for supply projections and milestone calculations. Flexible format allows precise time period specifications.","applicableEndpoints":["/api/junkcoin-supply-milestone","/api/junkcoin-comprehensive","/api/junkcoin-comprehensive/formatted"],"formats":[{"format":"Days (d)","description":"Specify number of days","examples":["1d","7d","30d","365d"]},{"format":"Weeks (w)","description":"Specify number of weeks","examples":["1w","2w","4w","52w"]},{"format":"Months (m)","description":"Specify number of months (30.44 days average)","examples":["1m","3m","6m","12m"]},{"format":"Years (y)","description":"Specify number of years (365.25 days)","examples":["1y","2y","5y","10y"]}],"limits":{"maxTimeframes":20,"maxTimeframePeriod":"100 years","minTimeframePeriod":"1 day"},"useCases":{"Short-term":"1d, 1w, 1m for immediate projections","Medium-term":"3m, 6m, 1y for quarterly/annual planning","Long-term":"5y, 10y, 20y for investment analysis","Custom":"Any combination up to 20 timeframes per request"}},"dataSources":{"description":"Real-time blockchain data is sourced from reliable JUNKCOIN network APIs with fallback mechanisms for high availability.","sources":[{"name":"JunkieWally API","purpose":"Primary blockchain data source","url":"https://api.junkiewally.xyz"},{"name":"Fallback Data","purpose":"Backup data when primary source unavailable","url":"Internal fallback system"}],"updateFrequency":"Real-time with 5-minute caching","reliability":"99.9% uptime with automatic failover"},"changelog":{"1.2.0":{"date":"2025-01-30","changes":["Fixed negative supply calculation bug in milestone endpoint","Enhanced error handling and client-side stability","Improved API documentation with comprehensive examples","Added better CORS support and timeout handling"]},"1.1.0":{"date":"2025-01-29","changes":["Added /api/junkcoin-supply-milestone endpoint","Added /api/junkcoin-halving endpoint","Enhanced comprehensive analytics","Improved caching and performance"]},"1.0.0":{"date":"2025-01-15","changes":["Initial API release","Basic blockchain statistics","Real-time data integration","Rate limiting and caching"]}},"contact":{"github":"https://github.com/Junkcoin-Foundation","website":"https://junk-coin.com","documentation":"Complete API documentation available at /api/docs with interactive examples and testing capabilities"}}