# MorScan
> Morpheus blockchain explorer and real-time API by DRM3 Labs. A real-time indexed data source for the Morpheus AI network on Base. All data sourced from attested on-chain state with cryptographic provenance receipts.

## What It Is
MorScan indexes Morpheus compute, builder, and token contracts on Base L2 and serves instant API responses. It tracks AI compute providers, model marketplace bids, MOR token staking sessions, builder subnets, token pricing, and network economics. Data is indexed in real time and every API response is signed with a provenance receipt for auditability.

## For Agents (quickstart)
- Auth: send X-Morscan-Key on every /mor/v1/* request (exception: /mor/v1/price is public)
- Keys: connect a wallet at https://morscan.io/console for a free key (10 req/min, 2,000/day, 40,000/month - no email, no signup); staked capacity scales at 3 req/min per MOR staked on the MorScan builder subnet, volume caps rise with stake and the daily cap is 5% of monthly (see https://morscan.io/stake)
- Errors: 200 success; 401 missing/invalid key (get one as above); 429 over your per-minute budget or a day/month volume cap (day caps reset 00:00 UTC), Retry-After header set; 500 unexpected, retry with backoff, check /health
- Provenance: every response row carries a _receipt id and responses are Ed25519-signed; public keys at https://morscan.io/.well-known/morscan-keys.json for offline verification
- Registration + limits guide (markdown): https://morscan.io/auth.md
- API catalog (RFC 9727): https://morscan.io/.well-known/api-catalog
- Agent skills (task-level how-tos with sha256-pinned docs): https://morscan.io/.well-known/agent-skills/index.json
- MCP server card (HTTP API integration point; no MCP JSON-RPC transport today): https://morscan.io/.well-known/mcp/server-card.json
- Markdown pages: GET /, /about, /contribute, /stake with "Accept: text/markdown" returns markdown

## Getting a Key
Connect a wallet at https://morscan.io/console - signing a challenge message is the
whole registration and issues your personal key immediately. Staking MOR on the
MorScan builder subnet raises that same key's capacity. Pass the key via the
X-Morscan-Key header on all /mor/v1/* requests.

## API Endpoints

### No Auth Required
- GET /health - service status, block heights, sync lag, version
- GET /mor/v1/price - MOR/USD read on-chain from the Base DEX (Uniswap v3 MOR/WETH), ETH/USD from Chainlink on Base (~30s cache)
- GET /chart.svg - pre-rendered 90-day MOR price chart (SVG)
- GET /teaser - public summary stats for the login page
- GET /openapi.json - OpenAPI 3.1 specification
- GET /llms.txt - this file
- GET /llms-full.txt - extended version with response examples
- GET /auth.md - how agents register and authenticate (markdown)
- GET /.well-known/api-catalog - RFC 9727 API catalog linkset
- GET /.well-known/agent-skills/index.json - agent skill docs index
- GET /.well-known/mcp/server-card.json - MCP-style server card (describes the HTTP API)

### Marketplace (X-Morscan-Key required)
- GET /mor/v1/all - full marketplace state (providers, bids, models, economics)
- GET /mor/v1/providers - registered AI compute providers
- GET /mor/v1/providers/:address - provider detail (bids, sessions, reputation)
- GET /mor/v1/bids - all model bids with pricing

### Sessions and Analytics (X-Morscan-Key required)
- GET /mor/v1/sessions - all sessions (paginated)
- GET /mor/v1/sessions/:wallet - sessions for a specific wallet
- GET /mor/v1/sessions/analytics - per-wallet analytics
- GET /mor/v1/sessions/daily - daily session counts (30-day history)
- GET /mor/v1/wallet/:wallet - full wallet detail with balances
- GET /mor/v1/wallet/:wallet/transactions - wallet transaction history
- GET /mor/v1/wallet/:wallet/gas - wallet gas cost breakdown
- GET /mor/v1/analytics - gas costs, network economics

### Models (X-Morscan-Key required)
- GET /mor/v1/models - all registered models with names
- GET /mor/v1/models/lookup - model ID to name mapping
- GET /mor/v1/models/demand - model demand heatmap (sessions, pricing, providers)
- GET /mor/v1/models/:modelId - specific model details

### Provider Reputation (X-Morscan-Key required)
- GET /mor/v1/reputation - all provider reputation scores
- GET /mor/v1/reputation/:provider - detailed reputation for a provider
- GET /mor/v1/disputes - recent disputed sessions
- GET /mor/v1/leaderboard - top providers and wallets

### Pricing (X-Morscan-Key required)
- GET /mor/v1/price/chart - 90-day price history data

### Provenance (X-Morscan-Key required)
- GET /mor/v1/provenance - audit trail of signed API responses (receipt chain, signer public key)

### Sync Status (X-Morscan-Key required)
- GET /mor/v1/sync-status - blockchain sync state

## Provenance
Every API response from MorScan is signed with a cryptographic provenance receipt. Receipts form a hash chain for auditability. Query the receipt chain at /mor/v1/provenance.

## Links
- Explorer: https://morscan.io
- OpenAPI Spec: https://morscan.io/openapi.json
- Agent auth guide: https://morscan.io/auth.md
- API catalog: https://morscan.io/.well-known/api-catalog
- Feedback and feature requests: https://github.com/DRM3Labs-OSS/morscan.io/issues