Modify Order

Modify an open order — atomic cancel + replace.

curl --request PUT \
  --url https://api.darknyx.example.com/orders/{order_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cancel_signature": "<string>",
  "cancel_nonce": "<string>",
  "replacement": {
    "symbol": "<string>",
    "amount": 123,
    "price_limit": 123,
    "expiry_slot": 123,
    "order_id": "<string>",
    "note_commitment": "<string>",
    "arrival_nonce": 123,
    "trading_key": "<string>",
    "trading_key_signature": "<string>",
    "owner_commitment": "<string>",
    "note_inner_hash": "<string>",
    "merkle_root": "<string>",
    "valid_input_proof": "<string>",
    "viewing_pubkey": "<string>",
    "session_id": "<string>",
    "min_fill_size": 123,
    "collateral_amount": 123,
    "tree_id": 0
  }
}
'

import requests

url = "https://api.darknyx.example.com/orders/{order_id}"

payload = {
    "cancel_signature": "<string>",
    "cancel_nonce": "<string>",
    "replacement": {
        "symbol": "<string>",
        "amount": 123,
        "price_limit": 123,
        "expiry_slot": 123,
        "order_id": "<string>",
        "note_commitment": "<string>",
        "arrival_nonce": 123,
        "trading_key": "<string>",
        "trading_key_signature": "<string>",
        "owner_commitment": "<string>",
        "note_inner_hash": "<string>",
        "merkle_root": "<string>",
        "valid_input_proof": "<string>",
        "viewing_pubkey": "<string>",
        "session_id": "<string>",
        "min_fill_size": 123,
        "collateral_amount": 123,
        "tree_id": 0
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cancel_signature: '<string>',
    cancel_nonce: '<string>',
    replacement: {
      symbol: '<string>',
      amount: 123,
      price_limit: 123,
      expiry_slot: 123,
      order_id: '<string>',
      note_commitment: '<string>',
      arrival_nonce: 123,
      trading_key: '<string>',
      trading_key_signature: '<string>',
      owner_commitment: '<string>',
      note_inner_hash: '<string>',
      merkle_root: '<string>',
      valid_input_proof: '<string>',
      viewing_pubkey: '<string>',
      session_id: '<string>',
      min_fill_size: 123,
      collateral_amount: 123,
      tree_id: 0
    }
  })
};

