# TypeScript SDK — Clearing: Clearing Orders

Create, manage, and query OTC clearing orders. All methods are on `client.clearingInstant`.

See the [API specifications](/api-specifications) for full request/response schemas and the [authentication guide](/tools/typescript-sdk/authentication) for setup.

## Methods

### createNewClearingOrder

`POST /v1/clearing/new` · Authenticated

Creates a new OTC clearing order. The request body is [validated client-side](/tools/typescript-sdk/deep-dives/request-validation). The SDK enforces:

- `symbol` — required string
- `amount` — required decimal string
- `price` — required decimal string
- `side` — required enum: `"buy"` or `"sell"`
- `counterparty_id` — optional string
- `expires_in_hrs` — optional finite number
- `account` — optional string (required for Master API keys to target a specific sub-account)

> **Note:** If you are using a Master API key, you must include the `account` field to specify which sub-account the clearing order applies to.
```ts
const order = await client.clearingInstant.createNewClearingOrder({
  symbol: "BTCUSD",
  amount: "1.0",
  price: "50000.00",
  side: "buy",
  counterparty_id: "counterparty-abc",
  expires_in_hrs: 24,
});

console.log(order.clearing_id); // unique clearing order ID
```

This is a POST mutation — never automatically retried. Prices and amounts must be decimal strings (e.g. `"50000.00"`, not `50000`).

### getClearingOrder

`POST /v1/clearing/status` · Authenticated

Retrieves the current status of a clearing order by its clearing ID.

```ts
const status = await client.clearingInstant.getClearingOrder({
  clearing_id: "clearing-123",
});

console.log(`Status: ${status.status}, Symbol: ${status.symbol}`);
```

This is a POST mutation — never automatically retried.

### cancelClearingOrder

`POST /v1/clearing/cancel` · Authenticated

Cancels an active clearing order. The request body is [validated client-side](/tools/typescript-sdk/deep-dives/request-validation) — `clearing_id` is a required string.

```ts
const result = await client.clearingInstant.cancelClearingOrder({
  clearing_id: "clearing-123",
});

console.log(result.result);  // e.g. "ok"
console.log(result.details); // description of the result
```

This is a POST mutation — never automatically retried. Only orders in a cancellable state can be cancelled.

### confirmClearingOrder

`POST /v1/clearing/confirm` · Authenticated

Confirms a clearing order, finalizing the trade. The request body is [validated client-side](/tools/typescript-sdk/deep-dives/request-validation). The SDK enforces:

- `clearing_id` — required string
- `symbol` — required string
- `amount` — required decimal string
- `price` — required decimal string
- `side` — required enum: `"buy"` or `"sell"`

```ts
const result = await client.clearingInstant.confirmClearingOrder({
  clearing_id: "clearing-123",
  symbol: "BTCUSD",
  amount: "1.0",
  price: "50000.00",
  side: "buy",
});

console.log(result.result); // e.g. "ok"
```

This is a POST mutation — never automatically retried. Confirmation is irreversible — ensure the fields match the original order before confirming.

### listClearingOrders

`POST /v1/clearing/list` · Authenticated

Lists clearing orders with optional time-range filtering. The response is a **wrapper object** with an `orders` array — not a bare array. Each order uses `quantity` (number) for the amount and `price` (number) for the price.

```ts
const response = await client.clearingInstant.listClearingOrders({});

for (const order of response.orders ?? []) {
  console.log(`${order.clearing_id}: ${order.symbol} ${order.side} ${order.quantity} @ ${order.price}`);
}
```

> **Tip:** Timestamp filters (`expiration_start`, `expiration_end`, `submission_start`, `submission_end`) accept `bigint` or `number`. Note that `price` and `quantity` in the list response are **numbers**, not strings.

### listClearingTrades

`POST /v1/clearing/trades` · Authenticated

Returns a list of executed clearing trades. The response is a **wrapper object** with a `results` array. Trades use `pair` (not `symbol`) and `quantity` (not `amount`).

```ts
const response = await client.clearingInstant.listClearingTrades({});

for (const trade of response.results ?? []) {
  console.log(`${trade.pair}: ${trade.quantity} @ ${trade.price} (${trade.sourceSide})`);
}
```

> **Tip:** The request body accepts an optional `timestamp` (bigint or number) for pagination. Each trade includes `clearingId`, `sourceAccount`, `targetAccount`, and status timestamps (`createdMs`, `lastUpdatedMs`, `expirationTimeMs`).

### listClearingBrokers

`POST /v1/clearing/broker/list` · Authenticated

Lists broker clearing orders. The response is a **wrapper object** with an `orders` array. Broker orders use `source_counterparty_id` (not `counterparty_id`) and `source_side` (not `side`).

```ts
const response = await client.clearingInstant.listClearingBrokers({});

for (const order of response.orders ?? []) {
  console.log(`${order.clearing_id}: ${order.source_counterparty_id} → ${order.target_counterparty_id}`);
  console.log(`  ${order.symbol} ${order.source_side} ${order.quantity} @ ${order.price}`);
}
```

> **Tip:** Timestamp filters accept `bigint` or `number` values. Like `listClearingOrders`, `price` and `quantity` are **numbers** in the response.

### createNewBrokerOrder

`POST /v1/clearing/broker/new` · Authenticated

Creates a new clearing order as a broker on behalf of two counterparties. The request body is [validated client-side](/tools/typescript-sdk/deep-dives/request-validation). The SDK enforces:

- `source_counterparty_id` — required string
- `target_counterparty_id` — required string
- `symbol` — required string
- `amount` — required decimal string
- `price` — required decimal string
- `side` — required enum: `"buy"` or `"sell"`
- `expires_in_hrs` — required finite number

```ts
const order = await client.clearingInstant.createNewBrokerOrder({
  source_counterparty_id: "counterparty-a",
  target_counterparty_id: "counterparty-b",
  symbol: "BTCUSD",
  amount: "5.0",
  price: "50000.00",
  side: "buy",
  expires_in_hrs: 48,
});

console.log(order.clearing_id); // unique clearing order ID
console.log(order.result);      // "AwaitSourceTargetConfirm"
```

This is a POST mutation — never automatically retried. All amounts and prices must be decimal strings. `expires_in_hrs` must be a finite number (not a string).

## What's next

- [Instant Orders](/tools/typescript-sdk/reference/clearing/instant-orders) — instant quote and execution
- [Request Validation](/tools/typescript-sdk/deep-dives/request-validation) — how client-side validation works
- [Data Types](/tools/typescript-sdk/deep-dives/data-types) — decimal strings and bigint fields