feat: add batch order helpers

README.md

@@ -298,6 +298,61 @@ Handle `None` for book `stats` and `transactTime`, and BBO `bestBid`, `bestAsk`,
 | `orders.cancel_all(params?)` | Cancel all open orders |
 | `orders.preview(params)` | Preview an order |
 | `orders.close_position(params)` | Close a position |
+| `orders.create_many(params)` | Create up to 20 orders |
+| `orders.cancel_many(params)` | Submit up to 20 cancellations |
+| `orders.modify_many(params)` | Submit up to 20 modifications |
+
+#### Batch orders
+
+Use `orders.create_many(params)`, `orders.cancel_many(params)`, and
+`orders.modify_many(params)` for up to 20 orders per request. Each accepts an
+`orders` list; cancel and modify entries include `orderId` and `marketSlug`.
+
+```python
+created = client.orders.create_many(
+    {
+        "orders": [
+            {
+                "marketSlug": "btc-100k",
+                "intent": "ORDER_INTENT_BUY_LONG",
+                "type": "ORDER_TYPE_LIMIT",
+                "price": {"value": "0.55", "currency": "USD"},
+                "quantity": 10,
+            },
+        ]
+    }
+)
+# For existing open orders:
+modified = client.orders.modify_many(
+    {
+        "orders": [
+            {
+                "orderId": "existing-order-id",
+                "marketSlug": "btc-100k",
+                "price": {"value": "0.50", "currency": "USD"},
+                "quantity": 10,
+            },
+        ]
+    }
+)
+canceled = client.orders.cancel_many(
+    {
+        "orders": [
+            {"orderId": "existing-order-id", "marketSlug": "btc-100k"},
+        ]
+    }
+)
+```
+
+With `AsyncPolymarketUS`, await each call. Batches are sent as one request and
+are never automatically retried or split. Invalid or oversized batches are
+reported through the existing API exceptions.
+
+`createdOrderIds` contains exchange-assigned IDs. `canceledOrderIds` and
+`modifiedOrderIds` echo the IDs submitted, and do **not** confirm each order
+was canceled or modified; unknown IDs can be ignored by the exchange. Follow
+`order_update` events for actual acceptance, fills, cancellations, replacements
+and rejections.
 
 ### RFQ trades (Authenticated)
 

polymarket_us/resources/orders.py

@@ -4,14 +4,20 @@
 from polymarket_us.types import (
     CancelAllOrdersParams,
     CancelAllOrdersResponse,
+    CancelOrderListParams,
+    CancelOrderListResponse,
     CancelOrderParams,
     ClosePositionParams,
     ClosePositionResponse,
+    CreateOrderListParams,
+    CreateOrderListResponse,
     CreateOrderParams,
     CreateOrderResponse,
     GetOpenOrdersParams,
     GetOpenOrdersResponse,
     GetOrderResponse,
+    ModifyOrderListParams,
+    ModifyOrderListResponse,
     ModifyOrderParams,
     PreviewOrderParams,
     PreviewOrderResponse,
@@ -29,6 +35,30 @@ def create(self, params: CreateOrderParams) -> CreateOrderResponse:
             authenticated=True,
         )
 
+    def create_many(self, params: CreateOrderListParams) -> CreateOrderListResponse:
+        """Create up to 20 orders in one request."""
+        return self._client.post(
+            "/v1/orders/batched",
+            body=dict(params),
+            authenticated=True,
+        )
+
+    def cancel_many(self, params: CancelOrderListParams) -> CancelOrderListResponse:
+        """Submit up to 20 cancellations; returned IDs do not confirm success."""
+        return self._client.post(
+            "/v1/orders/batched/cancel",
+            body=dict(params),
+            authenticated=True,
+        )
+
+    def modify_many(self, params: ModifyOrderListParams) -> ModifyOrderListResponse:
+        """Submit up to 20 modifications; returned IDs do not confirm success."""
+        return self._client.post(
+            "/v1/orders/batched/modify",
+            body=dict(params),
+            authenticated=True,
+        )
+
     def list(self, params: GetOpenOrdersParams | None = None) -> GetOpenOrdersResponse:
         """List open orders."""
         return self._client.get(
@@ -93,6 +123,30 @@ async def create(self, params: CreateOrderParams) -> CreateOrderResponse:
             authenticated=True,
         )
 
