{ "openapi": "3.1.0", "info": { "title": "MorScan - Morpheus Blockchain Explorer API", "version": "2.0.0", "description": "Real-time Morpheus blockchain explorer API. Provider, bid, session, and model data with sub-400ms response times. Fetches model names from on-chain ModelRegistry and tracks retracted bid history. All /mor/v1/* endpoints require a valid API key via X-Morscan-Key header." }, "servers": [ { "url": "https://morscan.io", "description": "Live API origin" } ], "paths": { "/health": { "get": { "summary": "Health Check", "description": "Returns sync status, block heights, and database counts.", "tags": [ "Status" ], "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/teaser": { "get": { "summary": "Public Stats", "description": "Quick stats without authentication - for splash screens.", "tags": [ "Status" ], "responses": { "200": { "description": "Basic stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeaserResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/capacity": { "get": { "summary": "Remaining Capacity", "description": "Your remaining rate-limit capacity across all three windows (per-minute, day, month), plus your live MOR stake and wallet. Metered - each call counts against your limits, so you can watch it draw down. Call it 11 times within a minute on the free 10/min tier and the 11th returns 429.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Remaining capacity", "content": { "application/json": { "schema": { "type": "object", "properties": { "perMin": { "type": "object", "properties": { "limit": { "type": "integer", "example": 10 }, "used": { "type": "integer", "example": 3 }, "remaining": { "type": "integer", "example": 7 }, "resetInSeconds": { "type": "integer", "example": 42 } } }, "today": { "type": "object", "properties": { "limit": { "type": "integer", "example": 2000 }, "used": { "type": "integer", "example": 15 }, "remaining": { "type": "integer", "example": 1985 }, "resetsAt": { "type": "string", "format": "date-time" } } }, "month": { "type": "object", "properties": { "limit": { "type": "integer", "example": 40000 }, "used": { "type": "integer", "example": 15 }, "remaining": { "type": "integer", "example": 39985 }, "resetsAt": { "type": "string", "format": "date-time" } } }, "stakeMor": { "type": "number", "example": 0 }, "wallet": { "type": "string", "nullable": true, "example": "0x1234...abcd" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Rate limited - the per-minute cap was reached. Retry-After header indicates when to retry." }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/all": { "get": { "summary": "Full Marketplace", "description": "All providers with their bids (active + retracted), model names from chain.", "tags": [ "Marketplace" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Full marketplace data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/providers": { "get": { "summary": "Provider List", "description": "All registered providers with endpoint info.", "tags": [ "Marketplace" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Provider list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvidersResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/bids": { "get": { "summary": "All Bids", "description": "All bids with model names and pricing.", "tags": [ "Marketplace" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Bid list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BidsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/models": { "get": { "summary": "Model Registry", "description": "All registered models with human-readable names from chain.", "tags": [ "Models" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Model list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/models/lookup": { "get": { "summary": "Model ID Lookup", "description": "Mapping of model IDs to human-readable names.", "tags": [ "Models" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Model ID → name mapping", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "0x972f711716...": "qwen3-235b:web" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/sessions": { "get": { "summary": "All Sessions", "description": "Paginated list of all sessions (active + closed).", "tags": [ "Sessions" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "active", "in": "query", "schema": { "type": "boolean" }, "description": "Filter active only" } ], "responses": { "200": { "description": "Session list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/sessions/{wallet}": { "get": { "summary": "Wallet Sessions", "description": "Sessions for a specific wallet address.", "tags": [ "Sessions" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string" }, "description": "0x wallet address" } ], "responses": { "200": { "description": "Wallet sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/sessions/analytics": { "get": { "summary": "Session Analytics", "description": "Per-wallet analytics with claimable stake tracking.", "tags": [ "Sessions" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Analytics data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mor/v1/wallet/{wallet}": { "get": { "summary": "Wallet Detail", "description": "Full wallet breakdown with ETH/MOR balances and session history.", "tags": [ "Sessions" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "wallet", "in": "path", "required": true, "schema": { "type": "string" }, "description": "0x wallet address" } ], "responses": { "200": { "description": "Wallet detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Morscan-Key", "description": "API key for authentication (format: mor_xxxxx)" } }, "responses": { "RateLimited": { "description": "Rate limited. Every key has a per-minute burst budget plus daily and monthly volume caps. A connected-wallet key (free, connect at /console) is 10 requests/min, 2,000/day, and 40,000/month; staked capacity scales at 3 requests/min per MOR staked on the MorScan builder subnet, and volume caps rise with stake - the daily cap is always 5% of the monthly cap (see /stake). Daily caps reset at 00:00 UTC and monthly caps on the 1st of the month (UTC). Volume caps are checked against a 60-second cache, so enforcement lands within a minute or two of the boundary. The Retry-After header says when to try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded" }, "reason": { "type": "string", "example": "Daily cap reached (2000/day). Resets at 00:00 UTC." }, "retry_after": { "type": "integer", "example": 42 }, "docs_url": { "type": "string", "example": "https://morscan.io/stake" } } } } } }, "ServerError": { "description": "Unexpected server error. Safe to retry with backoff; check /health for service status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal server error" } } } } } }, "Unauthorized": { "description": "Missing or invalid API key. Send X-Morscan-Key on every request. Connect your wallet at /console for a free key (10 req/min) - no email, no signup. Need more? Stake MOR on the MorScan builder subnet and capacity scales with your live stake (see /stake).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid API key" } } } } } } }, "schemas": { "SyncMetadata": { "type": "object", "properties": { "currentBlock": { "type": "integer", "description": "Latest block on chain" }, "syncedBlock": { "type": "integer", "description": "Last synced block" }, "blocksBehind": { "type": "integer", "description": "How many blocks behind" }, "lastSyncTs": { "type": "string", "format": "date-time" }, "timestamp": { "type": "string", "format": "date-time" } } }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded" ] }, "currentBlock": { "type": "integer" }, "syncedBlock": { "type": "integer" }, "blocksBehind": { "type": "integer" }, "providers": { "type": "integer" }, "bids": { "type": "integer" }, "sessions": { "type": "integer" }, "activeSessions": { "type": "integer" } } }, "TeaserResponse": { "type": "object", "properties": { "providers": { "type": "integer" }, "bids": { "type": "integer" }, "activeSessions": { "type": "integer" }, "totalSessions": { "type": "integer" }, "morStaked": { "type": "integer", "description": "Total MOR staked in active sessions" } } }, "Provider": { "type": "object", "properties": { "address": { "type": "string", "description": "0x provider address" }, "endpoint": { "type": "string", "description": "Provider RPC endpoint" }, "stake": { "type": "string", "description": "Provider stake in wei" }, "bidCount": { "type": "integer", "description": "Active bid count" }, "retractedBidCount": { "type": "integer", "description": "Retracted bid count" }, "bids": { "type": "array", "items": { "$ref": "#/components/schemas/Bid" } }, "retractedBids": { "type": "array", "items": { "$ref": "#/components/schemas/RetractedBid" } } } }, "Bid": { "type": "object", "properties": { "bidId": { "type": "string", "description": "bytes32 bid ID" }, "provider": { "type": "string" }, "modelId": { "type": "string", "description": "bytes32 model ID" }, "model": { "type": "string", "description": "Human-readable model name" }, "tags": { "type": "array", "items": { "type": "string" } }, "pricePerSecond": { "type": "string", "description": "Price in wei per second" }, "priceMorPerDay": { "type": "string", "description": "Price in MOR per day" }, "priceMorPerWeek": { "type": "string", "description": "Price in MOR per week" } } }, "RetractedBid": { "type": "object", "properties": { "bidId": { "type": "string" }, "model": { "type": "string" }, "priceMorPerDay": { "type": "string" }, "retractedAt": { "type": "integer", "description": "Unix timestamp when retracted" } } }, "Session": { "type": "object", "properties": { "sessionId": { "type": "string" }, "user": { "type": "string", "description": "User wallet address" }, "provider": { "type": "string" }, "bidId": { "type": "string" }, "modelId": { "type": "string" }, "model": { "type": "string" }, "stake": { "type": "string", "description": "Staked amount in wei" }, "stakeMor": { "type": "number", "description": "Staked amount in MOR" }, "isActive": { "type": "boolean" }, "openedAt": { "type": "integer" }, "closedAt": { "type": "integer", "nullable": true }, "endsAt": { "type": "integer" } } }, "MarketplaceResponse": { "allOf": [ { "$ref": "#/components/schemas/SyncMetadata" }, { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } } ] }, "ProvidersResponse": { "allOf": [ { "$ref": "#/components/schemas/SyncMetadata" }, { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } } ] }, "BidsResponse": { "allOf": [ { "$ref": "#/components/schemas/SyncMetadata" }, { "type": "object", "properties": { "bids": { "type": "array", "items": { "$ref": "#/components/schemas/Bid" } } } } ] }, "ModelsResponse": { "allOf": [ { "$ref": "#/components/schemas/SyncMetadata" }, { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "modelId": { "type": "string" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } } ] }, "SessionsResponse": { "allOf": [ { "$ref": "#/components/schemas/SyncMetadata" }, { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }, "total": { "type": "integer" } } } ] }, "AnalyticsResponse": { "allOf": [ { "$ref": "#/components/schemas/SyncMetadata" }, { "type": "object", "properties": { "wallets": { "type": "array", "items": { "type": "object", "properties": { "wallet": { "type": "string" }, "activeSessions": { "type": "integer" }, "totalSessions": { "type": "integer" }, "totalStakedMor": { "type": "number" } } } } } } ] }, "WalletDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/SyncMetadata" }, { "type": "object", "properties": { "wallet": { "type": "string" }, "ethBalance": { "type": "string" }, "morBalance": { "type": "string" }, "activeSessions": { "type": "integer" }, "totalSessions": { "type": "integer" }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } } } } ] } } } }