Limit Orders

This tutorial explains how to use stockseyes API for setting limit order triggers. Limit orders allow you to automatically execute trades when certain price conditions are met.

Overview

Limit orders work by setting up triggers that monitor instrument prices. When the specified condition is met (e.g., price reaches a certain level), the system will send a webhook notification to your callback URL with the current price and your attached metadata.

Setting a Limit Order Trigger

To set a limit order trigger, you need to make a POST request to the /orders/setTrigger endpoint.

curl -X POST "https://api.stockseyes.com/orders/setTrigger" \
  -H "Content-Type: application/json" \
  -H "Authorization: your-api-key" \
  -d '{
    "postCallback": "https://example.com/callback",
    "operator": "GREATER",
    "value": 1406,    
    "instrumentToken": 738561,    
    "expiresAt": 1736406718628,
    "metadata": {
      "orderId": "12345",
      "userId": "user123"
    }
  }'

Request Parameters

Parameter	Type	Required	Description	Example
postCallback	string	Yes	Callback URL to be called when trigger is activated	"https://example.com/callback"
operator	string	Yes	Comparison operator for the trigger	"GREATER"
value	number	Yes	The value to compare against	1406
instrumentToken	integer	Yes	Token identifier for the instrument	738561
expiresAt	integer	Yes	Expiry timestamp in epoch milliseconds	1736406718628
metadata	object	Yes	Additional metadata for the trigger	{"orderId": "12345", "userId": "user123"}

Available Operators

Operator	Description
EQUALS	Trigger when price equals the specified value
GREATER	Trigger when price is greater than the specified value
LESSER	Trigger when price is less than the specified value
GREATER_THAN_OR_EQUALS_TO	Trigger when price is greater than or equal to the specified value
LESSER_THAN_OR_EQUALS_TO	Trigger when price is less than or equal to the specified value

Expected Response

Success Response (200)

{
  "status": "added",
  "id": "VsenunqcFZTAHwTFm6ov"
}

Error Responses

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid API key
• 500 Internal Server Error: Server error

Webhook Callback

When the trigger condition is met, the system will send a POST request to your postCallback URL with the following payload:

Request Body

The webhook will include all your original metadata plus the current price:

{
  "orderId": "12345",
  "userId": "user123",
  "currentPrice": 897494
}

Example Webhook Payload

If you sent metadata as:

{
  "foo": "bar",
  "foo1": "bar1", 
  "userId": "someuserID",
  "orderId": "908409"
}

You will receive:

{
  "foo": "bar",
  "foo1": "bar1",
  "userId": "someuserID", 
  "orderId": "908409",
  "currentPrice": 897494
}

Getting Trigger Details by ID

You can retrieve the details of a specific trigger using its ID. This is useful for checking the status of your triggers or getting additional information.

curl --location 'https://api.stockseyes.com/orders/trigger/VsenunqcFZTAHwTFm6ov' \
--header 'Content-Type: application/json' \
--header 'Authorization: your-api-key'

Expected Response

{
    "createdAt": 1754197419171,
    "executed": true,
    "executedAt": 1736406829739,
    "expiresAt": 1736406718628,
    "id": "VsenunqcFZTAHwTFm6ov",
    "instrumentToken": 738561,
    "metadata": {
        "orderId": "12345",
        "userId": "user123"
    },
    "operator": "GREATER",
    "postCallback": "https://example.com/callback",
    "value": 1406.0
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the trigger
createdAt	integer	Creation timestamp in epoch milliseconds
executed	boolean	Whether the trigger has been executed
executedAt	integer	Execution timestamp in epoch milliseconds (null if not executed)
expiresAt	integer	Expiry timestamp in epoch milliseconds
instrumentToken	integer	Token identifier for the instrument
metadata	object	Additional metadata for the trigger
operator	string	Comparison operator for the trigger
postCallback	string	Callback URL to be called when trigger is activated
value	number	The value to compare against

Error Responses

• 404 Not Found: Trigger with the specified ID not found
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid API key
• 500 Internal Server Error: Server error

Use Cases

1. Buy When Price Drops

Set a trigger to buy when the price falls below a certain level:

{
  "postCallback": "https://your-app.com/webhooks/buy-trigger",
  "operator": "LESSER",
  "value": 1200,
  "instrumentToken": 738561,
  "expiresAt": 1736406718628,
  "metadata": {
    "action": "BUY",
    "quantity": 10,
    "userId": "user123"
  }
}

2. Sell When Price Rises

Set a trigger to sell when the price rises above a certain level:

{
  "postCallback": "https://your-app.com/webhooks/sell-trigger", 
  "operator": "GREATER",
  "value": 1500,
  "instrumentToken": 738561,
  "expiresAt": 1736406718628,
  "metadata": {
    "action": "SELL",
    "quantity": 5,
    "userId": "user123"
  }
}

3. Stop Loss

Set a stop loss trigger to limit losses:

{
  "postCallback": "https://your-app.com/webhooks/stop-loss",
  "operator": "LESSER_THAN_OR_EQUALS_TO",
  "value": 1100,
  "instrumentToken": 738561,
  "expiresAt": 1736406718628,
  "metadata": {
    "action": "STOP_LOSS",
    "quantity": 10,
    "userId": "user123",
    "orderType": "STOP_LOSS"
  }
}

Best Practices

1. Set Appropriate Expiry: Always set an expiresAt timestamp to prevent triggers from running indefinitely
2. Use Meaningful Metadata: Include relevant information in metadata to help identify the trigger context
3. Handle Webhook Failures: Implement retry logic in your webhook endpoint
4. Validate Webhook Data: Always validate the webhook payload before processing
5. Monitor Trigger Status: Keep track of your active triggers and their status

Finding Instrument Tokens

To find the instrumentToken for a specific instrument, use the Search Instruments API or Get All Instruments API.