Webhook API Documentation

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:

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

Get Open Trades

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

{
  "success": true,
  "trades": [
    {
      "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

• 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
• 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't provide more than 4 trade legs.

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

• Response (Success):

{
  "success": true,
  "id": "47462f2d-378c-4bf5-a016-1c1221aa0e62",
  "payload": [
    {
      "symbol": "SPY",
      "quantity": 1,
      "expiration": "YYYY-MM-DD",
      "type": "call or put",
      "strike": 1234
    },
    // Additional legs as needed
  ] 
}

• Response (Failure):

{
  "success": false,
  "id": "47462f2d-378c-4bf5-a016-1c1221aa0e62",
  "reason": "Error message",
  "message": "Detailed error information"
}

Exit A Trade

Close An Entire Trade

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

Close A Trade Based On Specific Rules

• Endpoint: POST https://app.optionsautotrader.com/webhook/{secret}/exit
• Request Body:
  • "close" field:
    • "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
  • "trade" field: this will only close the specific trade with the trade ID provided
  • "trim" field: this requires that you provide the "trade" field and the percentage that you want to trim (if you want to trim 50%, then set "trim": 50). This will round up when trimming.

{
  "bot": 1234567,
  "close": "all / newest / oldest",
  "trade": 1234567,
  "trim": 20
}

• Response (Success):

{
  "success": true,
  "id": "47462f2d-378c-4bf5-a016-1c1221aa0e62",
  "payload": {
    "bot": 1234567,
    "close": "",
    "trade": 1234567,
    "trim": 20,
  }
}

• Response (Failure):

{
  "success": false,
  "id": "47462f2d-378c-4bf5-a016-1c1221aa0e62",
  "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