> For the complete documentation index, see [llms.txt](https://jester.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jester.gitbook.io/docs/tools/sceptre/api.md).

# API

## Place an Order

<mark style="color:green;">`POST`</mark> `https://sceptre.jester.trade/api/v1/trades`

Trigger trades via a strict JSON payload. Inputs are validated, assets/prices normalized for Hyperliquid, and errors are structured.

**Headers**

* Content-Type: application/json
* x-api-key: YOUR\_TOKEN
* Required for non‑TradingView senders.
* TradingView IPs (52.89.214.238, 34.212.75.30, 54.218.53.128, 52.32.178.7) MUST put the token in the JSON body as key. If both header and body are present, they must match.

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| x-api-key    | YOUR\_TOKEN        |

**Body**

* Canonical fields only (lowercase).
* TradingView IPs (52.89.214.238, 34.212.75.30, 54.218.53.128, 52.32.178.7) MUST put the token in the JSON body as key. If both header and body are present, they must match.
* Required: id, strategy, a, o, and auth (x-api-key header or key in body)
* Optional: id, tp, sl, o, d (if p + tp + sl are omitted)

| Name       | Type                                             | Description                                                                                                                     |       |            |   |                                                                                           |
| ---------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ----- | ---------- | - | ----------------------------------------------------------------------------------------- |
| `key`      | string                                           | Auth token in body (TradingView IPs only). Otherwise use header.                                                                |       |            |   |                                                                                           |
| `id`       | number\|string                                   | User identifier (e.g., Telegram ID).                                                                                            |       |            |   |                                                                                           |
| `strategy` | string                                           | Lowercase strategy name, e.g. "dpoCycleSwing".                                                                                  |       |            |   |                                                                                           |
| `a`        | string                                           | Asset symbol (flexible inputs like "BTCUSDT", "BTC-USD", "btc"). Normalized to Hyperliquid format internally (e.g., "BTC-USD"). |       |            |   |                                                                                           |
| `p`        | number\|string                                   | Entry price; if o="limit", this is the limit price.                                                                             |       |            |   |                                                                                           |
| `tp`       | number\|string (optional)                        | Take‑profit price (if provided, must be numeric and sensible relative to p).                                                    |       |            |   |                                                                                           |
| `sl`       | number\|string (optional)                        | Stop‑loss price (if provided, must be numeric and sensible relative to p).                                                      |       |            |   |                                                                                           |
| `o`        | "market" \| "limit" (optional; default "market") | Order type; defaults to Market is not present.                                                                                  |       |            |   |                                                                                           |
| d          | "long"/"1" \| "short"/"2" \| "close"/"0"         | <p></p><ul><li>Direction: either</li><li>provide d (long                                                                        | short | close or 1 | 2 | 0), or</li><li>omit d and then p/tp/sl must be present so we can infer buy/sell</li></ul> |

Notes:

* Prices may be strings or numbers; commas/underscores are stripped during parsing (e.g., "110,804.0" → 110804.0).
* Asset normalization: inputs like BTCUSDT, BTCUSD, BTC/USDT, BTC-USD, btc are accepted and normalized to HL "\<BASE>-USD". k‑prefixed assets handled (e.g., kPEPE).

**Header-auth example:**

```
{
  "id": 123456789,
  "strategy": "dpoCycleSwing",
  "a": "BTCUSDT",
  "p": "68250.12",
  "tp": "68990",
  "sl": "67680.5",
  "o": "market",
  "d": "long",
}
```

**TradingView body‑auth example (key first; allowed only from TradingView IPs):**

```
{
  "key": "YOUR_TOKEN",
  "id": 123456789,
  "strategy": "dpoCycleSwing",
  "a": "BTCUSDT",
  "p": "68250.12",
  "tp": "68990",
  "sl": "67680.5",
  "o": "limit",
  "d": "1",
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "success": true,
  "message": "Signal accepted",
  "signalId": "sig_01HF..."
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "success": false,
  "error": "ValidationError",
  "issues": [
    { "field": "strategy", "code": "RequiredMissing" },
    { "field": "p", "code": "NotNumeric", "message": "Must be a number" },
    { "field": "foo", "code": "UnknownField", "message": "Not allowed in v1" }
  ],
  "traceId": "req_01HF..."
}
```

{% endtab %}

{% tab title="401" %}

```json
{ "success": false, "error": "MissingAuth", "detail": "x-api-key required" }
```

{% endtab %}

{% tab title="403" %}

```json
{ "success": false, "error": "KeyMismatch" }
```

{% endtab %}

{% tab title="422 " %}

```json
{ 
"success": false, "error": "NormalizationFailed", "detail": "Unrecognized asset"
}
```

{% endtab %}
{% endtabs %}

Validation rules:

* Canonical keys only: key?, id?, strategy, a, p, tp?, sl?, o?
* If tp/sl provided, must be numeric and sensible relative to p (e.g., for BUY, sl < p and tp > p).
* If both header and body key are present, they must match. Body key is accepted only from TradingView IPs.