API Documentation

Contract Management Endpoints

Store Contract

POST /contracts/store Payload:

{
  "contractAddress": "0x123...",
  "deployedBy": "0xabc...",
  "network": "arbitrum-sepolia"
}

Response (success):

{ "success": true, "contractAddress": "0x123...", "message": "Stored" }

List Contracts

GET /contracts/list?network=arbitrum-sepolia Returns paginated list with categories (discovered, checked, opted-in, cached).

Check Cache Status

GET /contracts/cache-status/{contractAddress} Returns current status, last ROI calculation, and historical bid attempts.

Place Bid

POST /contracts/place-bid Payload:

{
  "contractAddress": "0x123...",
  "network": "arbitrum-one" // optional; defaults to app NETWORK
}

Response:

{ "success": true, "wasCached": true, "txHash": "0x..." }

---

Real-time Monitoring Endpoints

Get Tracked Contracts

GET /api/tracked-contracts Returns arrays of allContracts, optedInContracts, checkedContracts, successfullyCachedContracts, and real-time connection flags.

Example partial response:

{
  "allContracts":["0x1...","0x2..."],
  "counts":{ "total":2, "optedIn":1, "checked":2, "cached":1 },
  "realtimeStatus":{ "websocketConnected": true }
}

Real-time Status

GET /api/realtime-status Shows WS health, topic listener status, and discovery stats.

---

Manual Contract Operations

Trigger Opt-in Check

POST /api/check-contract-optin Body:

{ "contractAddress":"0x..." }

Response:

{
  "success": true,
  "contractAddress": "0x...",
  "isOptedIn": true,
  "wasChecked": true
}

Trigger Caching Attempt

POST /api/cache-contract Body:

{ "contractAddress": "0x..." }

Response:

{ "success": true, "wasCached": true, "totalCached": 3 }

---

Performance & Status Endpoints

• GET /performance/bid-cache — view bid-value cache performance and TTL stats

• GET /performance/database-health — DB connection and health metrics

• POST /performance/initialize-bid-cache — force-initialize bid-value cache

• GET /status — system overview

• POST /status/analyze/{address} — manual analysis of contract