Webhook API Documentation

This webhook API is now live and available to use, as of Dec. 7th, 2024. If you have any questions on how to use this API or get stuck, please reach out to me directly by emailing me at hello@optionsautotrader.com

The Options Auto Trader Webhook API allows users to automate and customize their trading actions. Below are the endpoints, request bodies, and response formats for managing trades, including entries, exits, and status updates. This will help options traders who want to automate using Third Party tools like TradingView or their own custom code projects.

Getting Started

Options Auto Trader Webhook API Explained

In the Options Auto Trader platform, all trade entries must be tied to an auto trader bot to ensure proper management. This setup guarantees that trades can be monitored and managed as needed within the platform. Even if you prefer your trades to remain unmanaged—meaning they won’t be closed automatically by the system—they must still be associated with a bot. To accommodate this, you can create a generic bot that simply holds these trades without any management rules set. This webhook api is built to facilitate both integrations with third parties and custom coding projects.

Authentication

Each webhook endpoint requires a {secret} in the url to authenticate requests, which ensures secure access to user-specific trading bots and actions.

Keep your {secret} token confidential and avoid sharing it or exposing it in public code repositories. This webhook secret can be changed in your user profile in the event it gets compromised. It is also recommended to update your secret every 90 days for enhanced security.

The {secret} will always be 36 characters (8 char. - 4 char. - 4 char. - 4 char. - 12 char.)

Get Bot Information

• Endpoint: GET https://app.optionsautotrader.com/webhook/{secret}/bots

• Description: Retrieve the id of all bots associated with an Options Auto Trader account.

