QQ Omega Supply API

Serverless edge API for CoinMarketCap and CoinGecko token supply tracking across Base L2 and Solana.

Endpoints

Endpoint	Response
GET /v0/:provider/supply/total	Total supply (format varies)
GET /v0/:provider/supply/circulating	Circulating supply
GET /v0/supply	Full JSON breakdown
GET /v0/health	{ status: "ok" }

Supported providers: cmc (CoinMarketCap), coingecko (CoinGecko)

Setup

1. Install dependencies:

   bun install

2. Configure environment variables.

   Local development - create .dev.vars:

   # Required
   BASE_TOKEN_ADDRESS=0x...
   SOL_MINT_ADDRESS=...
   
   # Optional - RPC endpoints (defaults to public endpoints)
   BASE_RPC_URL=https://mainnet.base.org
   SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
   
   # Optional - Base locked wallets (empty = ignored)
   BASE_TREASURY_WALLET=
   BASE_AIRDROP_WALLET=
   BASE_VIRTUAL_AIRDROP_WALLET=
   BASE_TEAM_WALLET=
   BASE_PARTNERSHIP_WALLET=
   
   # Optional - Solana locked wallets (empty = ignored)
   SOL_TREASURY_WALLET=
   SOL_TEAM_WALLET=
   SOL_PARTNERSHIP_WALLET=
   

   Production - use Wrangler secrets:

   wrangler secret put BASE_TOKEN_ADDRESS
   wrangler secret put SOL_MINT_ADDRESS
   wrangler secret put BASE_RPC_URL
   # ... repeat for each variable

   All addresses are validated at request time: EVM via isAddress (viem), Solana via Base58 regex. Token addresses are required, wallet addresses are optional.

3. Local development:

   bun run dev

4. Deploy to Cloudflare:

   bun run deploy

Project Structure

src/
├── index.ts           # Entry point
├── middleware/        # Rate limiting, security headers
├── routes/            # Supply & health endpoints
├── lib/               # Supply calculation, validation
├── types/             # TypeScript interfaces
└── config/            # Routes & token config
test/                  # Unit & integration tests
scripts/               # Deployment utilities

Rate Limiting

10 requests/min per IP (fixed-window, in-memory). Returns standard X-RateLimit-* headers and 429 on limit.

bun run test:rate-limit  # Test locally

Cache Strategy

Edge-cached responses: max-age=30d, stale-while-revalidate=1h

Scripts

Command	Description
bun run dev	Start local dev server (:8787)
bun run deploy	Deploy to Cloudflare Workers
bun run deploy:secrets	Bulk deploy secrets from .dev.vars
bun run test	Run unit tests
bun run test:watch	Run tests in watch mode
bun run test:coverage	Run tests with coverage report
bun run test:integration	Run integration tests (requires dev server)
bun run test:rate-limit	Rate limiter smoke test
bun run lint	Lint with ESLint
bun run format	Format with Prettier
bun run typecheck	TypeScript type checking

Debugging

Press d in wrangler dev for Chrome DevTools.

Tech Stack

• Runtime: Cloudflare Workers (workerd)
• Framework: Hono v4
• EVM Client: viem v2
• Solana: Native fetch (JSON-RPC)
• Package Manager: Bun