Skip to main content

​
Base URL

All API endpoints use the following base URL: 
https://proteus-production-6213.up.railway.app
API endpoints are prefixed with /api/chain/

​
Architecture

The Proteus REST API is built on a blockchain-first architecture:
  • All data is fetched directly from BASE blockchain contracts
  • No database dependencies for read operations
  • Real-time on-chain data through Web3 integration
  • Responses include "source": "blockchain" to indicate data origin

​
Response Format

​
Success Response

{
  "success": true,
  "data": {},
  "message": "Optional success message"
}

​
Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {}
  }
}

​
Error Codes

CodeHTTP StatusDescription
VALIDATION_ERROR400Invalid input data or missing required fields
INVALID_REQUEST400Malformed request
UNAUTHORIZED401Invalid or missing authentication
INVALID_TOKEN401JWT token is invalid
TOKEN_EXPIRED401JWT token or OTP has expired
INVALID_SIGNATURE401Wallet signature verification failed
FORBIDDEN403Permission denied
NOT_FOUND404Resource not found
RATE_LIMITED429Too many requests
INTERNAL_ERROR500Unexpected server error
BLOCKCHAIN_ERROR500RPC or chain interaction failed
CONTRACT_ERROR500Smart contract call failed
SERVICE_UNAVAILABLE503Service temporarily unavailable

​
Market-Specific Errors

CodeDescription
MARKET_NOT_FOUNDMarket does not exist
MARKET_ENDEDMarket has already ended
MARKET_NOT_ENDEDMarket has not ended yet
MARKET_RESOLVEDMarket is already resolved
INSUFFICIENT_FUNDSNot enough ETH for operation

​
Rate Limits

User TypeLimit
Default100 req/min
Genesis Holder500 req/min

​
Caching

Responses are cached in Redis to improve performance:
Data TypeTTL
Actors5 minutes
Markets30 seconds
Stats10 seconds
Genesis NFT1 minute

​
Contract Addresses

​
BASE Sepolia (Testnet)

ContractAddressStatus
PredictionMarketV20x5174Da96BCA87c78591038DEe9DB1811288c9286Recommended
GenesisNFT0x1A5D4475881B93e876251303757E60E524286A24Active
ActorRegistry0xC71CC19C5573C5E1E144829800cD0005D0eDB723Active
DecentralizedOracle0x7EF22e27D44E3f4Cc2f133BB4ab2065D180be3C1Active
PayoutManager0x88d399C949Ff2f1aaa8eA5a859Ae4d97c74f6871Active

​
BASE Mainnet

Not yet deployed.

​
Health Check

curl https://api.proteus.com/api/health

​
Response

{
  "status": "healthy",
  "timestamp": "2026-03-06T12:00:00Z",
  "service": "proteus-node"
}

​
Next Steps

Authentication

Set up wallet-based JWT authentication

Markets

Query prediction markets from the blockchain

Predictions

Submit and track predictions

Actors

Get registered actor data

Build docs developers (and LLMs) love

Get started for freeTalk to us