API Reference
API Reference
Complete REST API documentation for OracleMart
API Reference
OracleMart provides a comprehensive REST API for accessing market data, user statistics, and platform analytics.
Base URL
Development: http://localhost:3000/api
Production: https://oraclemart.io/apiAuthentication
Most endpoints are public and don't require authentication. Rate limiting applies:
- Public endpoints: 100 requests/minute
- Authenticated endpoints: 1000 requests/minute
Response Format
All API responses follow this structure:
Success Response
{
"success": true,
"data": { /* endpoint-specific data */ },
"timestamp": "2025-10-29T11:00:00Z"
}Error Response
{
"success": false,
"error": "Error message",
"code": "ERROR_CODE",
"timestamp": "2025-10-29T11:00:00Z"
}Available Endpoints
Markets
Core market data and operations
- GET
/api/markets- List all markets - GET
/api/markets/:id- Get market details - GET
/api/markets/trending- Get trending markets - GET
/api/markets/featured- Get featured markets
Bets
Betting history and user positions
- GET
/api/bets- List bets with filters - GET
/api/bets/user/:address- Get user's bets - GET
/api/bets/market/:id- Get market's bets
Users
User statistics and profiles
- GET
/api/users/:address- Get user stats - GET
/api/users/:address/positions- Get user positions - GET
/api/users/:address/history- Get bet history
Analytics
Platform-wide analytics and leaderboards
- GET
/api/analytics/trending- Trending markets - GET
/api/analytics/leaderboard- Top traders - GET
/api/analytics/stats- Platform statistics - GET
/api/analytics/volume- Trading volume data
Common Query Parameters
Many endpoints support these common parameters:
| Parameter | Type | Description | Default |
|---|---|---|---|
limit | number | Results per page | 50 |
offset | number | Pagination offset | 0 |
sortBy | string | Sort field | varies |
order | string | asc or desc | desc |
Data Types
Market Object
interface Market {
id: string;
question: string;
description: string;
creator: string;
category: string;
state: 'Active' | 'Ended' | 'Resolved' | 'Invalid';
yes_pool: string; // Wei format
no_pool: string; // Wei format
volume: string; // Wei format
odds: {
yes: number; // Percentage
no: number; // Percentage
};
roi: {
yes: number; // Percentage return
no: number; // Percentage return
};
totalPool: string;
bet_count: number;
participant_count: number;
timeRemaining: number; // Milliseconds
created_at: string; // ISO 8601
end_time: string; // ISO 8601
winning_outcome?: boolean;
}Bet Object
interface Bet {
id: string;
market_id: string;
user_address: string;
outcome: boolean; // true = YES, false = NO
amount: string; // Wei format
odds: number; // At time of bet
potential_return: string; // Wei format
timestamp: string; // ISO 8601
claimed: boolean;
market_question: string;
market_state: string;
}User Stats Object
interface UserStats {
address: string;
total_bets: number;
total_wagered: string; // Wei format
total_winnings: string; // Wei format
win_rate: number; // Percentage
profit_loss: string; // Wei format
roi: number; // Percentage
rank: number;
active_positions: number;
markets_created: number;
}Error Codes
| Code | Description |
|---|---|
MARKET_NOT_FOUND | Market ID does not exist |
USER_NOT_FOUND | User address not found |
INVALID_PARAMETERS | Invalid query parameters |
RATE_LIMIT_EXCEEDED | Too many requests |
INTERNAL_ERROR | Server error |
Rate Limiting
Rate limits are enforced per IP address:
- Tier 1 (Public): 100 requests/minute
- Tier 2 (Authenticated): 1000 requests/minute
When rate limited, you'll receive:
{
"success": false,
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"retry_after": 30
}Pagination
For endpoints that return lists:
Request
GET /api/markets?limit=20&offset=40Response
{
"success": true,
"data": [...],
"pagination": {
"total": 125,
"limit": 20,
"offset": 40,
"has_more": true
}
}Examples
Get Active Markets
curl https://oraclemart.io/api/markets?state=Active&limit=10Get User Statistics
curl https://oraclemart.io/api/users/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbGet Trending Markets
curl https://oraclemart.io/api/analytics/trending?limit=5SDK Support
JavaScript/TypeScript
import { OracleMartClient } from '@oraclemart/sdk';
const client = new OracleMartClient({
apiUrl: 'https://oraclemart.io/api'
});
// Get markets
const markets = await client.markets.list({
state: 'Active',
limit: 10
});
// Get user stats
const stats = await client.users.getStats('0x...');Python
from oraclemart import OracleMartClient
client = OracleMartClient(
api_url='https://oraclemart.io/api'
)
# Get markets
markets = client.markets.list(state='Active', limit=10)
# Get user stats
stats = client.users.get_stats('0x...')WebSocket API
Real-time updates via WebSocket:
const ws = new WebSocket('wss://oraclemart.vercel.app/ws');
// Subscribe to market updates
ws.send(JSON.stringify({
action: 'subscribe',
channel: 'markets',
market_id: '1'
}));
// Receive updates
ws.onmessage = (event) => {
const update = JSON.parse(event.data);
console.log('Market update:', update);
};