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

# Orders

Submit, view, and cancel orders on Turbine.

## Submit Order

Create a new order on the orderbook.

```
POST /api/v1/orders
```

### Request Body

```json
{
  "order": {
    "marketId": "0x1234...abcd",
    "trader": "0xYourAddress...",
    "side": 0,
    "outcome": 0,
    "price": 500000,
    "size": 10000000,
    "nonce": 1234567890,
    "expiration": 1735689600,
    "makerFeeRecipient": "0x0000000000000000000000000000000000000000"
  },
  "signature": "0x...",
  "permitSignature": {
    "nonce": 0,
    "value": "100000000",
    "deadline": 1735689600,
    "v": 27,
    "r": "0x...",
    "s": "0x..."
  }
}
```

### Order Fields

| Field               | Type    | Description                                                                   |
| ------------------- | ------- | ----------------------------------------------------------------------------- |
| `marketId`          | bytes32 | Market identifier                                                             |
| `trader`            | address | Your wallet address                                                           |
| `side`              | uint8   | `0` = BUY, `1` = SELL                                                         |
| `outcome`           | uint8   | `0` = YES, `1` = NO                                                           |
| `price`             | uint64  | Price in USDC (6 decimals, range 1–999999). `500000` = $0.50                  |
| `size`              | uint64  | Order size in shares (6 decimals). `10000000` = 10 shares                     |
| `nonce`             | uint64  | Unique nonce for the order                                                    |
| `expiration`        | uint64  | Unix timestamp when order expires (must be at least 60 seconds in the future) |
| `makerFeeRecipient` | address | Fee recipient (use zero address)                                              |

### Permit Signature (Optional)

For per-order gasless USDC approval. Include when buying without prior USDC approval.

