# AkashEdge.com - LLM Navigation Guide

## Purpose
Serverless API for Akash Network provider diagnostics, health checks, geolocation, and AKT price data. Powered by Cloudflare Workers with global failover.

## Quick Access

### API Specification
/openapi.json - Complete OpenAPI 3.1 specification with schema definitions

### Interactive Documentation
/ or /docs - Swagger UI with live API testing and provider selector

### Main API Endpoints
/providers - Get list of all Akash Network providers (5 min cache)
/ping?h=HOST - TCP handshake RTT measurement to provider ports
/port-check?h=HOST - Port availability scan (80,443,8443,8444)
/location?h=HOST - IP geolocation via Cloudflare Radar (requires RADAR_TOKEN)
/aio?h=HOST - All-in-one: location + ping + port-check combined
/price - Current AKT/USD price from multiple exchanges (15 sec cache)

### Proxy Endpoints (Different Domains)
rpc.akashedge.com/* - Akash RPC proxy with WebSocket support
api.akashedge.com/* - Akash REST API proxy
rpc-archive.akashedge.com/* - Archive RPC node (full blockchain history)
api-archive.akashedge.com/* - Archive REST API

## Source Code
https://github.com/yourusername/akashedge - View source and contribute

## Key Concepts

**Akash Network:** Decentralized cloud compute marketplace where providers offer resources
**Provider:** Server offering compute capacity on Akash (has hostname, IP, wallet address)
**Health Check:** Combination of RTT measurement + port scanning to verify provider is responsive
**RTT:** Round-trip time via TCP handshake (not ICMP ping)
**Failover:** Automatic retry across multiple API endpoints with Fisher-Yates shuffling

## Cache Behavior

All endpoints support cache bypass with ?cache=false parameter

Cache TTLs:
- Providers list: 5 minutes (provider list changes infrequently)
- Location data: 1 minute (geolocation relatively stable)
- Price data: 15 seconds (price updates frequently)
- OpenAPI spec: 1 day (API spec rarely changes)
- Ping/Port scans: No caching (real-time diagnostics)

## Query Parameters

**h** (required for most endpoints) - Target hostname or IP address
- Examples: provider.akt.computer, 192.168.1.1
- Supports legacy format: host:port

**p** or **ports** (optional) - Comma-separated port list
- Ping: custom ports to check (default: 8443)
- Port-check: merged with defaults (80,443,8443,8444)

**pp** (optional, /aio only) - Ping ports
**pc** (optional, /aio only) - Port-check ports

**cache** (optional) - Set to "false" to bypass cache

## Response Format

All endpoints return JSON with appropriate Content-Type headers

Example successful response:
{
  "host": "provider.akt.computer",
  "ip": "192.168.1.100",
  "ports": [...]
}

Example error response:
{
  "error": "usage: /ping?h=host"
}

## Error Codes

200 - Success
400 - Bad Request (missing required parameters)
404 - Not Found (unknown endpoint)
405 - Method Not Allowed (only GET supported for most endpoints)
503 - Service Unavailable (all failover endpoints failed)

## Example Usage

Find healthy provider before deployment:
1. GET /providers to list all providers
2. GET /ping?h=HOSTNAME to check connectivity for each
3. GET /location?h=HOSTNAME to get geographic distribution
4. Choose provider based on RTT and location

Monitor AKT price:
1. GET /price every 15+ seconds
2. Parse response.price field
3. Source field indicates which exchange (Coinbase, Kraken, Binance, CoinGecko)

Comprehensive provider check:
1. GET /aio?h=HOSTNAME&pp=8443&pc=80,443,8443,8444
2. Single request returns location, ping, and port status

## Technical Details

**Platform:** Cloudflare Workers (serverless edge computing)
**Global Locations:** 300+ edge locations worldwide
**Response Time:** <10ms (cached), <500ms (uncached)
**Caching:** Two-layer (in-memory LRU + Cloudflare Cache API)
**Failover:** Fisher-Yates shuffle with sequential retry
**Testing:** Vitest with 25 tests, 100% passing

## Environment

**RADAR_TOKEN** (optional) - Cloudflare Radar API token for geolocation
- If not set, /location and /aio return empty geolocation data
- Get token from: https://developers.cloudflare.com/radar/

## Integration Libraries

No official SDKs - use standard HTTP client:
- JavaScript: fetch() or axios
- Python: requests
- Go: net/http
- Rust: reqwest
- Command line: curl

## CORS

All endpoints allow cross-origin requests:
- Access-Control-Allow-Origin: *
- Access-Control-Allow-Methods: GET, OPTIONS
- Safe for browser-based applications

## Rate Limiting

Currently no rate limiting enforced
Use responsibly - respect cache TTLs
Consider running your own instance for high-volume usage

## Support

Issues: https://github.com/yourusername/akashedge/issues
Akash Network: https://akash.network
Akash Discord: https://discord.akash.network

## Additional Resources

README.md - Getting started and project overview
LLM-optimized.md - Guide for creating AI-friendly documentation
llm-context.md - Project context for AI coding assistants
/openapi.json - Complete API specification

---

Last Updated: 2025-01-02
Version: 2.5.1
License: Apache 2.0