> For the complete documentation index, see [llms.txt](https://predictbase.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://predictbase.gitbook.io/docs/developer/endpoints/place-and-manage-orders.md).

# Place & Manage Orders

PredictBase allows users to **place, update, and cancel orders** programmatically using authenticated API requests.

All order-related endpoints require a **user-bound API key** and enforce strict ownership and status checks.

***

### Authentication

All endpoints on this page require an API key passed via the request **header**:

```
x-api-key: YOUR_API_KEY
```

The API key must be authorized for the user performing the action.

***

### Create a new Order

Places a new buy or sell order on an existing market.

#### Endpoint

```http
POST /create-order
```

#### Full URL

```
https://api.predictbase.app/create-order
```

#### Request Body

```json
{
  "kind": "NEW_ORDER",
  "order": {
    "type": "LIMIT",
    "side": "BUY",
    "marketId": "10744",
    "optionIndex": 0,
    "qty": 1,
    "price": 0.42,
    "userId": "0xUserAddress",
    "timeInForce": "GTC",
    "receivedAt": 1765595666776
  },
  "meta": {
    "clientOrderId": "ORD#abc123",
    "originalQty": 1
  }

```

#### Response (Success)

```json
{
  "success": true,
  "orderId": "ORDER#abc123",
  "status": "RECEIVED"
}
```

***

### Update an Order

Updates the **price** of an existing order while it is still pending.

#### Endpoint

```http
POST /update-order
```

#### Full URL

```
https://api.predictbase.app/update-order
```

#### Request Body

```json
{
  "orderId": "ORDER#abc123",
  "user": "0xUserAddress",
  "price": 0.42
}
```

#### Response (Success)

```json
{
  "success": true,
  "order": {
    "id": "ORDER#abc123",
    "price": 0.42,
    "status": "RECEIVED",
    "updatedAt": "2025-01-01T00:00:00.000Z",
    "...": "other fields"
  }
}
```

#### Errors

| Status | Meaning                               |
| ------ | ------------------------------------- |
| 400    | Missing `orderId`, `user`, or `price` |
| 409    | Invalid status or user mismatch       |
| 500    | Unexpected server error               |

***

### Cancel an Order

Cancels an existing order that has not been fully filled.

#### Endpoint

```http
POST /cancel-order
```

#### Full URL

```
https://api.predictbase.app/cancel-order
```

#### Response (Success)

```json
{
  "success": true,
  "order": {
    "id": "ORDER#abc123",
    "status": "CANCELED",
    "updatedAt": "2025-01-01T00:00:00.000Z",
    "...": "other fields"
  }

```

#### Possible Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| 404    | Order not found                          |
| 403    | User mismatch                            |
| 400    | Order status not cancelable              |
| 409    | Order was filled or updated concurrently |
| 500    | Unexpected server error                  |

***

### View your Orders

Returns a list of user active orders.

#### Endpoint

```http
GET /get_user_orders/{userAddress}
```

#### Full URL

```
https://api.predictbase.app/get_user_orders/{userAddress}
```

#### Response (Success)

```json
[
  {
    "id": "ORDER#6ddcdb08-3147-47ce-8650-e6484e5491d2",
    "marketId": "10001",
    "optionIndex": 0,
    "side": "SELL",
    "type": "LIMIT",
    "qty": 300,
    "filledQty": 0,
    "price": 0.5,
    "maxSlippageBps": null,
    "outcome": "YES",
    "userId": "0x0...",
    "timeInForce": "GTC",
    "status": "RECEIVED",
    "createdAt": "2026-01-03T23:45:24.451Z",
    "updatedAt": "2026-01-03T23:45:24.451Z",
    "__typename": "IntakeOrder"
  },
]
```

***

#### Behavior

* The user is resolved from the **API key**
* Order prices are specified in **USD (USDC) dollar value**.
  * `price = 0.42` means **$0.42 USD** (42 cents)
  * `price = 1.00` means **$1.00 USD**
  * Prices must be between **0.00 and 1.00**

***

### 💡 Common Use Cases

* Trading bots
* Market-making strategies
* Order management dashboards
* Automated re-pricing systems