> For the complete documentation index, see [llms.txt](https://docs.sigrex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sigrex.io/getting-started/signal-payload-format.md).

# Signal Payload Format

The **signal payload** is the core JSON structure that Sigrex uses to trigger trading actions through webhooks or webhook email addresses. When a signal is sent, it must match this format so the system can understand and execute it properly.

Below is the expected payload schema:

```ts
{
  id?: string,                  // A custom name/id for the alert (optional)
  key?: string,                 // Authorization key (required if webhook is key-protected)
  symbol: string,               // The trading pair (e.g., 'BTCUSDT', 'ETHUSDT')
  side: "BUY" | "SELL",         // Either 'BUY | buy' or 'SELL | sell'
  size?: number,                // Trade size (open in quote, close in base currency), overrides default (optional)
  forceSize? boolean,           // It can bypass the amount of those bots that have strict amount settings
  dilution?: boolean,           // If true, allows partial stacking of positions (optional)
  flag?: FlagType | FlagType[], // Additional tags like 'TEST', 'DEBUG', 'REVERSE' (optional)
  debug?: any,                  // Extra debugging info (optional)
  callback? string              // URL to receive the executed order result and execution details (optional)
}
```

***

## 🔍 Field Descriptions

* **id (optional):**\
  A custom label for the signal. Useful for identifying or grouping alerts in your dashboard.
* **key (optional, required in safe mode):**\
  The security key required for webhooks that are key-protected. Must match the one set during webhook creation.
* **symbol (required):**\
  The trading pair this signal targets. For example, `BTCUSDT`, `ETHUSD`, etc.
* **side (required):**\
  The trade direction. Must be either:
  * `'BUY | buy'` – to open long or close a short position
  * `'SELL | sell'` – to close long or open a short position
* **size (optional):**\
  The trade amount (open in quote, close in base currency). If not set, the default configured size for the connected bot will be used.
* **dilution (optional):**\
  If set to `true`, the bot will stack this trade on top of an existing position if it's in the same direction, instead of replacing it.
* **flag (optional):**\
  Tags that describe the signal’s purpose or behavior, such as:
  * `'TEST'` – test only, no real trade
  * `'DEBUG'` – for debugging
  * `'REVERSE'` – interpret as reverse trade\
    You can use a single flag or multiple in an array.
* **debug (optional):**\
  Any custom or diagnostic information. This data isn’t used by bots, but helps in testing or logging.
* **callback (optional):** The URL that receives the executed order result and additional execution details once processing is complete.

***

## ✅ Example Payloads

Simple

```json
{
  "key": "secret123",
  "symbol": "BTCUSDT",
  "side": "BUY",
}
```

More complex

```json
{
  "id": "Super Strategy",
  "key": "secret123",
  "symbol": "BTCUSDT",
  "side": "BUY",
  "size": 100,
  "dilution": true,
  "flag": ["TEST"],
  "callback": "https://your-app.com/webhooks/order-result"
}
```

## 📞 Example Callback Payload

```json
{
  // The original signal payload that was received
  "signal": {
    "symbol": "BTCUSDC",
    "key": "1ef5169216fgh0ffg3c4362d529b0d599b36",
    "side": "BUY",
    "callback": "https://webhook.site/51d70cee-ab97-4b3d-9146-0b2e87a30c9b"
  },

  // Information about the executor, including the bot and API used
  "executor": {
    "type": "cex-signal-bot",
    "api": {
      "id": 86,
      "exchange": "hyperliquid",
      "service": "futures"
    },
    "bot": {
      "id": 193
    }
  },

  // The actual order result returned by the exchange
  "result": {
    "status": "ok",
    "response": {
      "type": "order",
      "data": {
        "statuses": [
          {
            "filled": {
              "totalSz": "0.00025",
              "avgPx": "79550.0",
              "oid": 538410463312
            }
          }
        ]
      }
    }
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sigrex.io/getting-started/signal-payload-format.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.