fetch('https://api.darknyx.example.com/orders/{order_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.darknyx.example.com/orders/{order_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'cancel_signature' => '<string>',
    'cancel_nonce' => '<string>',
    'replacement' => [
        'symbol' => '<string>',
        'amount' => 123,
        'price_limit' => 123,
        'expiry_slot' => 123,
        'order_id' => '<string>',
        'note_commitment' => '<string>',
        'arrival_nonce' => 123,
        'trading_key' => '<string>',
        'trading_key_signature' => '<string>',
        'owner_commitment' => '<string>',
        'note_inner_hash' => '<string>',
        'merkle_root' => '<string>',
        'valid_input_proof' => '<string>',
        'viewing_pubkey' => '<string>',
        'session_id' => '<string>',
        'min_fill_size' => 123,
        'collateral_amount' => 123,
        'tree_id' => 0
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.darknyx.example.com/orders/{order_id}"

	payload := strings.NewReader("{\n  \"cancel_signature\": \"<string>\",\n  \"cancel_nonce\": \"<string>\",\n  \"replacement\": {\n    \"symbol\": \"<string>\",\n    \"amount\": 123,\n    \"price_limit\": 123,\n    \"expiry_slot\": 123,\n    \"order_id\": \"<string>\",\n    \"note_commitment\": \"<string>\",\n    \"arrival_nonce\": 123,\n    \"trading_key\": \"<string>\",\n    \"trading_key_signature\": \"<string>\",\n    \"owner_commitment\": \"<string>\",\n    \"note_inner_hash\": \"<string>\",\n    \"merkle_root\": \"<string>\",\n    \"valid_input_proof\": \"<string>\",\n    \"viewing_pubkey\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"min_fill_size\": 123,\n    \"collateral_amount\": 123,\n    \"tree_id\": 0\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.darknyx.example.com/orders/{order_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cancel_signature\": \"<string>\",\n  \"cancel_nonce\": \"<string>\",\n  \"replacement\": {\n    \"symbol\": \"<string>\",\n    \"amount\": 123,\n    \"price_limit\": 123,\n    \"expiry_slot\": 123,\n    \"order_id\": \"<string>\",\n    \"note_commitment\": \"<string>\",\n    \"arrival_nonce\": 123,\n    \"trading_key\": \"<string>\",\n    \"trading_key_signature\": \"<string>\",\n    \"owner_commitment\": \"<string>\",\n    \"note_inner_hash\": \"<string>\",\n    \"merkle_root\": \"<string>\",\n    \"valid_input_proof\": \"<string>\",\n    \"viewing_pubkey\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"min_fill_size\": 123,\n    \"collateral_amount\": 123,\n    \"tree_id\": 0\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.darknyx.example.com/orders/{order_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cancel_signature\": \"<string>\",\n  \"cancel_nonce\": \"<string>\",\n  \"replacement\": {\n    \"symbol\": \"<string>\",\n    \"amount\": 123,\n    \"price_limit\": 123,\n    \"expiry_slot\": 123,\n    \"order_id\": \"<string>\",\n    \"note_commitment\": \"<string>\",\n    \"arrival_nonce\": 123,\n    \"trading_key\": \"<string>\",\n    \"trading_key_signature\": \"<string>\",\n    \"owner_commitment\": \"<string>\",\n    \"note_inner_hash\": \"<string>\",\n    \"merkle_root\": \"<string>\",\n    \"valid_input_proof\": \"<string>\",\n    \"viewing_pubkey\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"min_fill_size\": 123,\n    \"collateral_amount\": 123,\n    \"tree_id\": 0\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "old_order_id": "<string>",
  "order_id": "<string>",
  "status": "modified",
  "arrival_slot": 123
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

TL;DRPUT /orders/{order_id} modifies a resting order as an atomic cancel + replace. The body carries a signed cancel of the old order plus a full, independently-signed replacement order. The swap happens under one lock with both preconditions checked first, so there is never a moment where you hold neither order.

Auth: Authorization: Bearer <token> and two signatures (a cancel of the old order and a full new order), both from the same trading key.

Why modify instead of cancel-then-place

Cancelling and re-placing as two separate calls leaves a gap: between the cancel landing and the new order arriving, you have no order resting, and a batch may clear in that gap. PUT /orders/{order_id} closes the gap. It verifies both sides, then applies the cancel and the replacement atomically: either the swap happens whole, or nothing changes.

Path parameters

Parameter	Type	Description
`order_id`	string	The 16-byte id (hex) of the OLD order to replace.

Request body

{
  "cancel_signature": "…",
  "cancel_nonce": "2",
  "replacement": { "… a full Place Order body …" }
}

Field	Type	Required	Description
`cancel_signature`	string	Yes	64-byte hex. Ed25519 signature over the canonical cancel body of the OLD order, which proves ownership of what is being replaced.
`cancel_nonce`	decimal string	Yes	Canonical `u64` decimal string bound into `cancel_signature`; the string form is lossless in JavaScript.
`replacement`	object	Yes	A complete, independently-signed Place Order body. It carries its own collateral note and input proof.

The trading key that signs the cancel must be the key that signs the replacement. The replacement may reuse the old order’s note and proof while that proof’s root is still in the on-chain root window, or it may point at a different note; it is a normal place-order body either way. Its session_id also scopes the embedded cancel signature to the current boot. The replacement must keep the original order’s symbol. Atomic modify is an operation inside one isolated market book; it cannot move intent between pairs. To change markets, cancel the old order and place a fresh signed order.

Reprice in place

If the replacement’s order_id equals the path order_id, the modify is a “reprice in place”: the cancel frees the id and the replacement reclaims it, so the logical order keeps its identity. If the replacement uses a new order_id, the old id is retired and a cancelled event is emitted for it on the orders stream.

Example

curl -s -X PUT "$GATEWAY/orders/$OLD_ORDER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_signature": "…",
    "cancel_nonce": "2",
    "replacement": { "symbol": "SOL-USDC", "side": "bid", "…": "…" }
  }'

Success response

{
  "old_order_id": "aa00000000000000000000000000000001",
  "order_id": "aa00000000000000000000000000000002",
  "status": "modified",
  "arrival_slot": 309482140
}

Field	Type	Description
`old_order_id`	string	The replaced order’s id.
`order_id`	string	The new order’s id (equals `old_order_id` on a reprice in place).
`status`	string	`"modified"`.
`arrival_slot`	integer	The slot stamped on the replacement order.

Atomicity guarantees

Both preconditions are checked before anything mutates:

The old order exists and is owned by the signing trading key.
The replacement’s order_id is not already booked (unless it equals the old id, the reprice-in-place case).

If either fails, the call returns an error and neither order is touched. Only when both hold does the engine cancel the old order and book the replacement under the same lock; no batch can clear between the two.

Errors

Condition	Status
Malformed fields / the replacement fails place-order verification	`400`
Missing or invalid bearer token	`401`
A signature does not verify, or the caller does not own the old order	`403`
The old order does not exist	`404`
The replacement’s `order_id` is already booked, or a nonce/session is stale	`409`

Authorizations

Authorization

string

header

required

Short-lived (≤ 1h) bearer token from POST /auth/token.

Expiry is EXACT — there is no grace period past expires_in, on REST or on the streaming transport. Refresh on a margin.

A structurally valid, unexpired token is still refused when it has been revoked (401), when the operator has invalidated the tokens the account was holding (401), or when the account is suspended (403). Suspension also blocks issuing a new one, so re-authenticating does not clear it.

Path Parameters

order_id

string

required

The OLD order's id (hex) to replace.

Body

application/json

cancel_signature

string

required

64-byte signature over the old order's canonical cancel body.

cancel_nonce

string

required

Canonical decimal u64 string.

Pattern: ^(0|[1-9][0-9]*)$

replacement

object

required

The canonical-order wire schema (darknyx-order-v5 signature domain). All 32/64/16-byte fields are hex-encoded strings; all numeric fields are JSON integers (u64). The trading-key signature covers the canonical encoding of the economic fields, viewing_pubkey, session_id, and arrival_nonce; the opening fields (owner_commitment, note_inner_hash) are pinned indirectly because the matcher re-derives note_commitment from them and rejects a mismatch.

Show child attributes

Response

Modified — old order cancelled, replacement resting.

old_order_id

string

required

order_id

string

required

Replacement id; may equal old_order_id for reprice-in-place.

status

enum<string>

required

Available options:

modified

arrival_slot

integer<uint64>

required

⌘I

Modify an open order — atomic cancel + replace.

curl --request PUT \
  --url https://api.darknyx.example.com/orders/{order_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cancel_signature": "<string>",
  "cancel_nonce": "<string>",
  "replacement": {
    "symbol": "<string>",
    "amount": 123,
    "price_limit": 123,
    "expiry_slot": 123,
    "order_id": "<string>",
    "note_commitment": "<string>",
    "arrival_nonce": 123,
    "trading_key": "<string>",
    "trading_key_signature": "<string>",
    "owner_commitment": "<string>",
    "note_inner_hash": "<string>",
    "merkle_root": "<string>",
    "valid_input_proof": "<string>",
    "viewing_pubkey": "<string>",
    "session_id": "<string>",
    "min_fill_size": 123,
    "collateral_amount": 123,
    "tree_id": 0
  }
}
'

import requests

url = "https://api.darknyx.example.com/orders/{order_id}"

payload = {
    "cancel_signature": "<string>",
    "cancel_nonce": "<string>",
    "replacement": {
        "symbol": "<string>",
        "amount": 123,
        "price_limit": 123,
        "expiry_slot": 123,
        "order_id": "<string>",
        "note_commitment": "<string>",
        "arrival_nonce": 123,
        "trading_key": "<string>",
        "trading_key_signature": "<string>",
        "owner_commitment": "<string>",
        "note_inner_hash": "<string>",
        "merkle_root": "<string>",
        "valid_input_proof": "<string>",
        "viewing_pubkey": "<string>",
        "session_id": "<string>",
        "min_fill_size": 123,
        "collateral_amount": 123,
        "tree_id": 0
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cancel_signature: '<string>',
    cancel_nonce: '<string>',
    replacement: {
      symbol: '<string>',
      amount: 123,
      price_limit: 123,
      expiry_slot: 123,
      order_id: '<string>',
      note_commitment: '<string>',
      arrival_nonce: 123,
      trading_key: '<string>',
      trading_key_signature: '<string>',
      owner_commitment: '<string>',
      note_inner_hash: '<string>',
      merkle_root: '<string>',
      valid_input_proof: '<string>',
      viewing_pubkey: '<string>',
      session_id: '<string>',
      min_fill_size: 123,
      collateral_amount: 123,
      tree_id: 0
    }
  })
};

