Orders API

Create, manage, and cancel trading orders.

Endpoints

Method	Endpoint	Description
POST /api/sdk/orders	Create a new order
GET /api/sdk/orders	List orders
GET /api/sdk/orders/:orderId	Get order by ID
GET /api/sdk/orders/by-client-id	Get order by client ID
PATCH /api/sdk/orders/:orderId	Amend an order
DELETE /api/sdk/orders/:orderId	Cancel an order
GET /api/sdk/orders/:orderId/fills	Get order fills
POST /api/sdk/orders/batch	Create multiple orders
DELETE /api/sdk/orders/batch	Cancel all orders

The Order Object

{
  "orderId": "ord_abc123def456",
  "clientOrderId": "my-order-001",
  "side": "buy",
  "asset": "BTC",
  "quantity": 1.5,
  "price": 50000.00,
  "orderType": "limit",
  "timeInForce": "GTC",
  "status": "open",
  "filledQuantity": 0.5,
  "remainingQuantity": 1.0,
  "averagePrice": 49950.00,
  "metadata": {
    "strategy": "momentum"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}

Attributes

Attribute	Type	Description
`orderId`	string	Unique order identifier
`clientOrderId`	string	Your custom identifier (optional)
`side`	string	`buy` or `sell`
`asset`	string	Asset symbol (e.g., `BTC`, `ETH`)
`quantity`	number	Order quantity
`price`	number	Limit price (null for market orders)
`orderType`	string	`limit` or `market`
`timeInForce`	string	`GTC`, `IOC`, or `FOK`
`status`	string	Order status
`filledQuantity`	number	Quantity filled
`remainingQuantity`	number	Quantity remaining
`averagePrice`	number	Average fill price
`metadata`	object	Custom metadata
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

Order Statuses

Status	Description
`open`	Order is active and waiting to be filled
`partially_filled`	Order is partially filled
`filled`	Order is completely filled
`cancelled`	Order was cancelled
`rejected`	Order was rejected
`expired`	Order expired (for IOC/FOK)

Time in Force

Value	Description
`GTC`	Good Till Cancelled - remains active until filled or cancelled
`IOC`	Immediate Or Cancel - fills immediately, cancels remainder
`FOK`	Fill Or Kill - must fill completely or is cancelled entirely

Create Order

Create a new order.

POST /api/sdk/orders

Required Scope: TRADE

Request Body

Parameter	Type	Required	Description
`side`	string	Yes	`buy` or `sell`
`asset`	string	Yes	Asset symbol (e.g., `BTC`)
`quantity`	number	Yes	Order quantity (> 0)
`price`	number	Conditional	Required for limit orders
`orderType`	string	No	`limit` (default) or `market`
`timeInForce`	string	No	`GTC` (default), `IOC`, or `FOK`
`clientOrderId`	string	No	Your custom ID (max 64 chars)
`metadata`	object	No	Custom key-value pairs

Example Request

curl -X POST https://api.zenotc.com/api/sdk/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature" \
  -d '{
    "side": "buy",
    "asset": "BTC",
    "quantity": 1.5,
    "price": 50000.00,
    "orderType": "limit",
    "timeInForce": "GTC",
    "clientOrderId": "my-order-001"
  }'

order = api_request("POST", "/api/sdk/orders", {
    "side": "buy",
    "asset": "BTC",
    "quantity": 1.5,
    "price": 50000.00,
    "orderType": "limit",
    "timeInForce": "GTC",
    "clientOrderId": "my-order-001"
})

Response

