{"openapi":"3.1.0","info":{"title":"AkashEdge : Serverless API for Akash Network powered by Cloudflare","version":"2.5.1","description":"## Free Akash Network RPC & API Endpoints\n\n**AkashEdge** provides free, globally distributed **RPC and REST API endpoints** for the **Akash Network blockchain**:\n\n* 🌐 **RPC Endpoint**: `https://rpc.akashedge.com` - Akash blockchain RPC node with WebSocket support\n* 🌐 **REST API Endpoint**: `https://api.akashedge.com` - Akash Cosmos REST API\n* 📚 **Archive RPC Node**: `https://rpc-archive.akashedge.com` - Full blockchain history\n* 📚 **Archive REST API**: `https://api-archive.akashedge.com` - Historical data access\n\n### Why AkashEdge RPC/API?\n\n* ✅ **Free & Public** - No API keys required\n* ✅ **WebSocket Support** - Real-time blockchain data subscriptions\n* ✅ **Automatic Failover** - Tries multiple Akash RPC nodes for reliability\n* ✅ **Global CDN** - Sub-10ms response from 300+ Cloudflare edge locations\n* ✅ **Archive Nodes** - Access complete Akash blockchain history\n\n---\n\n## Additional API Features\n\n**AkashEdge**: an always-on, serverless API for the Akash Network, running on Cloudflare Workers with global failover.\n\nAccess low-latency, edge-deployed endpoints:\n\n* **Providers**: real-time on-chain provider list with automatic REST fallback.\n* **Online Providers**: curated list of currently active and responsive providers.\n* **Ping**: sub-5s TCP handshake RTT measurements (default port: 8443).\n* **Port Check**: fast port availability scans (default ports: 80, 443, 8443, 8444).\n* **Location**: IP geolocation and ASN lookup via Cloudflare Radar.\n* **Composite**: combined diagnostics and location info in one call.\n* **Price**: AKT/USD pricing from top exchanges with automatic failover.\n* **OpenAPI Spec**: Machine-readable API specification at `/openapi.json`.\n* **RPC/API Nodes**: Transparent proxy to Akash blockchain nodes\n  - `rpc.akashedge.com` - Akash RPC proxy with WebSocket support and automatic failover\n  - `api.akashedge.com` - Akash REST API proxy with automatic failover\n  - Multiple backend endpoints with automatic failover\n  - Fisher-Yates shuffle for load balancing\n  - No caching - real-time blockchain data\n\n### Archive Nodes (Direct Routes)\n\nDirect connections to archive nodes with full blockchain history:\n\n* **Archive RPC**: `https://rpc-archive.akashedge.com` - Full RPC with complete block history\n* **Archive API**: `https://api-archive.akashedge.com` - Full REST API with historical data\n\n_Note: Archive nodes are direct DNS routes, not proxied through this Cloudflare Workers app._\n\n---\n\n### Cache Settings\n\nDefault cache TTL (Time To Live) for each endpoint:\n\n* **Providers**: 5 minutes\n* **Online Providers**: No caching (GitHub proxy)\n* **Location**: 1 minute\n* **Price**: 15 seconds\n* **OpenAPI Spec**: 1 day\n* **Ping/Port Check**: No caching (real-time measurements)\n* **AIO**: Location cached (1 min), ping/port-check not cached\n* **RPC/API Proxies**: No caching (real-time blockchain data)\n* Add `?cache=false` to any endpoint to bypass all caching layers\n\n---\n\n### Timeouts & Performance\n\n* **Regular API calls**: 3-second timeout\n* **Proxy requests**: 60-second timeout\n* **Parallel limit**: 3 concurrent connections per scan\n\n---\n\n### 🤖 For AI/LLM Integration\n\n* **[/llms.txt](/llms.txt)** - LLM navigation guide (web scraping optimized)\n* **[llm-context.md](./llm-context.md)** - Project context for AI coding assistants\n* **[LLM-optimized.md](./LLM-optimized.md)** - Guide for creating AI-friendly documentation\n* **[EXAMPLES.md](./EXAMPLES.md)** - Real-world integration patterns\n* **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System design documentation\n\n---\n\n### Static Assets\n\n* **[/akashedge-logo-triangle-only.svg](/akashedge-logo-triangle-only.svg)** - Logo (SVG format)\n* **[/akashedge-logo-triangle-only.ico](/akashedge-logo-triangle-only.ico)** - Favicon"},"servers":[{"url":"https://akashedge.com"}],"tags":[{"name":"Providers","description":"Akash On-chain providers"},{"name":"Ping","description":"Single-packet RTT checks"},{"name":"Port Check","description":"Port availability scans"},{"name":"Location","description":"Geolocate via Cloudflare Radar"},{"name":"Composite","description":"All-in-one convenience call"},{"name":"Price","description":"AKT cryptocurrency price information"},{"name":"WebSocket","description":"Real-time blockchain event subscriptions via RPC proxy"},{"name":"Documentation","description":"API specification and documentation"}],"paths":{"/providers":{"get":{"tags":["Providers"],"summary":"List Akash providers (automatic REST fallback)","parameters":[{"name":"cache","in":"query","required":false,"description":"Set to \"false\" to bypass cache and fetch fresh data","schema":{"type":"string","enum":["true","false"],"default":"true"}}],"responses":{"200":{"description":"Array of provider objects","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"wallet":{"type":"string"},"host_uri":{"type":"string"},"hostname":{"type":"string"},"domain":{"type":"string"}}}}}}}}}},"/online-providers":{"get":{"tags":["Providers"],"summary":"List only online Akash providers (port 8443 accessible)","description":"Returns the same data as /providers but filtered to only include providers with accessible port 8443. Uses background refresh with 60-second cache. **First request returns empty array** and triggers background scan with 1-second timeout per hostname. Subsequent requests (after 30-60 seconds) return cached results with online providers.","parameters":[{"name":"cache","in":"query","required":false,"description":"Set to \"false\" to bypass cache and fetch fresh data","schema":{"type":"string","enum":["true","false"],"default":"true"}}],"responses":{"200":{"description":"Array of online provider objects","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"wallet":{"type":"string"},"host_uri":{"type":"string"},"hostname":{"type":"string"},"domain":{"type":"string"}}}}}}}}}},"/ping":{"get":{"tags":["Ping"],"summary":"TCP handshake RTT to one or more ports","parameters":[{"name":"h","in":"query","required":true,"description":"Host to ping","schema":{"type":"string","example":"provider.akt.computer"}},{"name":"p","in":"query","required":false,"description":"Comma-separated list of ports to ping","schema":{"type":"string","example":""}}],"responses":{"200":{"description":"Ping result JSON","content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string"},"ip":{"type":"string"},"ports":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"integer"},"rtt_ms":{"type":"integer","nullable":true},"status":{"type":"string","enum":["open","closed"]}}}}}}}}},"400":{"description":"Bad Request - Missing host parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/port-check":{"get":{"tags":["Port Check"],"summary":"Check default Akash provider ports for reachability","parameters":[{"name":"h","in":"query","required":true,"description":"Host to check","schema":{"type":"string","example":"provider.akt.computer"}},{"name":"p","in":"query","required":false,"description":"Comma-separated list of ports to check","schema":{"type":"string","example":""}}],"responses":{"200":{"description":"Scan result JSON","content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string"},"ip":{"type":"string"},"ports":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"integer"},"rtt_ms":{"type":"integer","nullable":true},"status":{"type":"string","enum":["open","closed"]}}}}}}}}},"400":{"description":"Bad Request - Missing host parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/location":{"get":{"tags":["Location"],"summary":"Geo / ASN lookup via Cloudflare Radar","parameters":[{"name":"h","in":"query","required":false,"description":"Host to geolocate (defaults to provider.akt.computer)","schema":{"type":"string","example":"provider.akt.computer"}},{"name":"cache","in":"query","required":false,"description":"Set to \"false\" to bypass cache and fetch fresh data","schema":{"type":"string","enum":["true","false"],"default":"true"}}],"responses":{"200":{"description":"Location metadata","content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string"},"ip":{"type":"string"},"asn":{"type":"integer","nullable":true},"org":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"continent":{"type":"string","nullable":true},"subregion":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true}}}}}}}}},"/aio":{"get":{"tags":["Composite"],"summary":"All-in-one: location + ping + port-check","parameters":[{"name":"h","in":"query","required":false,"description":"Host to use for all checks (defaults to provider.akt.computer)","schema":{"type":"string","example":"provider.akt.computer"}},{"name":"pp","in":"query","required":false,"description":"Comma-separated list of ping ports","schema":{"type":"string","example":""}},{"name":"pc","in":"query","required":false,"description":"Comma-separated list of ports to check","schema":{"type":"string","example":""}}],"responses":{"200":{"description":"Composite result","content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string"},"ip":{"type":"string"},"asn":{"type":"integer","nullable":true},"org":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"continent":{"type":"string","nullable":true},"subregion":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"ping":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"integer"},"rtt_ms":{"type":"integer","nullable":true},"status":{"type":"string","enum":["open","closed"]}}}},"port_check":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"integer"},"rtt_ms":{"type":"integer","nullable":true},"status":{"type":"string","enum":["open","closed"]}}}}}}}}}}}},"/price":{"get":{"tags":["Price"],"summary":"Get current AKT/USD price from multiple sources with failover","parameters":[{"name":"cache","in":"query","required":false,"description":"Set to \"false\" to bypass cache and fetch fresh data","schema":{"type":"string","enum":["true","false"],"default":"true"}}],"responses":{"200":{"description":"Current AKT price in USD","content":{"application/json":{"schema":{"type":"object","properties":{"price":{"type":"number"},"currency":{"type":"string"},"source":{"type":"string"},"timestamp":{"type":"integer"}}}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/openapi.json":{"get":{"tags":["Documentation"],"summary":"Get OpenAPI specification","responses":{"200":{"description":"OpenAPI 3.1.0 specification in JSON format","content":{"application/json":{"schema":{"type":"object","description":"OpenAPI specification object"}}}}}}},"/":{"get":{"tags":["Documentation"],"summary":"Interactive API documentation (Swagger UI)","responses":{"200":{"description":"HTML page with Swagger UI","content":{"text/html":{"schema":{"type":"string","description":"Swagger UI HTML page"}}}}}}},"/docs":{"get":{"tags":["Documentation"],"summary":"Interactive API documentation (Swagger UI) - alias for /","responses":{"200":{"description":"HTML page with Swagger UI","content":{"text/html":{"schema":{"type":"string","description":"Swagger UI HTML page"}}}}}}}},"x-websocket-info":{"endpoint":"wss://rpc.akashedge.com/websocket","description":"# WebSocket RPC Proxy\n\nConnect to `wss://rpc.akashedge.com/websocket` for real-time blockchain event subscriptions.\n\n## Features\n- **Automatic Failover**: Proxies through 4 RPC endpoints with failover\n- **Transparent Passthrough**: Status 101 WebSocket upgrade handled correctly\n- **60-second Handshake Timeout**: Connection established within timeout window\n- **Full Tendermint RPC Support**: All subscription methods available\n\n## Connection\n```javascript\nconst ws = new WebSocket('wss://rpc.akashedge.com/websocket');\n\nws.onopen = () => {\n  console.log('Connected to AkashEdge RPC WebSocket');\n};\n```\n\n## Available Subscriptions\n\n### Subscribe to New Blocks\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"subscribe\",\n  \"id\": 1,\n  \"params\": {\n    \"query\": \"tm.event='NewBlock'\"\n  }\n}\n```\n\n### Subscribe to Transactions\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"subscribe\",\n  \"id\": 2,\n  \"params\": {\n    \"query\": \"tm.event='Tx'\"\n  }\n}\n```\n\n### Subscribe to Validator Set Updates\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"subscribe\",\n  \"id\": 3,\n  \"params\": {\n    \"query\": \"tm.event='ValidatorSetUpdates'\"\n  }\n}\n```\n\n## Query Filters\n\nCombine conditions with AND/OR operators:\n```\ntm.event='Tx' AND tx.height > 1000\ntm.event='Tx' AND message.sender='akash1...'\n```\n\n## Unsubscribe\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"unsubscribe\",\n  \"id\": 4,\n  \"params\": {\n    \"query\": \"tm.event='NewBlock'\"\n  }\n}\n```\n\n## Error Handling\n```javascript\nws.onerror = (error) => {\n  console.error('WebSocket error:', error);\n};\n\nws.onclose = (event) => {\n  console.log('Disconnected. Reconnecting...');\n  setTimeout(() => reconnect(), 1000);\n};\n```\n\n## Message Format\n\n**Subscription Confirmation:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {}\n}\n```\n\n**Event Data:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"query\": \"tm.event='NewBlock'\",\n    \"data\": {\n      \"type\": \"tendermint/event/NewBlock\",\n      \"value\": {\n        \"block\": { ... },\n        \"result_finalize_block\": { ... }\n      }\n    }\n  }\n}\n```\n\n## Connection Tips\n- Use secure WebSocket (wss://) protocol\n- Implement reconnection logic for network interruptions\n- Handle subscription confirmations before assuming success\n- Unsubscribe when no longer needed to reduce server load\n- Monitor connection state with ping/pong or heartbeat messages\n\n## Failover Behavior\nWebSocket connections are transparently proxied through multiple high-reliability RPC endpoints with automatic failover. Endpoints are tried with Fisher-Yates shuffle for load balancing and optimal performance."}}