+    async def create_many(self, params: CreateOrderListParams) -> CreateOrderListResponse:
+        """Create up to 20 orders in one request."""
+        return await self._client.post(
+            "/v1/orders/batched",
+            body=dict(params),
+            authenticated=True,
+        )
+
+    async def cancel_many(self, params: CancelOrderListParams) -> CancelOrderListResponse:
+        """Submit up to 20 cancellations; returned IDs do not confirm success."""
+        return await self._client.post(
+            "/v1/orders/batched/cancel",
+            body=dict(params),
+            authenticated=True,
+        )
+
+    async def modify_many(self, params: ModifyOrderListParams) -> ModifyOrderListResponse:
+        """Submit up to 20 modifications; returned IDs do not confirm success."""
+        return await self._client.post(
+            "/v1/orders/batched/modify",
+            body=dict(params),
+            authenticated=True,
+        )
+
     async def list(self, params: GetOpenOrdersParams | None = None) -> GetOpenOrdersResponse:
         """List open orders."""
         return await self._client.get(

polymarket_us/types/__init__.py

@@ -39,9 +39,14 @@
 from polymarket_us.types.orders import (
     CancelAllOrdersParams,
     CancelAllOrdersResponse,
+    CancelOrderListItem,
+    CancelOrderListParams,
+    CancelOrderListResponse,
     CancelOrderParams,
     ClosePositionParams,
     ClosePositionResponse,
+    CreateOrderListParams,
+    CreateOrderListResponse,
     CreateOrderParams,
     CreateOrderResponse,
     Execution,
@@ -51,6 +56,9 @@
     GetOrderResponse,
     ManualOrderIndicator,
     MarketMetadata,
+    ModifyOrderListItem,
+    ModifyOrderListParams,
+    ModifyOrderListResponse,
     ModifyOrderParams,
     Order,
     OrderIntent,
@@ -155,6 +163,14 @@
     "GetMarketBookResponse",
     "GetMarketBBOResponse",
     # Orders
+    "CreateOrderListParams",
+    "CreateOrderListResponse",
+    "CancelOrderListItem",
+    "CancelOrderListParams",
+    "CancelOrderListResponse",
+    "ModifyOrderListItem",
+    "ModifyOrderListParams",
+    "ModifyOrderListResponse",
     "OrderType",
     "OrderSide",
     "OutcomeSide",

polymarket_us/types/orders.py

@@ -119,7 +119,7 @@ class CreateOrderParams(TypedDict, total=False):
     intent: OrderIntent  # Required
     type: OrderType
     price: Amount
-    quantity: int
+    quantity: int | float
     tif: TimeInForce
     participateDontInitiate: bool
     goodTillTime: str
@@ -142,7 +142,7 @@ class ModifyOrderParams(TypedDict, total=False):
 
     marketSlug: str  # Required
     price: Amount
-    quantity: int
+    quantity: int | float
     tif: TimeInForce
     participateDontInitiate: bool
     goodTillTime: str
@@ -211,3 +211,51 @@ class ClosePositionResponse(TypedDict, total=False):
 
     id: str
     executions: list[Execution]
+
+
+class CreateOrderListParams(TypedDict):
+    """A batch of up to 20 orders to create."""
+
+    orders: list[CreateOrderParams]
+
+
+class CreateOrderListResponse(TypedDict):
+    """Exchange-assigned IDs; follow the order stream for execution outcomes."""
+
+    createdOrderIds: list[str]
+
+
+class CancelOrderListItem(CancelOrderParams):
+    """An existing order to cancel in a batch."""
+
+    orderId: str
+
+
+class CancelOrderListParams(TypedDict):
+    """A batch of up to 20 orders to cancel."""
+
+    orders: list[CancelOrderListItem]
+
+
+class CancelOrderListResponse(TypedDict):
+    """IDs submitted for cancellation, not confirmation of per-order success."""
+
+    canceledOrderIds: list[str]
+
+
+class ModifyOrderListItem(ModifyOrderParams):
+    """An existing order to modify; marketSlug is required by the API."""
+
+    orderId: str
+
+
+class ModifyOrderListParams(TypedDict):
+    """A batch of up to 20 orders to modify."""
+
+    orders: list[ModifyOrderListItem]
+
+
+class ModifyOrderListResponse(TypedDict):
+    """IDs submitted for modification, not confirmation of per-order success."""
+
+    modifiedOrderIds: list[str]

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "polymarket-us"
-version = "2.3.0"
+version = "2.4.0"
 description = "Polymarket US Python SDK"
 readme = "README.md"
 license = "MIT"