fetch('https://api.darknyx.example.com/orders/{order_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.darknyx.example.com/orders/{order_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'cancel_signature' => '<string>',
    'cancel_nonce' => '<string>',
    'replacement' => [
        'symbol' => '<string>',
        'amount' => 123,
        'price_limit' => 123,
        'expiry_slot' => 123,
        'order_id' => '<string>',
        'note_commitment' => '<string>',
        'arrival_nonce' => 123,
        'trading_key' => '<string>',
        'trading_key_signature' => '<string>',
        'owner_commitment' => '<string>',
        'note_inner_hash' => '<string>',
        'merkle_root' => '<string>',
        'valid_input_proof' => '<string>',
        'viewing_pubkey' => '<string>',
        'session_id' => '<string>',
        'min_fill_size' => 123,
        'collateral_amount' => 123,
        'tree_id' => 0
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.darknyx.example.com/orders/{order_id}"

	payload := strings.NewReader("{\n  \"cancel_signature\": \"<string>\",\n  \"cancel_nonce\": \"<string>\",\n  \"replacement\": {\n    \"symbol\": \"<string>\",\n    \"amount\": 123,\n    \"price_limit\": 123,\n    \"expiry_slot\": 123,\n    \"order_id\": \"<string>\",\n    \"note_commitment\": \"<string>\",\n    \"arrival_nonce\": 123,\n    \"trading_key\": \"<string>\",\n    \"trading_key_signature\": \"<string>\",\n    \"owner_commitment\": \"<string>\",\n    \"note_inner_hash\": \"<string>\",\n    \"merkle_root\": \"<string>\",\n    \"valid_input_proof\": \"<string>\",\n    \"viewing_pubkey\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"min_fill_size\": 123,\n    \"collateral_amount\": 123,\n    \"tree_id\": 0\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.darknyx.example.com/orders/{order_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cancel_signature\": \"<string>\",\n  \"cancel_nonce\": \"<string>\",\n  \"replacement\": {\n    \"symbol\": \"<string>\",\n    \"amount\": 123,\n    \"price_limit\": 123,\n    \"expiry_slot\": 123,\n    \"order_id\": \"<string>\",\n    \"note_commitment\": \"<string>\",\n    \"arrival_nonce\": 123,\n    \"trading_key\": \"<string>\",\n    \"trading_key_signature\": \"<string>\",\n    \"owner_commitment\": \"<string>\",\n    \"note_inner_hash\": \"<string>\",\n    \"merkle_root\": \"<string>\",\n    \"valid_input_proof\": \"<string>\",\n    \"viewing_pubkey\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"min_fill_size\": 123,\n    \"collateral_amount\": 123,\n    \"tree_id\": 0\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.darknyx.example.com/orders/{order_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cancel_signature\": \"<string>\",\n  \"cancel_nonce\": \"<string>\",\n  \"replacement\": {\n    \"symbol\": \"<string>\",\n    \"amount\": 123,\n    \"price_limit\": 123,\n    \"expiry_slot\": 123,\n    \"order_id\": \"<string>\",\n    \"note_commitment\": \"<string>\",\n    \"arrival_nonce\": 123,\n    \"trading_key\": \"<string>\",\n    \"trading_key_signature\": \"<string>\",\n    \"owner_commitment\": \"<string>\",\n    \"note_inner_hash\": \"<string>\",\n    \"merkle_root\": \"<string>\",\n    \"valid_input_proof\": \"<string>\",\n    \"viewing_pubkey\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"min_fill_size\": 123,\n    \"collateral_amount\": 123,\n    \"tree_id\": 0\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "old_order_id": "<string>",
  "order_id": "<string>",
  "status": "modified",
  "arrival_slot": 123
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

Getting Started

System

Account

Instruments

Orders

Settlement

Tree

WebSocket

Why modify instead of cancel-then-place

Path parameters

Request body

Reprice in place

Example

Success response

Atomicity guarantees

Errors

Authorizations

Path Parameters

Body

Response

​Why modify instead of cancel-then-place

​Path parameters

​Request body

​Reprice in place

​Example

​Success response

​Atomicity guarantees

​Errors

Authorizations

Path Parameters

Body

Response

Why modify instead of cancel-then-place

Path parameters

Request body

Reprice in place

Example

Success response

Atomicity guarantees

Errors