• Response:

  • id - numeric UUID

  • broker - string

    • options: TastyTrade, Tradier, TradeStation, CharlesSchwab, Paper

  • name - string

  • strategy - string

    • options: custom, 1-1-2, iron condor, credit spread, etc

  {   
     "success": true,   
     "user": "email",   
     "data": [     
        {       
          "id": 1234567,       
          "broker": "CharlesSchwab",       
          "name": "BEST BOT EVER",       
          "strategy": "CREDIT SPREAD",     
        }   
      ] 
  }

  ---

  Get Open Trades

  • Endpoint: GET https://app.optionsautotrader.com/webhook/{secret}/trades

  • Response:

    • bot_id - numeric UUID (corresponds with GET bot information id)

    • trade_id - numeric UUID

  {
    "success": true,
    "trades": [
      {
        "bot_id": 12345,
        "trade_id": 1234567,
        "symbol": "SPX",
        "strategy": "IRON CONDOR",
        "entered_at": "2024-10-25 10:20:01"
        "entry_price": 12.50,
        "profit_loss": 20.20,
        "percentage_profit_loss": 20,
      }
    ]
  }
  

  ---

  Enter A Trade

  Enter Trade Based On Bot Settings (Simple Webhook)

  • Endpoint: POST https://app.optionsautotrader.com/webhook/{secret}/enter/{bot_id}

  Enter Trade Based On Custom Trade Legs

  • Endpoint: POST https://app.optionsautotrader.com/webhook/{secret}/enter/{bot_id}

  • Request Body:

    • "symbol" field: a string of the asset you are trading

    • "quantity" field: an integer that defines the quantity of the trade. A positive number means you will buy to open the contract and a negative number means you will sell to open the contract.

    • "expiration" field: provided in the format YYYY-MM-DD, we will locate the expiration date that is closest to this date if we can't find the exact match.

    • "type" field: provide call or put

    • "strike" field: an integer that defines the strike price you want to enter. If we can't locate the exact strike price, then we will find the closest strike.

    • You can provide up to 4 trade legs.

  {
    "legs": [
      {
        "symbol": "SPY",
        "quantity": 1,
        "expiration": "YYYY-MM-DD",
        "type": "call or put",
        "strike": 1234
      }
      // Additional legs as needed
    ]
  }
  

  • Response (Success):

  {
    "success": true,
    "message": "Trade successfully queued",
    "payload": {
        "bot_id": "6584406",
        "bot_name": "SPX 0 DTE Iron Condor",
        "legs": [
            {
                "symbol": "SPY",
                "quantity": 1,
                "expiration": "2024-12-30",
                "type": "call",
                "strike": 356
            }
        ],
        "executed_at": "2024-12-04 15:37:53"
      }
  }
  

  • Response (Failure):

  {
    "success": false,
    "reason": "Error message",
    "message": "Detailed error information"
  }
  

  ---

  Exit A Trade

  Close A Trade Based On Specific Rules

  • Endpoint: POST https://app.optionsautotrader.com/webhook/{secret}/exit/{bot_id}

  • Request Body:

    • “trade_id” field (optional): this will close a specific trade

    • "close" field (optional):

      • "all" - this will close all the trades being tracked by the bot with ID

      • "newest" - this will close the newest trade being tracked by the bot with ID

      • "oldest" - this will close the oldest trade being tracked by the bot with ID

      • If none provided, we will default to closing “all” trades

  {
    "trade_id": 12345,
    "close": "all / newest / oldest",
  }
  

  • Response (Success):

  [
      "success": true,
      "message": "Trade close request processed",
      "payload": {
          "bot_id": "9990849",
          "bot_name": "SPX 0 DTE Iron Condor",
          "close_type": "all",
          "closed_trades": [
              70939,
              70941,
              70944,
              70951
          ],
          "executed_at": "2024-12-04 15:55:08"
      }
  ]
  

  • Response (Failure):

  {
    "success": false,
    "reason": "Error message",
    "message": "Detailed error information"
  }
  

  ---

  Rate Limits

  To ensure the reliability and performance of the Options Auto Trader platform, please be mindful of the following rate limits and performance guidelines when using the Webhook API:

  • Request Limit: Each user is allowed up to 60 API requests per minute. Exceeding this limit will result in a temporary block on further requests from your account for a short period.

  • Cooldown Period: After reaching the rate limit, requests from the same account will be blocked for 5 minutes. After this period, API access will be restored automatically.

  ---

  Order Retrying

  Failed or rejected orders will never be retried. If communication with a broker fails for any reason, we will never retry a failed operation. We will do our best to detect when something fails or something unexpected happens and notify you via email. However, there are scenarios where an order could be accepted by a broker and then rejected later and in those scenarios, you may not receive a trade failed email notification. You can always check the status (webhook received, order created, trade routed to the broker, trade filled, etc) of any trade via the Trade Transparency Page.

  ---

  Webhook Execution Delays

  Webhooks triggered from third parties like TradingView and TrendSpider can be delayed for an undetermined amount of time or may not be sent at all. You are responsible for monitoring your automated trading strategy and taking manual action when necessary.

  ---

  Common Errors and Troubleshooting

  When using the Options Auto Trader Webhook API, you may encounter errors. Below are some common issues and troubleshooting tips to help resolve them:

  Authentication Errors

  • Error: 401 Unauthorized

  • Cause: The {secret} token in the URL is missing, incorrect, or has been compromised.

  • Solution: Ensure the {secret} token matches the one in your account profile. If compromised, reset it in your profile and update your integrations.

  Rate Limit Exceeded

  • Error: 429 Too Many Requests

  • Cause: Exceeded the rate limit of 60 requests per minute.

  • Solution: Wait 5 minutes for the cooldown period before resuming requests. Consider batching requests or implementing a back-off strategy for automated retries.

  Invalid Parameters

  • Error: 400 Bad Request

  • Cause: Missing or incorrect parameters in the request body.

  • Solution: Verify that all required fields are included and correctly formatted. For example, ensure dates are in YYYY-MM-DD format, and symbols are accurate.

  Bot Not Found

  • Error: 404 Not Found

  • Cause: The specified bot ID does not exist or is not associated with your account.

  • Solution: Use the GET /bots endpoint to retrieve the correct bot IDs and confirm they are properly set up in your account.

  Trade Entry/Exit Errors

  • Error: 400 Bad Request or Custom Error Messages

  • Cause: Issues in trade parameters such as unsupported symbols, invalid expiration dates, or incorrect trade legs.

  • Solution: Verify that all trade parameters align with valid asset symbols, expiration dates, and trade types (e.g., "call" or "put"). Refer to the Enter A Trade and Exit A Trade sections for required formats.

  Internal Server Error

  • Error: 500 Internal Server Error

  • Cause: This is often a temporary issue on the server.

  • Solution: Wait a few moments and retry the request. If the error persists, contact support for assistance.

  Payload Error Messages

  • Error: success: false , with reason and message fields in the response.

  • Cause: These fields provide specific error messages to help diagnose issues.

  • Solution: Review the reason and message values to understand the error. Common messages might include “Invalid asset” or “Bot not enabled for trade entries.”

  If issues persist, please contact our support team with details, including the error messages and the steps taken, for further assistance. Contact support at hello@optionsautotrader.com

TERMS OF SERVICE: Please be aware that continued use of the Options Auto Trader is subject to our Terms Of Service. If you have any questions or wish to review these terms, feel free to visit the website.