______                            __        ______ _
  / ____/___  ____ ___  ____  __  __/ /____   / ____/(_)
 / /   / __ \/ __ `__ \/ __ \/ / / / __/ _ \ / /_  / /
/ /___/ /_/ / / / / / / /_/ / /_/ / /_/  __// __/ / /
\____/\____/_/ /_/ /_/ .___/\__,_/\__/\___/_/   /_/
                    /_/

ComputeFi API Endpoints

Public API surface for ComputeFi market intelligence on Base.

API Surface · Environment · Release Preflight

---

This repo contains the ComputeFi backend API: read-only market data, read-only Base intelligence, the paid IROS query lifecycle, transaction history, and the MCP tool gateway. It is organized so public routes are auditable and write-heavy product/admin routes are isolated behind internal controls.

---

Route Trust Model

Trust level	Prefix	Purpose
Public health	/health, /api/status, /api/version	Liveness and deployment metadata
Public read-only data	/api/feeds/*, /api/iros/*, /api/base/*, /api/mcp/tools	Market, IROS, Base, and MCP catalog reads
Paid lifecycle	/api/query/*	Quote, lock, verify payment, and process paid IROS queries
Wallet scoped history	/api/transactions/list	Wallet-filtered query/payment records
MCP execution	/api/mcp/playground/execute	Read-only tool execution, bearer-gated when MCP_API_KEY is set
Webhooks	/api/webhooks/*	Provider callbacks with route-specific authentication
Internal/admin	/api/internal/*	Mission, Watch, Telegram, CROTA, and AI helper controls

Internal routes are disabled unless ENABLE_INTERNAL_API=true. In production, they also require INTERNAL_API_KEY.

---

Public Endpoints

Health And Metadata

Endpoint	Method	Purpose
/health	GET	Liveness check
/api/status	GET	Basic API status
/api/version	GET	API name and version metadata

Market Data

All market data endpoints are read-only and return degraded source states when upstreams are unavailable.

Endpoint	Method	Purpose
/api/feeds/fear-greed	GET	Fear and greed reading
/api/feeds/funding	GET	Funding rates for major markets
/api/feeds/oi-by-exchange/:symbol?	GET	Open interest by venue
/api/feeds/liquidations/:symbol?	GET	Long/short liquidation context
/api/feeds/etf-flows	GET	BTC ETF flow proxy
/api/feeds/exchange-netflow/:symbol?	GET	Exchange inflow/outflow signal
/api/feeds/dominance	GET	Market dominance snapshot
/api/feeds/stablecoins	GET	Stablecoin cap and flow snapshot
/api/feeds/network-activity	GET	Network activity context
/api/feeds/whale-flow	GET	Recent large transfer flow
/api/feeds/top-traders/:symbol?	GET	Top trader positioning proxy
/api/feeds/taker-pressure/:symbol?	GET	Taker buy/sell pressure
/api/feeds/options/:symbol?	GET	Options context
/api/feeds/orderbook/:symbol?	GET	Order book pressure
/api/feeds/large-orders/:symbol?	GET	Large order feed
/api/feeds/cvd/:symbol?	GET	Cumulative volume delta
/api/feeds/volatility/:symbol?	GET	Volatility regime
/api/feeds/derivatives/:symbol?	GET	Derivatives summary
/api/feeds/session	GET	Current trading session
/api/feeds/snapshot/:symbol?	GET	Aggregated market snapshot
/api/feeds/fresh-mints	GET	Fresh token mint feed

IROS Context

Endpoint	Method	Purpose
/api/iros/health	GET	IROS and data-network health
/api/iros/klines/:symbol	GET	OHLCV candles
/api/iros/dashboard/:symbol?	GET	Dashboard market context

POST /api/iros/test exists only for local/test mode and returns 403 outside TEST_MODE=true.

Base Intelligence

Read-only Base routes validate addresses, clamp limits, and never expose backend RPC URLs.

Endpoint	Method	Purpose
/api/base/status	GET	Base RPC health, latest block, gas, tx count
/api/base/usdc-transfers	GET	Recent configured-token Transfer events
/api/base/token-lens/:address?	GET	ERC-20 metadata, supply, bytecode, transfers
/api/base/wallet-lens/:owner	GET	Wallet balances, nonce, USDC/native activity, counterparties

Legacy read aliases remain available:

• /api/base/token/:address?
• /api/base/wallet/:owner

Paid Query Lifecycle

Endpoint	Method	Purpose
/api/query/estimate	POST	Validate query and quote USDC cost
/api/query/submit	POST	Create a pending query lock and unsigned payment transaction
/api/query/process	POST	Verify Base payment and return standard IROS response
/api/query/process/stream	POST	Verify Base payment and stream IROS phases, sources, deltas, and final result

Payment verification and replay checks complete before model execution. The streaming route does not emit model deltas until payment verification passes.

Transactions

Endpoint	Method	Purpose
/api/transactions/list?userWallet=0x...	GET	Wallet-scoped paid query history

MCP

Endpoint	Method	Purpose
/api/mcp/tools	GET	Read-only MCP tool catalog
/api/mcp/playground/execute	POST	Read-only tool execution, gated by MCP_API_KEY when configured
/api/mcp/manifest	GET	Public endpoint/tool manifest
/api/mcp/status	GET	Sanitized subsystem heartbeat

All MCP tools are registered through src/mcp/registry.ts and execute through src/mcp/dispatch.ts.

---

Internal Routes

Internal routes are mounted under /api/internal/* and are not part of the public API contract.

Prefix	Purpose
/api/internal/base/*	AI wallet explanation, trade desk, and memory reads
/api/internal/crota/*	CROTA partner bridge
/api/internal/iros/plans/*	IROS plan extraction
/api/internal/missions/*	Mission CRUD and events
/api/internal/telegram/*	Telegram linking and delivery controls
/api/internal/watch/*	Watch rules, Sentinel controls, alert history mutation

Webhooks live under /api/webhooks/* and use route-specific authentication.

---

Project Structure

src/
|-- index.ts              # Express bootstrap and route registration
|-- env.ts                # Environment parsing and validation
|-- config/               # Base chain and token config
|-- middleware/           # Auth and internal route guards
|-- routes/               # Public, webhook, and internal route modules
|-- services/             # Base, IROS, feeds, missions, Telegram, pricing
|-- mcp/                  # MCP registry, dispatch, normalization, bulk catalog
|-- realtime/             # Sentinel WebSocket attachment
`-- contracts/            # Mission and plan contracts

---

Environment

cp env.example .env

Required for production paid query processing:

Variable	Purpose
BASE_RPC_URL	Base RPC endpoint
COMPUTE_TOKEN_ADDRESS	Payment token, defaults to Base USDC
TREASURY_ADDRESS	Treasury wallet receiving payments
ANTHROPIC_API_KEY	IROS model provider key
MCP_API_KEY	Optional bearer gate for MCP execution

Optional provider keys are documented in env.example.

---

Development

npm install
cp env.example .env
npm run dev

Default local URL:

http://localhost:3001

---

Verification

npm run build
npm run test
npm run release:preflight

npm run release:preflight checks neutral commit identity, active machine-user GitHub auth, release remote ownership, whitespace, and obvious public-release leaks.

---

Release

Public release commits must use:

ComputeFi Team <ops@computefi.org>

The intended public target is:

https://github.com/ComputeFi/ComputeFi-API-Endpoints

Do not commit secrets, .env files, local paths, handoff notes, personal usernames, generated build output, or deployment-only scratch files.

---

License

ComputeFi API Endpoints is released under the MIT License.