Skip to content

feat(spot): add cl_ord_id to create_order and edit_order endpoints #416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
claudiapacini wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(spot): add cl_ord_id to create_order and edit_order endpoints #416

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 86 additions & 11 deletions src/kraken/spot/trade.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ def create_order( # pylint: disable=too-many-branches,too-many-arguments # noqa
close_price2: str | float | None = None,
deadline: str | None = None,
userref: int | None = None,
cl_ord_id: str | None = None,
*,
truncate: bool = False,
reduce_only: bool | None = False,
Expand Down Expand Up @@ -190,6 +191,8 @@ def create_order( # pylint: disable=too-many-branches,too-many-arguments # noqa
:type validate: bool, optional
:param userref: User reference id for example to group orders
:type userref: int, optional
:param cl_ord_id: Client order id (optional)
Copy link
Owner

@btschwertfeger btschwertfeger Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The optional is given by the type declaration and not necessary at this place.

(Similar to other places; please address)

Suggested change
:param cl_ord_id: Client order id (optional)
:param cl_ord_id: Client order id

:type cl_ord_id: str, optional
:raises ValueError: If input is not correct
:return: The transaction id
:rtype: dict
Expand Down Expand Up @@ -400,6 +403,8 @@ def create_order( # pylint: disable=too-many-branches,too-many-arguments # noqa
params["deadline"] = deadline
if defined(userref):
params["userref"] = userref
if defined(cl_ord_id):
params["cl_ord_id"] = cl_ord_id
if defined(displayvol):
params["displayvol"] = str(displayvol)

Expand Down Expand Up @@ -456,6 +461,7 @@ def create_order_batch(
... "timeinforce": "GTC",
... "type": "buy",
... "userref": 16861348843,
... "cl_ord_id": "my-client-order-id-1",
... "volume": 1,
... },
... {
Expand All @@ -464,6 +470,7 @@ def create_order_batch(
... "timeinforce": "GTC",
... "type": "sell",
... "userref": 16861348843,
... "cl_ord_id": "my-client-order-id-2",
... "volume": 2,
... },
... ],
Expand Down Expand Up @@ -491,8 +498,19 @@ def create_order_batch(
extra_params=extra_params,
)

def amend_order(
def amend_order( # pylint: disable=too-many-arguments # noqa: PLR0913, PLR0917
self: Trade,
txid: str | None = None,
cl_ord_id: str | None = None,
order_qty: str | float | None = None,
display_qty: str | float | None = None,
limit_price: str | float | None = None,
trigger_price: str | float | None = None,
pair: str | None = None,
post_only: bool | None = None,
deadline: str | None = None,
nonce: int | None = None,
validate: bool = False,
*,
extra_params: dict | None = None,
) -> dict:
Expand All @@ -504,22 +522,69 @@ def amend_order(

- https://docs.kraken.com/api/docs/rest-api/amend-order

:param txid: The txid of the order to edit
:type txid: str, optional
:param cl_ord_id: Client order id (optional)
Copy link
Owner

@btschwertfeger btschwertfeger Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:param cl_ord_id: Client order id (optional)
:param cl_ord_id: Client order id

:type cl_ord_id: str, optional
:param order_qty: Set a new order quantity
:type order_qty: str | float, optional
:param display_qty: Set a new display quantity
:type display_qty: str | float, optional
:param limit_price: Set a new limit price
:type limit_price: str | float, optional
:param trigger_price: Set a new trigger price
:type trigger_price: str | float, optional
:param pair: Pair of the order, required on amends for non-crypto orders
:type pair: str, optional
:param post_only: Set post-only flag
:type post_only: bool, optional
:param deadline: RFC3339 timestamp
:type deadline: str, optional
:param nonce: Nonce used in construction of API-Sign header
:type nonce: int, optional
:param validate: Validate the order without placing on the market (default: ``False``)
:type validate: bool, optional
:raises ValueError: If both ``txid`` and ``cl_ord_id`` are not set
Copy link
Owner

@btschwertfeger btschwertfeger Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not having txid or cl_ord_id results in kraken.exceptions.KrakenInvalidArgumentsError.

Suggested change
:raises ValueError: If both ``txid`` and ``cl_ord_id`` are not set
:raises kraken.exceptions.KrakenInvalidArgumentsError: If neither ``txid`` or ``cl_ord_id`` is set

:return: Success or failure
:rtype: dict

.. code-block:: python
:linenos:
:caption: Spot Trade: Amend order

>>> from kraken.spot import Trade
>>> trade = Trade(key="api-key", secret="secret-key")
>>> trade.amend_order(
... extra_params={
... "txid": "OVM3PT-56ACO-53SM2T",
... "limit_price": "105636.9",
... }
... txid="OVM3PT-56ACO-53SM2T",
... limit_price="105636.9"
... )
"""
params: dict = {"validate": validate}
if defined(txid):
params["txid"] = txid
if defined(cl_ord_id):
params["cl_ord_id"] = cl_ord_id
if defined(order_qty):
params["order_qty"] = str(order_qty)
if defined(display_qty):
params["display_qty"] = str(display_qty)
if defined(limit_price):
params["limit_price"] = str(limit_price)
if defined(trigger_price):
params["trigger_price"] = str(trigger_price)
if defined(pair):
params["pair"] = pair
if defined(post_only):
params["post_only"] = post_only
if defined(deadline):
params["deadline"] = deadline
if defined(nonce):
params["nonce"] = nonce

return self.request( # type: ignore[return-value]
"POST",
uri="/0/private/AmendOrder",
params=params,
extra_params=extra_params,
)

Expand Down Expand Up @@ -632,21 +697,24 @@ def edit_order( # pylint: disable=too-many-arguments # noqa: PLR0913, PLR0917
@ensure_string("txid")
Copy link
Owner

@btschwertfeger btschwertfeger Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I looked up the docs and it seems like txid can be an integer as well, but cl_ord_id must be a string.

So lets swap these out:

Suggested change
@ensure_string("txid")
@ensure_string("cl_ord_id")

def cancel_order(
self: Trade,
txid: str,
txid: str | None = None,
cl_ord_id: str | None = None,
*,
extra_params: dict | None = None,
) -> dict:
"""
Cancel a specific order by ``txid``. Instead of a transaction id
a user reference id can be passed.
a user reference id or client order id can be passed.

Requires the ``Cancel/close orders`` permission in
the API key settings.

- https://docs.kraken.com/api/docs/rest-api/cancel-order

:param txid: Transaction id or comma delimited list of user reference ids to cancel.
:type txid: str
:param txid: Transaction id, client order id, or comma delimited list of user reference ids to cancel.
:type txid: str, optional
:param cl_ord_id: Client order id (optional)
:type cl_ord_id: str, optional
:return: Success or failure - Number of closed orders
:rtype: dict

Expand All @@ -659,10 +727,17 @@ def cancel_order(
>>> trade.cancel_order(txid="OAUHYR-YCVK6-P22G6P")
{ 'count': 1 }
"""
params: dict = {}
if defined(txid):
params["txid"] = txid
if defined(cl_ord_id):
params["cl_ord_id"] = cl_ord_id


return self.request( # type: ignore[return-value]
method="POST",
uri="/0/private/CancelOrder",
params={"txid": txid},
params=params,
extra_params=extra_params,
)

Expand Down Expand Up @@ -742,7 +817,7 @@ def cancel_order_batch(
extra_params: dict | None = None,
) -> dict:
"""
Cancel a a list of orders by ``txid`` or ``userref``
Cancel a list of orders by ``txid``, ``userref`` or ``cl_ord_id``.

Requires the ``Cancel/close orders`` permission in
the API key settings.
Expand Down
15 changes: 15 additions & 0 deletions src/kraken/spot/user.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,7 @@ def get_trade_balance(
def get_open_orders(
self: User,
userref: int | None = None,
cl_ord_id: str | None = None,
*,
trades: bool | None = False,
extra_params: dict | None = None,
Expand All @@ -266,6 +267,8 @@ def get_open_orders(

:param userref: Filter the results by user reference id
:type userref: int, optional
:param cl_ord_id: Filter the results by client order id
:type cl_ord_id: str, optional
:param trades: Include trades related to position or not into the
response (default: ``False``)
:type trades: bool
Expand Down Expand Up @@ -316,6 +319,8 @@ def get_open_orders(
params: dict = {"trades": trades}
if defined(userref):
params["userref"] = userref
if defined(cl_ord_id):
params["cl_ord_id"] = cl_ord_id
return self.request( # type: ignore[return-value]
method="POST",
uri="/0/private/OpenOrders",
Expand All @@ -326,6 +331,7 @@ def get_open_orders(
def get_closed_orders(
self: User,
userref: int | None = None,
cl_ord_id: str | None = None,
start: int | None = None,
end: int | None = None,
ofs: int | None = None,
Expand All @@ -344,6 +350,8 @@ def get_closed_orders(

:param userref: Filter the results by user reference id
:type userref: int, optional
:param cl_ord_id: Filter the results by client order id
:type cl_ord_id: str, optional
:param start: Unix timestamp to start the search from
:type start: int, optional
:param end: Unix timestamp to define the last result to include
Expand Down Expand Up @@ -404,6 +412,8 @@ def get_closed_orders(
params: dict = {"trades": trades, "closetime": closetime}
if defined(userref):
params["userref"] = userref
if defined(cl_ord_id):
params["cl_ord_id"] = cl_ord_id
if defined(start):
params["start"] = start
if defined(end):
Expand All @@ -423,6 +433,7 @@ def get_orders_info(
self: User,
txid: list[str] | str,
userref: int | None = None,
cl_ord_id: str | None = None,
*,
trades: bool | None = False,
consolidate_taker: bool | None = True,
Expand All @@ -441,6 +452,8 @@ def get_orders_info(
:type txid: str | list[str]
:param userref: Filter results by user reference id
:type userref: int, optional
:param cl_ord_id: Filter results by client order id
:type cl_ord_id: str, optional
:param trades: Include trades in the result or not (default: ``False``)
:type trades: bool, optional
:param consolidate_taker: Consolidate trades by individual taker trades
Expand Down Expand Up @@ -524,6 +537,8 @@ def get_orders_info(
}
if defined(userref):
params["userref"] = userref
if defined(cl_ord_id):
params["cl_ord_id"] = cl_ord_id
return self.request( # type: ignore[return-value]
method="POST",
uri="/0/private/QueryOrders",
Expand Down
19 changes: 12 additions & 7 deletions src/kraken/spot/ws_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,6 +253,7 @@ async def send_message( # noqa: C901 # pylint: disable=arguments-differ
... "order_qty": 1.0,
... "side": "buy",
... "symbol": "BTC/USD",
... "cl_ord_id": "my-client-order-id"
... },
... }
... )
Expand All @@ -275,13 +276,15 @@ async def send_message( # noqa: C901 # pylint: disable=arguments-differ
... "order_qty": 1,
... "order_type": "limit",
... "order_userref": 123456789,
... "cl_ord_id": "my-client-order-id-1",
... "side": "buy",
... },
... {
... "limit_price": 500.21,
... "order_qty": 2.12345,
... "order_type": "limit",
... "order_userref": 212345679,
... "cl_ord_id": "my-client-order-id-2",
... "side": "sell",
... "stp_type": "cancel_both",
... },
Expand All @@ -307,7 +310,8 @@ async def send_message( # noqa: C901 # pylint: disable=arguments-differ
... "orders": [
... "123456789",
... "212345679",
... "ORDER-ID123-4567890"
... "ORDER-ID123-4567890",
... "my-client-order-id"
... ],
... },
... }
Expand Down Expand Up @@ -356,25 +360,26 @@ async def send_message( # noqa: C901 # pylint: disable=arguments-differ
... message={
... "method": "cancel_order",
... "params": {
... "order_id": ["ORDER-ID123-456789", "ORDER-ID123-987654"],
... "order_id": ["ORDER-ID123-456789", "my-client-order-id"],
... },
... }
... )

**Editing orders** can be done as shown in the example below. See
https://docs.kraken.com/api/docs/websocket-v2/edit_order for more information.
**Amending orders** can be done as shown in the example below. See
https://docs.kraken.com/api/docs/websocket-v2/amend_order for more information.

.. code-block:: python
:linenos:
:caption: Spot Websocket: Cancel order(s)
:caption: Spot Websocket: Amend order

>>> await client_auth.send_message(
... message={
... "method": "edit_order",
... "method": "amend_order",
... "params": {
... "order_id": "ORDER-ID123-456789",
... "order_qty": 2.5,
... "symbol": "BTC/USD",
... "cl_ord_id": "my-client-order-id"
... },
... }
... )
Expand Down Expand Up @@ -586,7 +591,7 @@ def private_methods(self: SpotWSClient) -> list[str]:
June 2023):

- `add_order <https://docs.kraken.com/api/docs/websocket-v2/add_order>`_
- `amend_order` <https://docs.kraken.com/api/docs/websocket-v2/amend_order>`_
- `amend_order <https://docs.kraken.com/api/docs/websocket-v2/amend_order>`_
- `cancel_order <https://docs.kraken.com/api/docs/websocket-v2/cancel_order>`_
- `cancel_all <https://docs.kraken.com/api/docs/websocket-v2/cancel_all>`_
- `cancel_all_orders_after <https://docs.kraken.com/api/docs/websocket-v2/cancel_after>`_
Expand Down
Loading