{% hint style="info" %}
Recommended alternative: Use a one-time max permit via [`POST /api/v1/relayer/usdc-permit`](broken://pages/7ee185e9a6cef050e5f55ef1c17b9e6f347b3371#usdc-permit) instead. This approves USDC once, and all future orders can omit `permitSignature`.
{% endhint %}

| Field      | Type   | Description                        |
| ---------- | ------ | ---------------------------------- |
| `nonce`    | uint64 | On-chain permit nonce              |
| `value`    | string | Amount to approve (as string)      |
| `deadline` | uint64 | Permit expiration (Unix timestamp) |
| `v`        | uint8  | Signature component                |
| `r`        | string | Signature component (32 bytes hex) |
| `s`        | string | Signature component (32 bytes hex) |

### Response

```json
{
  "orderHash": "0xabc123...",
  "status": "accepted",
  "matches": 2,
  "timestamp": 1735689000
}
```

| Field       | Type    | Description                                         |
| ----------- | ------- | --------------------------------------------------- |
| `orderHash` | string  | Unique order identifier (EIP-712 hash)              |
| `status`    | string  | `"accepted"` on success                             |
| `matches`   | integer | Number of immediate matches against existing orders |
| `timestamp` | uint64  | Server timestamp                                    |

### Validation Rules

* **Price**: Must be between 1 and 999999 (exclusive of 0 and 1000000)
* **Size**: Must be greater than 0
* **Expiration**: Must be at least 60 seconds in the future
* **Signature**: Must be a valid EIP-712 typed data signature (65 bytes)

### EIP-712 Signing

Orders must be signed using EIP-712 typed data:

```javascript
const domain = {
  name: "Turbine Settlement",
  version: "1",
  chainId: 137,
  verifyingContract: "0xSettlementAddress..."
};

const types = {
  Order: [
    { name: "marketId", type: "bytes32" },
    { name: "trader", type: "address" },
    { name: "side", type: "uint8" },
    { name: "outcome", type: "uint8" },
    { name: "price", type: "uint64" },
    { name: "size", type: "uint64" },
    { name: "nonce", type: "uint64" },
    { name: "expiration", type: "uint64" },
    { name: "makerFeeRecipient", type: "address" }
  ]
};

const signature = await wallet._signTypedData(domain, types, order);
```

### Example

```bash
curl -X POST https://api.turbinefi.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "marketId": "0x...",
      "trader": "0x...",
      "side": 0,
      "outcome": 0,
      "price": 500000,
      "size": 10000000,
      "nonce": 1234567890,
      "expiration": 1735689600,
      "makerFeeRecipient": "0x0000000000000000000000000000000000000000"
    },
    "signature": "0x..."
  }'
```

## Get User Orders

Retrieve open orders for a user.

```
GET /api/v1/orders
```

### Query Parameters

| Parameter | Type    | Required | Description           |
| --------- | ------- | -------- | --------------------- |
| `trader`  | address | Yes      | User's wallet address |
| `market`  | bytes32 | No       | Filter by market ID   |

### Response

```json
{
  "orders": [
    {
      "orderHash": "0xabc...",
      "marketId": "0x...",
      "side": 0,
      "price": 500000,
      "size": 10000000,
      "remainingSize": 5000000,
      "timestamp": 1735689000
    }
  ],
  "count": 1
}
```

| Field           | Type   | Description                                                   |
| --------------- | ------ | ------------------------------------------------------------- |
| `orderHash`     | string | Order identifier                                              |
| `marketId`      | string | Market identifier                                             |
| `side`          | uint8  | `0` = BUY, `1` = SELL                                         |
| `price`         | uint64 | Order price (6 decimals). `500000` = $0.50                    |
| `size`          | uint64 | Original order size (6 decimals)                              |
| `remainingSize` | uint64 | Unfilled portion (6 decimals). `5000000` = 5 shares remaining |
| `timestamp`     | uint64 | When order was placed                                         |

### Example

```bash
curl "https://api.turbinefi.com/api/v1/orders?trader=0xYourAddress"
```

## Cancel Order

Cancel an open order.

```
DELETE /api/v1/orders/{hash}
```

### Path Parameters

| Parameter | Type   | Description          |
| --------- | ------ | -------------------- |
| `hash`    | string | Order hash to cancel |

### Query Parameters

| Parameter  | Type    | Required | Description                            |
| ---------- | ------- | -------- | -------------------------------------- |
| `marketId` | bytes32 | Yes      | Market ID                              |
| `side`     | string  | No       | `"buy"` or `"sell"` (default: `"buy"`) |

### Response

```json
{
  "status": "cancelled",
  "orderHash": "0xabc..."
}
```

### Example

```bash
curl -X DELETE "https://api.turbinefi.com/api/v1/orders/0xabc...?marketId=0x...&side=buy"
```

## Get All User Orders

Returns all open orders for a user across all markets on a specific chain.

```
GET /api/v1/users/{address}/orders
```

### Path Parameters

| Parameter | Type    | Description           |
| --------- | ------- | --------------------- |
| `address` | address | User's wallet address |

### Query Parameters

| Parameter  | Type    | Required | Description            |
| ---------- | ------- | -------- | ---------------------- |
| `chain_id` | integer | Yes      | Chain ID (e.g., `137`) |

### Response

```json
{
  "orders": [
    {
      "orderHash": "0xabc...",
      "marketId": "0x...",
      "marketQuestion": "Will ETH reach $5000?",
      "side": 0,
      "outcome": 0,
      "price": 500000,
      "size": 10000000,
      "remainingSize": 5000000,
      "timestamp": 1735689000
    }
  ]
}
```

### Example

```bash
curl "https://api.turbinefi.com/api/v1/users/0xYourAddress/orders?chain_id=137"
```

## Failed Trades

Returns trades that failed settlement in the last 24 hours.

```
GET /api/v1/failed-trades
```

### Response

```json
{
  "failedTrades": [
    {
      "marketId": "0x...",
      "txHash": "0x...",
      "buyerAddress": "0x...",
      "sellerAddress": "0x...",
      "fillSize": 10000000,
      "fillPrice": 500000,
      "reason": "execution reverted",
      "timestamp": "2025-01-01T00:00:00Z",
      "batchIndex": 0
    }
  ],
  "count": 1
}
```

## Pending Trades

Returns trades waiting for blockchain confirmation.

```
GET /api/v1/pending-trades
```

### Response

```json
{
  "pendingTrades": [
    {
      "marketId": "0x...",
      "txHash": "0x...",
      "buyerAddress": "0x...",
      "sellerAddress": "0x...",
      "fillSize": 10000000,
      "fillPrice": 500000,
      "timestamp": "2025-01-01T00:00:00Z",
      "isBatch": false,
      "batchIndex": 0
    }
  ],
  "count": 1
}
```

## Settlement Status

Look up the status of a specific settlement transaction.

```
GET /api/v1/settlements/{txHash}
```

### Path Parameters

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `txHash`  | string | Transaction hash |

### Response

```json
{
  "found": true,
  "txHash": "0x...",
  "status": "confirmed",
  "marketId": "0x...",
  "buyerAddress": "0x...",
  "sellerAddress": "0x...",
  "fillSize": 10000000,
  "fillPrice": 500000,
  "timestamp": "2025-01-01T00:00:00Z",
  "isBatch": false,
  "batchIndex": 0
}
```

If the transaction is not found, `found` will be `false` and all other fields will be omitted.

## Matching Behavior

{% stepper %}
{% step %}

### Price-time priority

Orders match against the best available price first.
{% endstep %}

{% step %}

### Same outcome only

BUY YES matches SELL YES, never SELL NO.
{% endstep %}

{% step %}

### Partial fills

Orders can partially fill; the remaining size stays on the book.
{% endstep %}

{% step %}

### Blockchain settlement

Matched trades are submitted to the blockchain for on-chain settlement.
{% endstep %}
{% endstepper %}

The `matches` field in the submit response indicates how many counter-orders were matched.


---

# 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:

```
GET https://docs.ojolabs.xyz/markets/api/orders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.