Events API

Create and retrieve trading events

Overview

The Events API allows you to create new trading events and retrieve event information. Trading events represent binary opinion markets where users can trade YES or NO positions.

Create Event

Endpoint: POST /events/create

Creates a new trading event in the platform.

Request Body

title · string · required

The title of the trading event. Must be unique.

Example: “Will Bitcoin reach $100k by 2026?”

description · string · required

Detailed description of the event and trading conditions.

Example: “This event will resolve to YES if Bitcoin reaches $100,000 USD by December 31, 2026.”

start_date · string · required

ISO 8601 formatted date-time when trading begins.

Format: YYYY-MM-DDTHH:mm:ss.sssZ

Example: “2026-01-01T00:00:00.000Z”

end_date · string · required

ISO 8601 formatted date-time when trading ends and the event expires.

Format: YYYY-MM-DDTHH:mm:ss.sssZ

Example: “2026-12-31T23:59:59.999Z”

min_bet · number · required

Minimum bet amount in INR.

Example: 10

max_bet · number · required

Maximum bet amount in INR.

Example: 1000

sot · string · required

Source or type of the event (e.g., “crypto”, “sports”, “politics”).

Example: “crypto”

quantity · number · required

Total quantity of contracts available for trading.

Example: 10000

Response

status · boolean · required

Always true for successful creation

code · number · required

HTTP status code: 201

message · string · required

Success message: “Event created successfully”

additional · string · required

Generated event code (event ID)

Example Request

cURL

curl -X POST https://api.opinix.trade/events/create \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Will Bitcoin reach $100k by 2026?",
    "description": "This event will resolve to YES if Bitcoin reaches $100,000 USD by December 31, 2026.",
    "start_date": "2026-01-01T00:00:00.000Z",
    "end_date": "2026-12-31T23:59:59.999Z",
    "min_bet": 10,
    "max_bet": 1000,
    "sot": "crypto",
    "quantity": 10000
  }'

Example Response

201 - Success

{
  "status": true,
  "code": 201,
  "message": "Event created successfully",
  "additional": "3169798"
}

409 - Event Already Exists

{
  "status": false,
  "code": 409,
  "name": "Resource conflict",
  "message": "Event already exists"
}

422 - Validation Error

{
  "status": false,
  "code": 422,
  "name": "Unprocessable entity",
  "message": "min_bet: Expected number, received string"
}

---

Get Trade Summary

Endpoint: GET /events/tradeSummary

Retrieves trade summary and WebSocket subscription details for an event.

Query Parameters

eventId · string · required

The unique event ID (event code) to retrieve trade summary for.

Example: “3169798”

Response

status · boolean · required

Always true for successful requests

code · number · required

HTTP status code: 200

message · string · required

Success message: “Trade summary fetched successfully”

additional · object · required

Trade summary data containing orderbook configuration

additional.order_book_details · object · required

Order book details for the event

additional.order_book_details.orderbook_config · object · required

Configuration for orderbook WebSocket subscription

additional.order_book_details.orderbook_config.socket_events · object · required

WebSocket event configuration

additional.order_book_details.orderbook_config.socket_events.subscribe_msg_name · string · required

Message name to subscribe: "subscribe_orderbook"

additional.order_book_details.orderbook_config.socket_events.unsubscribe_msg_name · string · required

Message name to unsubscribe: "unsubscribe_orderbook"

additional.order_book_details.orderbook_config.socket_events.listener_msg_name · string · required

Channel name to listen for updates: "event_orderbook_{eventId}"

additional.order_book_details.orderbook_config.socket_events.subscription_data · string · required

Event ID for subscription

Example Request

cURL

curl -X GET "https://api.opinix.trade/events/tradeSummary?eventId=3169798" \
  -H "Accept: application/json"

Example Response

200 - Success

{
  "status": true,
  "code": 200,
  "message": "Trade summary fetched successfully",
  "additional": {
    "order_book_details": {
      "orderbook_config": {
        "socket_events": {
          "subscribe_msg_name": "subscribe_orderbook",
          "unsubscribe_msg_name": "unsubscribe_orderbook",
          "listener_msg_name": "event_orderbook_3169798",
          "subscription_data": "3169798"
        }
      }
    }
  }
}

404 - Event Not Found

{
  "status": false,
  "code": 404,
  "name": "Resource not found",
  "message": "Event not found"
}

---

Event Types

Based on the source code at packages/types/src/index.ts:29-42, here are the event type definitions:

export type TEvent = {
  id: string;
  title: string;
  slug: string;              // Auto-generated from title
  description: string;
  start_date: Date;
  end_date: Date;
  createdAt: Date;           // Auto-generated
  min_bet: number;
  max_bet: number;
  sot: string;               // Source or type
  traders: number;           // Number of active traders
  quantity: number;          // Total contracts available
};

Implementation Notes

Source Code Reference:

• Event routes: apps/server/src/router/eventRouter.ts
• Event handlers: apps/server/src/controllers/event/index.ts
• Type definitions: packages/types/src/index.ts:29-42

Event Slug Generation

The API automatically generates a URL-friendly slug from the event title. For example:

• Title: “Will Bitcoin reach $100k by 2026?”
• Generated slug: “will-bitcoin-reach-100k-by-2026”

Event Code

Each event is assigned a unique numeric event code upon creation. This code is used to identify the event in subsequent API calls and WebSocket subscriptions.

Duplicate Event Prevention

The API checks for existing events with the same slug before creating a new event. If an event with the same slug exists, the API returns a 409 Conflict error.