API Reference

Comprehensive documentation for the DotMarket REST API and WebSocket interfaces. Learn how to fetch historical data, user statistics, and real-time market updates.

The DotMarket API provides developers with programmatic access to the rich dataset generated by our 1-minute prediction markets. While you can always read data directly from the Arc Testnet smart contracts, utilizing our REST API and WebSocket feeds is significantly faster, more efficient, and provides access to complex aggregated statistics that are impossible to calculate on-chain.

Whether you are building a custom analytics dashboard, a trading bot, or a completely new frontend interface, this API reference provides everything you need to get started.

Base URL and Authentication

All REST API requests should be directed to the following base URL. We enforce strict HTTPS connections for all endpoints to ensure data integrity and security.

• Base URL: https://api-testnet.dotmarket.com/v1

Authentication

The vast majority of the DotMarket API endpoints are completely public. You do not need an API key to fetch market data, historical rounds, or global leaderboards. This open-access model encourages transparency and community-driven development.

However, certain advanced endpoints—such as those requiring heavy computational resources or high-frequency polling—may require authentication. For these endpoints, you must include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

REST API Endpoints

Below is a detailed breakdown of the core REST endpoints available in the v1 API. All responses are returned in standard JSON format.

1. Get Current Market Status

Retrieves the exact state of the currently active 1-minute rounds. This is the most frequently accessed endpoint, providing the real-time pool sizes and dynamic multipliers.

Endpoint: GET /market/current

Response Example:

{
  "success": true,
  "data": {
    "bettingRound": {
      "epoch": 10452,
      "startTime": 1718300400,
      "lockTime": 1718300460,
      "poolUp": "1450.5",
      "poolDown": "890.2",
      "multiplierUp": 1.61,
      "multiplierDown": 2.62
    },
    "liveRound": {
      "epoch": 10451,
      "lockPrice": 64250.50,
      "poolUp": "2100.0",
      "poolDown": "1950.0"
    }
  }
}

2. Get Historical Rounds

Fetches a paginated list of past prediction rounds. This is essential for rendering historical charts and analyzing market trends over time.

Endpoint: GET /market/history

Query Parameters:

• limit (optional): Number of records to return (Default: 50, Max: 200)
• offset (optional): Number of records to skip for pagination (Default: 0)
• epoch (optional): Filter by a specific round ID.

Response Example:

{
  "success": true,
  "data": [
    {
      "epoch": 10450,
      "lockPrice": 64200.00,
      "closePrice": 64210.25,
      "winningDirection": "UP",
      "totalVolume": "4500.5"
    },
    {
      "epoch": 10449,
      "lockPrice": 64180.75,
      "closePrice": 64150.00,
      "winningDirection": "DOWN",
      "totalVolume": "3800.0"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextOffset": 50
  }
}

3. Get User Statistics

Retrieves the comprehensive performance metrics for a specific wallet address, including their total PnL, win rate, and total volume traded.

Endpoint: GET /users/:address/stats

Response Example:

{
  "success": true,
  "data": {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "totalPredictions": 452,
    "winRate": 0.54,
    "totalVolume": "125000.0",
    "netPnL": "+4500.25",
    "unclaimedRewards": "350.0"
  }
}

Rate Limiting and Errors

To ensure the stability and reliability of the API for all developers, we enforce strict rate limits on all endpoints.

• Public Endpoints: 100 requests per minute per IP address.
• Authenticated Endpoints: 1000 requests per minute per API Key.

If you exceed these limits, the API will respond with an HTTP 429 status code.

Error Handling

When an error occurs, the API returns a structured JSON payload detailing the issue. You should parse this response in your application to provide meaningful feedback to your users.

Error Response Example:

{
  "success": false,
  "error": {
    "code": 404,
    "message": "User statistics not found. Address has never participated.",
    "type": "RESOURCE_NOT_FOUND"
  }
}

WebSocket Subscriptions

For applications that require absolute real-time data—which is critical when building interfaces for 1-minute prediction markets—you must utilize our WebSocket feeds.

• WebSocket URL: wss://api-testnet.dotmarket.com/ws

Connecting and Subscribing

Once connected, you can subscribe to specific channels by sending a JSON payload. The server will then push relevant events to your connection as they occur on the Arc Testnet.

Subscribe Payload:

{
  "action": "subscribe",
  "channel": "market_updates"
}

Real-Time Update Event Example:

{
  "event": "pool_updated",
  "data": {
    "epoch": 10452,
    "poolUp": "1455.5",
    "poolDown": "890.2",
    "multiplierUp": 1.60,
    "multiplierDown": 2.63
  }
}

By integrating with the WebSocket feed, your application can instantly reflect the actions of other users, ensuring your UI is always perfectly synchronized with the fast-paced DotMarket ecosystem.