> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojifunded.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order endpoints

> Place, cancel, and close orders across all order types and execution venues.

Order endpoints require the `TRADE` or `MANAGE_ORDERS` permission scope depending on the operation. See [Authentication](/api-reference/authentication) for scope details.

```
BASE = https://engine.dojifunded.com/v1
```

***

## Place an order

```bash theme={null}
POST /v1/order
```

**Required permission:** `TRADE`

Single endpoint for all order types — market, limit, stop, take-profit — across all venues.

```bash theme={null}
curl -X POST "$BASE/order" \
  -H "X-API-Key: $KEY" \
  -H "X-API-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id":  "5e1c7a40-0000-…",
    "symbol":      "BTC-USD",
    "side":        "BUY",
    "kind":        "LIMIT",
    "quantity":    0.05,
    "price":       62500,
    "tif":         "GTC",
    "flags":       { "post_only": true, "reduce_only": false },
    "client_id":   "my-bot:strategy-A:1234",
    "platform_id": "GMX"
  }'
```

### Request fields

<ParamField body="account_id" type="string" required>
  UUID of the account to trade on. Must be owned by the authenticated user.
</ParamField>

<ParamField body="symbol" type="string" required>
  Tradable symbol, e.g. `BTC-USD`, `ETH-USD`, `AAPL-USD`. See [`GET /v1/tickers`](/api-reference/market-data#tickers) for the full catalog. Symbol variants like `BTCUSD`, `BTC/USD`, and `btc-usd` are also accepted.
</ParamField>

<ParamField body="side" type="string" required>
  `BUY` or `SELL`.
</ParamField>

<ParamField body="kind" type="string" required>
  Order type: `MARKET` | `LIMIT` | `STOP` | `TAKE_PROFIT`.
</ParamField>

<ParamField body="quantity" type="number" required>
  Base-asset quantity. Must be positive.
</ParamField>

<ParamField body="price" type="number">
  Limit price. Required when `kind` is `LIMIT`.
</ParamField>

<ParamField body="trigger_price" type="number">
  Trigger reference price. Required when `kind` is `STOP` or `TAKE_PROFIT`.
</ParamField>

<ParamField body="tif" type="string">
  Time-in-force. One of:

  | Value | Meaning                                        |
  | ----- | ---------------------------------------------- |
  | `GTC` | Good till cancelled                            |
  | `GTD` | Good till date                                 |
  | `GTX` | Post-only intent (same as `GTC` + `post_only`) |
  | `IOC` | Immediate or cancel                            |
  | `FOK` | Fill or kill                                   |
</ParamField>

<ParamField body="flags.post_only" type="boolean">
  Reject the order if it would be immediately matched as a taker.
</ParamField>

<ParamField body="flags.reduce_only" type="boolean">
  Only reduce an existing position — never open or increase one.
</ParamField>

<ParamField body="flags.trigger_on_index" type="boolean">
  For stop/TP orders: trigger against the index price.
</ParamField>

<ParamField body="flags.trigger_on_mark" type="boolean">
  For stop/TP orders: trigger against the mark price.
</ParamField>

<ParamField body="client_id" type="string">
  Your own deduplication ID. Retrying with the same `client_id` is safe — the engine returns the original result rather than placing a duplicate. Surfaces in fills and audit logs.
</ParamField>

<ParamField body="platform_id" type="string">
  Execution venue override: `GMX` | `OSTIUM`. Overrides the account default for this order only.
</ParamField>

<ParamField body="parent_order_id" type="string">
  UUID of a parent order. Links a TP or SL to its entry.
</ParamField>

<ParamField body="position_id" type="string">
  UUID of a specific open position to target when reducing.
</ParamField>

### Response

```json theme={null}
{
  "order": {
    "id":     "…",
    "status": "OPEN",
    "…": "…"
  },
  "trades":     [],
  "violations": []
}
```

<ResponseField name="order" type="object">
  The created order with its current status.
</ResponseField>

<ResponseField name="trades" type="array">
  Fills generated immediately by the order (market orders, IOC/FOK).
</ResponseField>

<ResponseField name="violations" type="array">
  Non-empty when the order was rejected by a risk rule. Each entry includes `rule`, `severity`, and a human-readable message. The order is **not placed** when violations are present.
</ResponseField>

<Note>
  Risk-rule rejections come back with HTTP `200` but a non-empty `violations` array — check this field in every response.
</Note>

***

## List open orders

```bash theme={null}
GET /v1/account/:account_id/orders
```

**Required permission:** `READ_ONLY`

Returns all working orders for the account.

```bash theme={null}
curl "$BASE/account/$ACC/orders" \
  -H "X-API-Key: $KEY" \
  -H "X-API-Secret: $SECRET"
```

***

## Cancel an order

```bash theme={null}
POST /v1/account/:account_id/orders/:order_id/cancel
```

**Required permission:** `MANAGE_ORDERS`

Cancels a working order. Returns the final order state.

```bash theme={null}
curl -X POST "$BASE/account/$ACC/orders/$ORDER_ID/cancel" \
  -H "X-API-Key: $KEY" \
  -H "X-API-Secret: $SECRET"
```

***

## Close a position

```bash theme={null}
POST /v1/account/:account_id/close-position
```

**Required permission:** `TRADE`

Convenience endpoint that sends a reduce-only order against an open position.

```bash theme={null}
curl -X POST "$BASE/account/$ACC/close-position" \
  -H "X-API-Key: $KEY" \
  -H "X-API-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "symbol": "BTC-USD", "kind": "MARKET" }'
```

<ParamField body="symbol" type="string" required>
  Symbol of the position to close.
</ParamField>

<ParamField body="quantity" type="number">
  Partial close quantity. Omit to close the full position.
</ParamField>

<ParamField body="kind" type="string">
  Order type for the closing order. Defaults to `MARKET`.
</ParamField>

<ParamField body="price" type="number">
  Limit price (required if `kind` is `LIMIT`).
</ParamField>

<ParamField body="tif" type="string">
  Time-in-force for the closing order.
</ParamField>

<ParamField body="client_id" type="string">
  Deduplication ID. Safe to retry.
</ParamField>

***

## Idempotency

Always set a stable `client_id` per trading intent. If a request times out or returns a 5xx error, retry with the **same** `client_id` — the engine returns the original result without placing a duplicate order. See [Errors](/api-reference/errors) for retry guidance.