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

# Trading

Order placement, cancellation, AMM trades, and smart-routed market orders.

{% hint style="warning" %}
**All endpoints in this section require authentication.** Include `Authorization: Bearer <token>` in every request.

Trade quantities are always integers in **micro-units** (`quantity × 1,000,000`). Limit order prices are decimal numbers between `0.01` and `0.99`.
{% endhint %}

***

## POST /orders

Place a limit order (resting on the order book until filled or cancelled).

### Request body

| Field       | Type            | Description                                                                           |
| ----------- | --------------- | ------------------------------------------------------------------------------------- |
| `marketId`  | string          | Target market                                                                         |
| `side`      | `BUY` \| `SELL` | Trade direction                                                                       |
| `outcome`   | `YES` \| `NO`   | Outcome to trade                                                                      |
| `orderType` | `GTC` \| `FOK`  | `GTC` rests until filled/cancelled; `FOK` fills completely immediately or is rejected |
| `price`     | number          | Limit price, `0.01`–`0.99`                                                            |
| `quantity`  | number          | Quantity in micro-units                                                               |

### Code examples

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

```bash
curl -X POST "https://predict.pretoke.xyz/api/v1/orders" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "mkt_01hz...",
    "side": "BUY",
    "outcome": "YES",
    "orderType": "GTC",
    "price": 0.55,
    "quantity": 100000000
  }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://predict.pretoke.xyz/api/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    marketId: 'mkt_01hz...',
    side: 'BUY',
    outcome: 'YES',
    orderType: 'GTC',
    price: 0.55,
    quantity: 100000000
  })
});

const { data } = await response.json();
console.log('Order placed:', data.orderId);
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    "https://predict.pretoke.xyz/api/v1/orders",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "marketId": "mkt_01hz...",
        "side": "BUY",
        "outcome": "YES",
        "orderType": "GTC",
        "price": 0.55,
        "quantity": 100000000
    }
)
order = response.json()["data"]
print(f"Order ID: {order['orderId']}")
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.post(
  'https://predict.pretoke.xyz/api/v1/orders',
  {
    marketId: 'mkt_01hz...',
    side: 'BUY',
    outcome: 'YES',
    orderType: 'GTC',
    price: 0.55,
    quantity: 100000000
  },
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
console.log('Order placed:', result.data.orderId);
```

{% endtab %}
{% endtabs %}

### Errors

`400 Bad Request` — invalid price range, non-positive quantity, insufficient balance, etc.

{% hint style="info" %}
**Rate limit:** 10 requests / 60s (trade category).
{% endhint %}

***

## DELETE /orders/:id

Cancel an open order. Locked collateral for the unfilled portion is released back to your available balance.

### Code examples

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

```bash
curl -X DELETE "https://predict.pretoke.xyz/api/v1/orders/ord_01hz..." \
  -H "Authorization: Bearer <token>"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch('https://predict.pretoke.xyz/api/v1/orders/ord_01hz...', {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${accessToken}` }
});
```

{% endtab %}

{% tab title="Python" %}

```python
requests.delete(
    "https://predict.pretoke.xyz/api/v1/orders/ord_01hz...",
    headers={"Authorization": f"Bearer {access_token}"}
)
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
await axios.delete('https://predict.pretoke.xyz/api/v1/orders/ord_01hz...', {
  headers: { Authorization: `Bearer ${accessToken}` }
});
```

{% endtab %}
{% endtabs %}

### Errors

`404 Not Found` — `{ "error": { "code": "ORDER_NOT_FOUND" } }`

***

## GET /orders

List your open orders, optionally filtered by market.

### Query parameters

| Param      | Type              | Description               |
| ---------- | ----------------- | ------------------------- |
| `marketId` | string (optional) | Filter to a single market |

### Code examples

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

```bash
curl -X GET "https://predict.pretoke.xyz/api/v1/orders?marketId=mkt_01hz..." \
  -H "Authorization: Bearer <token>"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://predict.pretoke.xyz/api/v1/orders?marketId=mkt_01hz...', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});
const { data: orders } = await response.json();
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    "https://predict.pretoke.xyz/api/v1/orders",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"marketId": "mkt_01hz..."}
)
orders = response.json()["data"]
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.get('https://predict.pretoke.xyz/api/v1/orders', {
  params: { marketId: 'mkt_01hz...' },
  headers: { Authorization: `Bearer ${accessToken}` }
});
```

{% endtab %}
{% endtabs %}

***

## POST /trade/amm

Execute a trade directly against the automated market maker.

### Request body

```json
{ "marketId": "mkt_01hz...", "side": "BUY", "outcome": "YES", "quantity": "50000000" }
```

### Code examples

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

```bash
curl -X POST "https://predict.pretoke.xyz/api/v1/trade/amm" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "marketId": "mkt_01hz...", "side": "BUY", "outcome": "YES", "quantity": "50000000" }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://predict.pretoke.xyz/api/v1/trade/amm', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    marketId: 'mkt_01hz...',
    side: 'BUY',
    outcome: 'YES',
    quantity: '50000000'
  })
});

const { data: trade } = await response.json();
console.log(`Filled: ${trade.filledQuantity} @ avg ${trade.avgPrice}`);
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    "https://predict.pretoke.xyz/api/v1/trade/amm",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"marketId": "mkt_01hz...", "side": "BUY", "outcome": "YES", "quantity": "50000000"}
)
trade = response.json()["data"]
print(f"Filled: {trade['filledQuantity']} @ avg {trade['avgPrice']}")
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.post(
  'https://predict.pretoke.xyz/api/v1/trade/amm',
  { marketId: 'mkt_01hz...', side: 'BUY', outcome: 'YES', quantity: '50000000' },
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
```

{% endtab %}
{% endtabs %}

### Response `200 OK`

```json
{
  "data": {
    "tradeId": "trd_01hz...",
    "venue": "AMM",
    "filledQuantity": "50000000",
    "avgPrice": "0.635",
    "totalCost": "31810000",
    "fee": "158750"
  },
  "requestId": "..."
}
```

***

## POST /trade/market

Execute a smart-routed market order — automatically picks the best venue or splits between order book and AMM.

### Request body

Same as `POST /trade/amm`: `{ marketId, side, outcome, quantity }`.

### Code examples

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

```bash
curl -X POST "https://predict.pretoke.xyz/api/v1/trade/market" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "marketId": "mkt_01hz...", "side": "BUY", "outcome": "YES", "quantity": "50000000" }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://predict.pretoke.xyz/api/v1/trade/market', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    marketId: 'mkt_01hz...',
    side: 'BUY',
    outcome: 'YES',
    quantity: '50000000'
  })
});
const { data: trade } = await response.json();
console.log(`Venue: ${trade.venue}, Cost: ${trade.totalCost}`);
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    "https://predict.pretoke.xyz/api/v1/trade/market",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"marketId": "mkt_01hz...", "side": "BUY", "outcome": "YES", "quantity": "50000000"}
)
trade = response.json()["data"]
print(f"Venue: {trade['venue']}, Cost: {trade['totalCost']}")
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { data: result } = await axios.post(
  'https://predict.pretoke.xyz/api/v1/trade/market',
  { marketId: 'mkt_01hz...', side: 'BUY', outcome: 'YES', quantity: '50000000' },
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
```

{% endtab %}
{% endtabs %}

### Response `200 OK`

Same shape as `POST /trade/amm`, with `venue` reflecting actual routing: `CLOB`, `AMM`, or `HYBRID`.


---

# 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.pretoke.xyz/api-reference/trading.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.