# 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)

Access (every listed door is live today):
- Free key: connect a wallet at https://morscan.io/console and sign one challenge (no email, no signup, no payment) - 60 req/min, 2,000/day, 40,000/month. Headless mint: GET /console/wallet/challenge, sign with EIP-191 personal_sign, POST /console/wallet/verify.
- Stake for more: stake MOR on the MorScan builder subnet and the same key's caps follow your live stake (3 req/min per MOR staked; volume caps rise with stake and the daily cap is 5% of the monthly cap). Your principal stays yours. See https://morscan.io/stake
- Pay per call with x402: no key at all - a keyless call to a metered endpoint returns 402 with an x402 envelope (x402.org); pay 0.01 USDC per call on Base (eip155:8453) via a signed EIP-3009 X-PAYMENT header. Verified at request time, settled on-chain in batches. See https://morscan.io/auth.md
- Buy a call pack with x402: POST https://morscan.io/mor/v1/keys/purchase with no payment header returns 402 listing the pack prices as x402 accepts entries (e.g. 10,000 calls for 1 USDC); retry with a signed X-PAYMENT for exactly one pack price and the response includes an API key (mspk_..., send as X-Morscan-Key) carrying that prepaid call balance. Calls never expire; the payment settles on-chain at purchase.

- Errors: 200 success; 401 invalid key; 402 keyless on a metered endpoint (x402 payment envelope - pay per call or mint the free key); 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
- Pagination: list endpoints return at most 100 rows per page (limit clamped server-side, applied value echoed in pagination meta); use page to paginate, max depth 1000
- 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; human-facing in-browser check at https://morscan.io/verify
- 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. Fully headless
works too (no browser): GET /console/wallet/challenge, sign the returned
message with EIP-191 personal_sign, POST the result to /console/wallet/verify -
the 3-step recipe with examples is in https://morscan.io/auth.md. 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 - model name and description
- GET /mor/v1/models/:modelId/detail - the canonical-model picture: every on-chain listing of the model aggregated (any listing id of the model returns the same content) - description, active bids with providers and pricing, session demand + 30-day daily series, per-provider reputation, the listing inventory with web/TEE capability flags, and the model family rollup. Human page: /compute/models/:modelId

### 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