{
  "orderId": "ord_abc123def456",
  "clientOrderId": "my-order-001",
  "side": "buy",
  "asset": "BTC",
  "quantity": 1.5,
  "price": 50000.00,
  "orderType": "limit",
  "timeInForce": "GTC",
  "status": "open",
  "filledQuantity": 0,
  "remainingQuantity": 1.5,
  "averagePrice": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Errors

Code	Description
400	Invalid parameters (missing required field, invalid value)
401	Authentication failed
403	Insufficient scope (requires `TRADE`)
422	Risk check failed (exceeds limits)

List Orders

Retrieve a list of orders with optional filters.

GET /api/sdk/orders

Required Scope: READ

Query Parameters

Parameter	Type	Default	Description
`statuses`	string	-	Comma-separated: `open`, `partially_filled`, `filled`, `cancelled`
`asset`	string	-	Filter by asset symbol
`side`	string	-	Filter by side: `buy` or `sell`
`page`	integer	1	Page number
`limit`	integer	50	Results per page (max 100)

Example Request

curl -X GET "https://api.zenotc.com/api/sdk/orders?statuses=open,partially_filled&asset=BTC&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

orders = api_request("GET", "/api/sdk/orders?statuses=open&asset=BTC&limit=10")

Response

{
  "orders": [
    {
      "orderId": "ord_abc123def456",
      "clientOrderId": "my-order-001",
      "side": "buy",
      "asset": "BTC",
      "quantity": 1.5,
      "price": 50000.00,
      "status": "open",
      "filledQuantity": 0,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

Get Order

Retrieve a specific order by ID.

GET /api/sdk/orders/:orderId

Required Scope: READ

Path Parameters

Parameter	Type	Description
`orderId`	string	The order ID

Example Request

curl -X GET https://api.zenotc.com/api/sdk/orders/ord_abc123def456 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

order = api_request("GET", "/api/sdk/orders/ord_abc123def456")

Response

Returns the Order object.

Errors

Code	Description
404	Order not found

Get Order by Client ID

Retrieve an order using your custom client order ID.

GET /api/sdk/orders/by-client-id

Required Scope: READ

Query Parameters

Parameter	Type	Required	Description
`clientOrderId`	string	Yes	Your custom order ID

Example Request

curl -X GET "https://api.zenotc.com/api/sdk/orders/by-client-id?clientOrderId=my-order-001" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

order = api_request("GET", "/api/sdk/orders/by-client-id?clientOrderId=my-order-001")

Response

Returns the Order object.

Amend Order

Modify an existing order's quantity or price.

PATCH /api/sdk/orders/:orderId

Required Scope: TRADE

Path Parameters

Parameter	Type	Description
`orderId`	string	The order ID

Request Body

Parameter	Type	Required	Description
`quantity`	number	No	New order quantity
`price`	number	No	New limit price

At least one of quantity or price must be provided.

Example Request

curl -X PATCH https://api.zenotc.com/api/sdk/orders/ord_abc123def456 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature" \
  -d '{
    "quantity": 2.0,
    "price": 51000.00
  }'

order = api_request("PATCH", "/api/sdk/orders/ord_abc123def456", {
    "quantity": 2.0,
    "price": 51000.00
})

Response

Returns the updated Order object.

Errors

Code	Description
400	Invalid parameters
404	Order not found
409	Order cannot be amended (already filled/cancelled)

Cancel Order

Cancel an open order.

DELETE /api/sdk/orders/:orderId

Required Scope: TRADE

Path Parameters

Parameter	Type	Description
`orderId`	string	The order ID

Example Request

curl -X DELETE https://api.zenotc.com/api/sdk/orders/ord_abc123def456 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

result = api_request("DELETE", "/api/sdk/orders/ord_abc123def456")

Response

{
  "orderId": "ord_abc123def456",
  "status": "cancelled",
  "cancelledAt": "2024-01-15T10:35:00.000Z"
}

Get Order Fills

Retrieve fills (trades) for a specific order.

GET /api/sdk/orders/:orderId/fills

Required Scope: READ

Path Parameters

Parameter	Type	Description
`orderId`	string	The order ID

Example Request

curl -X GET https://api.zenotc.com/api/sdk/orders/ord_abc123def456/fills \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature"

Response

{
  "fills": [
    {
      "fillId": "fill_xyz789",
      "orderId": "ord_abc123def456",
      "price": 49950.00,
      "quantity": 0.5,
      "side": "buy",
      "fee": 24.975,
      "feeCurrency": "USD",
      "executedAt": "2024-01-15T10:32:00.000Z"
    },
    {
      "fillId": "fill_xyz790",
      "orderId": "ord_abc123def456",
      "price": 50000.00,
      "quantity": 0.5,
      "side": "buy",
      "fee": 25.00,
      "feeCurrency": "USD",
      "executedAt": "2024-01-15T10:33:00.000Z"
    }
  ]
}

Create Batch Orders

Create multiple orders in a single request (up to 100 orders).

POST /api/sdk/orders/batch

Required Scope: TRADE

Request Body

Parameter	Type	Required	Description
`orders`	array	Yes	Array of order objects (max 100)

Each order in the array follows the same schema as Create Order.

Example Request

curl -X POST https://api.zenotc.com/api/sdk/orders/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature" \
  -d '{
    "orders": [
      {"side": "buy", "asset": "BTC", "quantity": 1.0, "price": 49000},
      {"side": "buy", "asset": "BTC", "quantity": 1.0, "price": 48000},
      {"side": "sell", "asset": "BTC", "quantity": 0.5, "price": 52000}
    ]
  }'

result = api_request("POST", "/api/sdk/orders/batch", {
    "orders": [
        {"side": "buy", "asset": "BTC", "quantity": 1.0, "price": 49000},
        {"side": "buy", "asset": "BTC", "quantity": 1.0, "price": 48000},
        {"side": "sell", "asset": "BTC", "quantity": 0.5, "price": 52000}
    ]
})

Response

{
  "results": [
    {"success": true, "orderId": "ord_001", "clientOrderId": null},
    {"success": true, "orderId": "ord_002", "clientOrderId": null},
    {"success": false, "error": "Insufficient balance", "index": 2}
  ],
  "summary": {
    "total": 3,
    "successful": 2,
    "failed": 1
  }
}

Cancel All Orders

Cancel all open orders, optionally filtered by asset or side.

DELETE /api/sdk/orders/batch

Required Scope: TRADE

Request Body

Parameter	Type	Required	Description
`asset`	string	No	Cancel only orders for this asset
`side`	string	No	Cancel only `buy` or `sell` orders

Example Request

curl -X DELETE https://api.zenotc.com/api/sdk/orders/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Timestamp: 1705312200000" \
  -H "X-API-Signature: your_signature" \
  -d '{"asset": "BTC"}'

# Cancel all BTC orders
result = api_request("DELETE", "/api/sdk/orders/batch", {"asset": "BTC"})

# Cancel all orders
result = api_request("DELETE", "/api/sdk/orders/batch", {})

Response

{
  "cancelledCount": 5,
  "cancelledOrders": [
    "ord_001",
    "ord_002",
    "ord_003",
    "ord_004",
    "ord_005"
  ]
}

Endpoints​

The Order Object​

Attributes​

Order Statuses​

Time in Force​

Create Order​

Request Body​

Example Request​

Response​

Errors​

List Orders​

Query Parameters​

Example Request​

Response​

Get Order​

Path Parameters​

Example Request​

Response​

Errors​

Get Order by Client ID​

Query Parameters​

Example Request​

Response​

Amend Order​

Path Parameters​

Request Body​

Example Request​

Response​

Errors​

Cancel Order​

Path Parameters​

Example Request​

Response​

Get Order Fills​

Path Parameters​

Example Request​

Response​

Create Batch Orders​

Request Body​

Example Request​

Response​

Cancel All Orders​

Request Body​

Example Request​

Response​

Endpoints

The Order Object

Attributes

Order Statuses

Time in Force

Create Order

Request Body

Example Request

Response

Errors

List Orders

Query Parameters

Example Request

Response

Get Order

Path Parameters

Example Request

Response

Errors

Get Order by Client ID

Query Parameters

Example Request

Response

Amend Order

Path Parameters

Request Body

Example Request

Response

Errors

Cancel Order

Path Parameters

Example Request

Response

Get Order Fills

Path Parameters

Example Request

Response

Create Batch Orders

Request Body

Example Request

Response

Cancel All Orders

Request Body

Example Request

Response