EQULS API - Execute Trades Endpoint

Overview

This endpoint allows users to execute single trades or parlays by submitting trade details. It validates the request, finds the corresponding games, and creates trade records in the database.

Details

URL: /v1/execute
Method: POST
Authentication: Required (API Key as query parameter)

Request Parameters

Query Parameters:
- apiKey: Required. Must be a valid 24-character hexadecimal API key for authentication.
Request Body:
- trades: An array of trade objects, each containing:
  - home_team: The home team name (case-insensitive, will be capitalized)
  - away_team: The away team name (case-insensitive, will be capitalized)
  - sport: One of the valid sports supported by the API (case-insensitive)
  - league: One of the valid leagues supported by the API (case-insensitive, will be converted to uppercase)
  - bet_type: The type of bet (must be one of the valid bet types)
  - selection: Optional. The selected team or outcome (case-insensitive, will be capitalized)
  - book: The sportsbook to place the bet with (must be one of the valid books)
  - rules: An object containing either an AND or OR array of rule strings in the format "type:operator:value"
    - type: Either "point" or "price"
    - operator: One of "greater_than", "less_than", or "equals"
    - value: A numeric value (price must be > 1)
  - units: The number of units to wager (positive number, maximum 5)
  - executeAsLive: Optional boolean flag to indicate if the trade should be executed as a live bet (defaults to false)
  - start_date: The start date of the game in UTC format
- executeAs: Either "single" or "parlay" to indicate how the trades should be executed

Response

Success (201 Created):Returns a JSON object containing the created trades. Example:

{
  "message": "Trades created successfully",
  "executeAs": "single",
  "trades": [
    {
      "tradeId": "60a1e2c3d4e5f6a7b8c9d0e1",
      "book": "DraftKings",
      "game": {
        "home_team": "Los Angeles Lakers",
        "away_team": "Boston Celtics",
        "sport": "basketball",
        "league": "NBA",
        "start_date": "2023-12-25T20:00:00Z"
      },
      "executeAsLive": false
    }
  ]
}

Error (400 Bad Request):Returned when the request body is invalid. Example:

{
  "error": "Invalid request body",
  "details": [
    {
      "code": "invalid_enum_value",
      "message": "Invalid enum value. Expected 'NFL' | 'NBA' | ...",
      "path": ["trades", 0, "league"]
    }
  ],
  "validValues": {
    "sports": ["football", "basketball", "baseball", ...],
    "leagues": ["NFL", "NBA", "MLB", ...],
    "betTypes": ["moneyline", "spread", "total", ...],
    "books": ["DraftKings", "FanDuel", "Caesars", ...],
    "ruleOperators": ["greater_than", "less_than", "equals"],
    "ruleTypes": ["point", "price"]
  }
}

Error (404 Not Found):Returned when a game matching the provided details cannot be found. Example:

{
  "error": "Game not found",
  "message": "Could not find matching game with teams: Los Angeles Lakers vs Boston Celtics, sport: basketball, league: NBA, start date: 2023-12-25T20:00:00Z"
}

Error (500 Internal Server Error):Returned when an unexpected error occurs during processing. Example:

{
  "error": "Internal server error",
  "message": "An unexpected error occurred while processing the trades"
}

Parlay Validation Rules

When executeAs is set to "parlay", the following additional validations are applied:

Must have at least 2 trades
All trades must use the same sportsbook
All trades must have the same units value
All trades must have unique selections
All trades must be from different games, except for Same Game Parlays (SGPs)

Notes

Team names are automatically capitalized for consistency
Sport names are converted to lowercase
League names are converted to uppercase
For FanDuel, the book is stored internally as "Blue Book"
When executing a parlay, all trades are linked with a common bundleId
The API key must be a valid 24-character hexadecimal string in the MongoDB ObjectID format
Rules must follow the specific format and validation requirements
The maximum allowed units per trade is 5
The start_date must be a valid date string in UTC format
The executeAsLive flag allows trades to be marked for live betting execution