API reference

Cancel an order

POST

/v2/orders/{orderId}/cancel

const url = 'https://api.hyperstream.dev/v2/orders/0x35dc8d390877c71baacadb4001eea0055804cfc306f599fbfc97c1d69d64d30a/cancel';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'},
  body: '{"payload":{"nonce":"90193471235580291647163018827702615384561129844105227391950712038818471125043","rootIntentId":"0x01cb37f4c5f512f757df0452b51e3fe8daefda8dfdd7e6d298d841ac54f7d18b"},"signature":"0x60ce0a47bc64e07a5437de5fd4e6008bce46756d4d7c971710283924888b2a137a91ed09461b5848bb2b7341f5c258da3f97853e73662275f047e0c3c20882211b"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.hyperstream.dev/v2/orders/0x35dc8d390877c71baacadb4001eea0055804cfc306f599fbfc97c1d69d64d30a/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "payload": { "nonce": "90193471235580291647163018827702615384561129844105227391950712038818471125043", "rootIntentId": "0x01cb37f4c5f512f757df0452b51e3fe8daefda8dfdd7e6d298d841ac54f7d18b" }, "signature": "0x60ce0a47bc64e07a5437de5fd4e6008bce46756d4d7c971710283924888b2a137a91ed09461b5848bb2b7341f5c258da3f97853e73662275f047e0c3c20882211b" }'

Relays an EOA depositor’s signed cancel. Valid once the order is published. The filled part is paid out and the rest refunded when the hub settles.

A 200 is an acceptance, not settlement: keep polling the order. A cancel that races a fill is safe; whichever lands first settles the order. Sign a fresh nonce on every attempt.

Only ECDSA signatures recovering to the depositor or the delegate operator are accepted; ERC-1271 is not supported. A contract wallet’s owner signature does not match the depositing contract. Wait for automatic settlement at expiry or contact Khalani for help cancelling early.

Authorizations

ApiKeyAuth

Parameters

Path Parameters

orderId

required

string

/^0x[0-9a-fA-F]{64}$/

The orderId from /v2/build. Case-insensitive.

Example

0x35dc8d390877c71baacadb4001eea0055804cfc306f599fbfc97c1d69d64d30a

Request Body^required

application/json

A depositor-signed cancel, relayed by your backend.

object

payload

required

object

nonce

required

A fresh random uint256 per cancel attempt, decimal. Not the build nonce; a reused value is rejected.

string

/^\d+$/

rootIntentId

required

The order’s traces.rootIntentId.

string

/^0x[0-9a-fA-F]{64}$/

signature

required

The depositor’s EIP-712 OrderDelegateV2Cancel signature over payload.

string

/^0x[0-9a-fA-F]+$/

Example

{
  "payload": {
    "nonce": "90193471235580291647163018827702615384561129844105227391950712038818471125043",
    "rootIntentId": "0x01cb37f4c5f512f757df0452b51e3fe8daefda8dfdd7e6d298d841ac54f7d18b"
  },
  "signature": "0x60ce0a47bc64e07a5437de5fd4e6008bce46756d4d7c971710283924888b2a137a91ed09461b5848bb2b7341f5c258da3f97853e73662275f047e0c3c20882211b"
}

Responses

200

Accepted.

application/json

The cancel was accepted, not yet settled. Poll the order until delivered or delivery_failed, with a local timeout.

object

medusaSubmissionId

required

Identifier of the accepted cancel submission.

string

Example

{
  "medusaSubmissionId": "0xd51bb36fd7ad3c3e0b2c7a7f29f04de6a6e2d2a1f5b1f0e9d9f0f9a6a1f5c7e3"
}

400

Invalid body, or rootIntentId is not this order’s.

application/json

Any of:

The request failed schema validation. Carries message, not error.

object

message

required

string

Allowed value: Validation failed

name

required

string

Allowed value: ValidationException

details

required

Array<object>

object

field

required

string

message

required

string

code

required

string

Maintenance, a malformed JSON body, or an unhandled failure. Carries message, not error.

object

message

required

string

name

required

MaintenanceException (503), BadRequestException (malformed JSON) or InternalErrorException (500).

string

Example

{
  "error": "Payload rootIntentId does not match the order's published root intent"
}

401

The X-API-Key header is missing.

application/json

An error raised by the route itself.

object

error

required

string

detail

object

minSrcAmount

Smallest deposit that would quote, in source base units.

string

/^\d+$/

maxSrcAmount

Largest deposit that would quote, in source base units.

string

/^\d+$/

maxOutcomeAmount

Largest output that would quote, in destination base units.

string

/^\d+$/

missing

The deployment setting this direction needs.

string

Example

{
  "error": "X-API-Key required"
}

403

The key is unknown or past its rotation window. A 403 is always about your account: do not retry.

application/json

An error raised by the route itself.

object

error

required

string

detail

object

minSrcAmount

Smallest deposit that would quote, in source base units.

string

/^\d+$/

maxSrcAmount

Largest deposit that would quote, in source base units.

string

/^\d+$/

maxOutcomeAmount

Largest output that would quote, in destination base units.

string

/^\d+$/

missing

The deployment setting this direction needs.

string

Example

{
  "error": "Unknown or inactive integrator"
}

404

No such order, or it belongs to another integrator.

application/json

An error raised by the route itself.

object

error

required

string

detail

object

minSrcAmount

Smallest deposit that would quote, in source base units.

string

/^\d+$/

maxSrcAmount

Largest deposit that would quote, in source base units.

string

/^\d+$/

maxOutcomeAmount

Largest output that would quote, in destination base units.

string

/^\d+$/

missing

The deployment setting this direction needs.

string

Example

{
  "error": "Order not found"
}

409

Not published yet, so there is nothing to cancel.

application/json

An error raised by the route itself.

object

error

required

string

detail

object

minSrcAmount

Smallest deposit that would quote, in source base units.

string

/^\d+$/

maxSrcAmount

Largest deposit that would quote, in source base units.

string

/^\d+$/

maxOutcomeAmount

Largest output that would quote, in destination base units.

string

/^\d+$/

missing

The deployment setting this direction needs.

string

Example

{
  "error": "Order has not been published yet — wait for the deposit to clear or use stuck-deposit recovery."
}

500

Unhandled failure. Retry once, then escalate with the x-request-id response header.

application/json

Maintenance, a malformed JSON body, or an unhandled failure. Carries message, not error.

object

message

required

string

name

required

MaintenanceException (503), BadRequestException (malformed JSON) or InternalErrorException (500).

string

Example

{
  "message": "Internal Error",
  "name": "InternalErrorException"
}

502

The cancel was rejected or temporarily unavailable. Re-read the order and rejection. Fix a wrong signer or malformed signature before retrying; a fresh nonce does not fix either. For a reused nonce or temporary failure, retry with a fresh nonce only while the order is still open.

application/json

An error raised by the route itself.

object

error

required

string

detail

object

minSrcAmount

Smallest deposit that would quote, in source base units.

string

/^\d+$/

maxSrcAmount

Largest deposit that would quote, in source base units.

string

/^\d+$/

maxOutcomeAmount

Largest output that would quote, in destination base units.

string

/^\d+$/

missing

The deployment setting this direction needs.

string

Example ^generated

{
  "error": "example",
  "detail": {
    "minSrcAmount": "example",
    "maxSrcAmount": "example",
    "maxOutcomeAmount": "example",
    "missing": "example"
  }
}

Cancel an order

Authorizations

Parameters

Path Parameters

Example

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

500

Example

502

Example generated

Request Body^required

Example ^generated