> For the complete documentation index, see [llms.txt](https://docs.swapkit.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapkit.dev/api-reference/v3-limit-manage-and-cancel-orders.md).

# /v3/limit - Manage and cancel orders

Read a single order, paginate the orders an API key owns, and run the two-call cancel flow.

Steps 4–7 of the order flow, for orders that already exist: read one, page through many, and cancel. Steps 1–3 — quote, build and submit — are on [Place an order](https://docs.swapkit.dev/api-reference/v3-limit-place-an-order.md).

Order state follows the [status lifecycle](https://docs.swapkit.dev/api-reference/v3-limit-place-and-manage-limit-orders.md#order-status-lifecycle), and fills and terminal transitions also reach your [webhook](https://docs.swapkit.dev/api-reference/v3-limit-place-and-manage-limit-orders.md#webhooks) if one is configured.

***

## 4. Single-order detail

**Method:** `GET`\
**URL:** `https://api.swapkit.dev/v3/limit/orders/:orderId`

Returns one order, synced with the provider on every call.

### Order object

<table><thead><tr><th width="200">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>orderId</code></td><td><code>UUID string</code></td><td>UUID of the order.</td></tr><tr><td><code>orderHash</code></td><td><code>string</code></td><td>The provider's order identifier, fixed for the order's life. <strong>1inch</strong>: the <code>0x</code> digest of the signed order. <strong>Harbor</strong>: an opaque <code>0x</code> hash SwapKit assigns. <strong>NEAR Intents</strong>: the 1Click order id. The deposit's tx hash is <code>depositHash</code>, not this.</td></tr><tr><td><code>chainId</code></td><td><code>string enum</code></td><td>Sell-asset chain: a numeric string for EVM (<code>"1"</code>, <code>"42161"</code>), a slug otherwise (<code>"bitcoin"</code>, <code>"solana"</code>).</td></tr><tr><td><code>provider</code></td><td><code>enum</code></td><td>Provider that routed the order.</td></tr><tr><td><code>maker</code></td><td><code>string</code></td><td>Sell-chain address that owns the order.</td></tr><tr><td><code>receiver</code></td><td><code>string</code> or <code>null</code></td><td>Buy-chain address that receives the proceeds. <code>null</code> only on legacy orders.</td></tr><tr><td><code>sellAsset</code></td><td><code>string</code></td><td>Asset sold, e.g. <code>"ETH.ETH"</code>.</td></tr><tr><td><code>buyAsset</code></td><td><code>string</code></td><td>Asset bought, e.g. <code>"BTC.BTC"</code>.</td></tr><tr><td><code>sellAmount</code></td><td><code>decimal string</code></td><td>Amount sold. <strong>Human-readable</strong>, unlike <code>/v3/quote</code> and <code>/v3/swap</code>.</td></tr><tr><td><code>buyAmount</code></td><td><code>decimal string</code></td><td>Amount the order is resting for. Human-readable.</td></tr><tr><td><code>limitPrice</code></td><td><code>decimal string</code></td><td><code>buyAsset</code> per 1 <code>sellAsset</code>.</td></tr><tr><td><code>filledSellAmount</code>, <code>filledBuyAmount</code></td><td><code>decimal string</code></td><td><code>"0"</code> until a fill. All-or-nothing providers jump to the full amounts; partial-fill providers climb.</td></tr><tr><td><code>txHashes</code></td><td><code>TxHash[]</code></td><td>The order's on-chain transactions, oldest first; <code>[]</code> until one lands. <a href="#the-txhashes-entries">Entry shape below</a>.</td></tr><tr><td><code>cancelRequestedAt</code></td><td><code>ISO 8601 string?</code></td><td>Set while an asynchronous cancel (NEAR Intents) is pending; gone once the order is <code>CANCELLED</code>. <a href="#id-7.-submit-the-cancellation">See below</a>.</td></tr><tr><td><code>usdValueOpen</code></td><td><code>string</code> or <code>null</code></td><td>Approximate USD value of the sell side at build. <code>null</code> if no price was found.</td></tr><tr><td><code>usdValueClose</code></td><td><code>string</code> or <code>null</code></td><td>Approximate USD value of what has filled. <code>null</code> until something fills; final once the order is terminal.</td></tr><tr><td><code>status</code></td><td><code>enum</code></td><td>See the <a href="https://docs.swapkit.dev/api-reference/v3-limit-place-and-manage-limit-orders.md#order-status-lifecycle">order status lifecycle</a>.</td></tr><tr><td><code>fees</code></td><td><code>Fee[]</code></td><td>Fees on the order. <a href="#fees-breakdown">See below</a>.</td></tr><tr><td><code>depositHash</code></td><td><code>string?</code></td><td>The <code>depositTxHash</code> you submitted: as sent on NEAR Intents and 1inch native sells, lowercased on Harbor. Omitted before submit, and on signed-intent orders.</td></tr><tr><td><code>withdrawHash</code></td><td><code>string?</code></td><td><strong>Harbor only.</strong> Harbor's payout transaction, lowercase <code>0x</code>: the settlement after a fill, or the refund after a cancel or expiry. On other providers, see <code>txHashes</code>.</td></tr><tr><td><code>expiresAt</code></td><td><code>ISO 8601 string</code></td><td>When SwapKit marks the order <code>EXPIRED</code>. Harbor and NEAR Intents then refund the deposit; a 1inch native sell does <strong>not</strong> — <a href="#id-6.-cancel-an-order">cancel it</a> to release the escrow.</td></tr><tr><td><code>createdAt</code>, <code>updatedAt</code></td><td><code>ISO 8601 string</code></td><td>Server timestamps. <code>updatedAt</code> moves whenever sync writes new state.</td></tr></tbody></table>

#### The `txHashes` entries

<table><thead><tr><th width="200">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>txHash</code></td><td><code>string</code></td><td>The transaction hash.</td></tr><tr><td><code>type</code></td><td><code>enum</code></td><td><code>fill</code> or <code>cancel</code> on 1inch; <code>deposit</code>, <code>withdraw</code> or <code>refund</code> on Harbor and NEAR Intents. Open enum.</td></tr><tr><td><code>chainId</code></td><td><code>string enum</code></td><td>Chain the transaction is on. Not always the sell chain: a <code>withdraw</code> lands on the buy chain.</td></tr><tr><td><code>blockNumber</code></td><td><code>integer</code> (optional)</td><td>Block number, where the provider reports it.</td></tr></tbody></table>

### Fees breakdown

Each entry in `fees[]` has this shape. Not every provider charges every type.

<table><thead><tr><th width="200">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td><code>enum</code></td><td><code>liquidity</code> (the provider's fee), <code>affiliate</code> (yours, from your API key config), <code>service</code> (SwapKit's, currently <code>0</code>) or <code>network</code> (destination-chain gas or outbound fee).</td></tr><tr><td><code>amount</code></td><td><code>string</code></td><td>Human-readable amount.</td></tr><tr><td><code>amountBps</code></td><td><code>number</code> (optional)</td><td>The fee in bps.</td></tr><tr><td><code>asset</code></td><td><code>string</code></td><td>Asset the fee is in.</td></tr><tr><td><code>chain</code></td><td><code>string</code></td><td>Chain the fee is paid on.</td></tr><tr><td><code>protocol</code></td><td><code>enum</code></td><td>Provider charging the fee.</td></tr></tbody></table>

```json
{
  "type":      "liquidity",
  "amount":    "0.00123",
  "amountBps": 30,
  "asset":     "ETH.USDT-0x…",
  "chain":     "ETH",
  "protocol":  "HARBOR"
}
```

Fee figures are projections until settlement, and `chain` is the fee asset's own rather than the sell chain's — a USDT fee reports `"ETH"`.

<table><thead><tr><th width="150">Fee type</th><th width="210">Until the order fills</th><th width="200">After a fill</th><th>Ended without ever filling (CANCELLED, EXPIRED, FAILED)</th></tr></thead><tbody><tr><td><code>liquidity</code></td><td>Projected.</td><td>Replaced with the actual value by providers that report settlement figures. NEAR Intents settles none.</td><td><code>0</code></td></tr><tr><td><code>affiliate</code>, <code>service</code></td><td>Projected. NEAR Intents charges both on the <strong>input</strong>, so they land in the sell asset.</td><td>Still projected.</td><td><code>0</code></td></tr><tr><td><code>network</code></td><td>Projected. On NEAR Intents a delivery fee in the <strong>buy</strong> asset — it becomes a refund fee in the <strong>sell</strong> asset once the order reaches <code>CANCELLED</code> or <code>EXPIRED</code>.</td><td>Replaced with the actual value by providers that report settlement figures. NEAR Intents settles none.</td><td>Not <code>0</code>: on NEAR Intents the real refund fee, on Harbor still the estimate from build.</td></tr></tbody></table>

### Errors

<table><thead><tr><th width="80">Status</th><th width="270">Error code</th><th>Scenario</th></tr></thead><tbody><tr><td>404</td><td><code>limitOrderNotFound</code></td><td>Unknown <code>orderId</code>.</td></tr><tr><td>401</td><td><code>unauthorized</code></td><td>The order belongs to another API key, or the key isn't recognised.</td></tr><tr><td>401</td><td><code>apiKeyInvalid</code></td><td>Missing <code>x-api-key</code>.</td></tr><tr><td>400</td><td><code>validation_error</code></td><td><code>orderId</code> isn't a UUID.</td></tr></tbody></table>

***

## 5. Paginated order list

**Method:** `GET`\
**URL:** `https://api.swapkit.dev/v3/limit/orders`

Your API key's orders, newest first. It does **not** re-sync with the provider — use [`/v3/limit/orders/:orderId`](#id-4.-single-order-detail) when freshness matters.

### Query parameters

All optional, and unknown keys are ignored. Results are always limited to your API key's orders.

<table><thead><tr><th width="200">Parameter</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>sourceAddress</code></td><td><code>string</code></td><td>Filter by <code>maker</code>. EVM addresses match case-insensitively; others match exactly.</td></tr><tr><td><code>destinationAddress</code></td><td><code>string</code></td><td>Filter by <code>receiver</code>. Same matching as <code>sourceAddress</code>.</td></tr><tr><td><code>sourceChain</code></td><td><code>string enum</code></td><td>Filter by sell chain, using the order's <code>chainId</code> values (<code>"1"</code>, <code>"bitcoin"</code>, …).</td></tr><tr><td><code>destinationChain</code></td><td><code>string enum</code></td><td>Filter by buy chain. Orders created before SwapKit recorded the buy chain never match.</td></tr><tr><td><code>joinType</code></td><td><code>enum</code></td><td>How each pair of filters combines when both halves are set: <code>fullOuter</code> (default) is <strong>OR</strong>, <code>inner</code> is <strong>AND</strong>.</td></tr><tr><td><code>status</code></td><td><code>enum</code> or <code>enum[]</code></td><td>One or more <a href="https://docs.swapkit.dev/api-reference/v3-limit-place-and-manage-limit-orders.md#order-status-lifecycle">statuses</a>: <code>?status=FILLED</code>, <code>?status=PENDING&#x26;status=FILLED</code> or <code>?status=PENDING,FILLED</code>. If omitted: active orders only, or every status with <code>updatedSince</code>.</td></tr><tr><td><code>updatedSince</code></td><td><code>ISO 8601 string</code></td><td>Only orders changed at or after this time (with an offset, e.g. <code>Z</code>), oldest change first. <code>updatedAt</code> moves when the order itself changes, not on a sync that finds nothing new. It's set as we record the change, a moment before the change can be read back — milliseconds usually, but our instances' clocks differ, so go back a few minutes from the last <code>updatedAt</code> you saw rather than starting exactly at it.</td></tr><tr><td><code>cursor</code></td><td><code>string</code></td><td>The previous page's <code>nextCursor</code>, unchanged, with the same <code>updatedSince</code> and filters.</td></tr><tr><td><code>limit</code></td><td><code>int</code> (1–100)</td><td>Page size. Default 50.</td></tr></tbody></table>

There is no provider filter — filter by `sourceChain` / `destinationChain` instead.

### List response schema

<table><thead><tr><th width="200">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>orders</code></td><td><code>Order[]</code></td><td>See the <a href="#order-object">order object</a>.</td></tr><tr><td><code>nextCursor</code></td><td><code>string</code> (optional)</td><td>Present when the page is full, so the last page may be followed by an empty one. Absent after a short page.</td></tr></tbody></table>

```json
{
  "orders":     [],
  "nextCursor": "…"
}
```

To iterate: start with no cursor, then keep passing `nextCursor` until the response omits it.

{% hint style="warning" %}
**On a plain listing, terminal states are opt-in.** Without `status` you get active orders only — `PENDING`, `SUBMITTED`, `OPEN`, `PARTIAL`. Name `FILLED`, `CANCELLED`, `EXPIRED` or `FAILED` explicitly to include them.
{% endhint %}

{% hint style="warning" %}
**The chain pair is OR by default too.** `?sourceChain=1&destinationChain=bitcoin` returns every order touching Ethereum **or** Bitcoin, *not* Ethereum→Bitcoin orders — pass `joinType=inner` to require both. The two axes are then AND'd, with `status` on top.
{% endhint %}

### Examples

{% tabs %}
{% tab title="cURL" %}

```bash
# Default — active orders only (PENDING / SUBMITTED / OPEN / PARTIAL)
curl 'https://api.swapkit.dev/v3/limit/orders?limit=50' \
  -H 'x-api-key: YOUR_API_KEY'
# → { "orders": [ …50 rows… ], "nextCursor": "<opaque>" }

# Next page — pass nextCursor back unchanged (URL-encode it)
curl 'https://api.swapkit.dev/v3/limit/orders?limit=50&cursor=<nextCursor>' \
  -H 'x-api-key: YOUR_API_KEY'
# → { "orders": [ …23 rows… ] }   # no nextCursor → end of stream

# Everything that changed since a point in time, every status, oldest change first
curl 'https://api.swapkit.dev/v3/limit/orders?updatedSince=2026-11-01T00:00:00Z&limit=100' \
  -H 'x-api-key: YOUR_API_KEY'

# Filled orders from one maker address
curl 'https://api.swapkit.dev/v3/limit/orders?sourceAddress=bc1q…&status=FILLED&limit=20' \
  -H 'x-api-key: YOUR_API_KEY'

# BTC → ETH orders only (AND the chain pair)
curl 'https://api.swapkit.dev/v3/limit/orders?sourceChain=bitcoin&destinationChain=1&joinType=inner' \
  -H 'x-api-key: YOUR_API_KEY'

# maker = bc1q… OR receiver = 0xabc… (default fullOuter)
curl 'https://api.swapkit.dev/v3/limit/orders?sourceAddress=bc1q…&destinationAddress=0xabc…' \
  -H 'x-api-key: YOUR_API_KEY'

# Several statuses — repeat the key, or use the comma form
curl 'https://api.swapkit.dev/v3/limit/orders?status=PENDING,FILLED' \
  -H 'x-api-key: YOUR_API_KEY'
```

{% endtab %}
{% endtabs %}

### Errors

<table><thead><tr><th width="80">Status</th><th width="270">Error code</th><th>Scenario</th></tr></thead><tbody><tr><td>400</td><td><code>validation_error</code></td><td>A <code>limit</code> outside 1–100, an <code>updatedSince</code> without an offset, or an invalid filter value. The body lists accepted values.</td></tr><tr><td>400</td><td><code>limitOrderInvalidCursor</code></td><td><code>cursor</code> isn't a <code>nextCursor</code> from this endpoint, or came from a listing with a different <code>updatedSince</code> mode.</td></tr><tr><td>401</td><td><code>apiKeyInvalid</code></td><td>Missing <code>x-api-key</code>.</td></tr><tr><td>401</td><td><code>unauthorized</code></td><td>Unrecognised <code>x-api-key</code>.</td></tr></tbody></table>

***

## 6. Cancel an order

**Method:** `POST`\
**URL:** `https://api.swapkit.dev/v3/limit/cancel/build`

Force-syncs the order and returns what the wallet must sign or broadcast to cancel it, if anything.

<figure><picture><source srcset="https://1967725871-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl88kbsjWGhgdARxzgqCE%2Fuploads%2Fgit-blob-b6a27b5018a65de859770fefd78f3a1105664fc9%2Flimit-order-cancel-dark.svg?alt=media" media="(prefers-color-scheme: dark)"><img src="https://1967725871-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl88kbsjWGhgdARxzgqCE%2Fuploads%2Fgit-blob-b94fb5a964703a585f1ffc7bf6ea2a77db393ed4%2Flimit-order-cancel.svg?alt=media" alt="Cancelling an order. POST /v3/limit/cancel/build returns one of three things: cancelTx, which the wallet broadcasts before you send txHash; typedData, btcSignaturePreimage or messageToSign, which the wallet signs before you send signature; or all nulls, meaning nothing to sign, so you send orderId alone. Every path then calls POST /v3/limit/cancel/submit. On 1inch and Harbor the order is CANCELLED; on NEAR Intents it stays open with cancelRequestedAt set and reaches CANCELLED within minutes."></picture><figcaption><p>Always two calls. What happens between them depends on which field <code>/cancel/build</code> returns.</p></figcaption></figure>

### Request schema

<table><thead><tr><th width="200">Parameter</th><th width="150">Type</th><th width="100">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>orderId</code></td><td><code>string</code></td><td>Yes</td><td>The order to cancel.</td></tr></tbody></table>

### Cancel build response schema

Branch on which artifact is set, not on the provider. All of them `null` is a valid case: there is nothing to sign.

<table><thead><tr><th width="200">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>orderId</code></td><td><code>string</code></td><td>The order being cancelled.</td></tr><tr><td><code>cancelTx</code></td><td><code>object</code> (optional)</td><td>Cancel transaction to broadcast. <strong>1inch.</strong></td></tr><tr><td><code>typedData</code></td><td><code>object</code> (optional)</td><td>EIP-712 cancel message to sign. <strong>Harbor EVM, and NEAR Intents on EVM.</strong></td></tr><tr><td><code>btcSignaturePreimage</code></td><td><code>string</code> (optional)</td><td>String to sign as a Bitcoin Signed Message. <strong>Harbor BTC, and NEAR Intents on Bitcoin.</strong></td></tr><tr><td><code>messageToSign</code></td><td><code>object</code> (optional)</td><td><code>{ scheme, message }</code> to sign. <strong>NEAR Intents</strong>: <code>ed25519</code> on Solana, <code>tip191</code> on Tron, <code>bip137</code> on the Bitcoin family.</td></tr><tr><td><code>nextActions</code></td><td><code>object[]</code></td><td>The <code>/v3/limit/cancel/submit</code> request to send next. <strong>Follow this rather than inferring from the body.</strong></td></tr></tbody></table>

```json
{
  "orderId": "3f2b8c1e-…",
  "cancelTx": null,
  "typedData": null,
  "btcSignaturePreimage": null,
  "nextActions": []
}
```

{% hint style="danger" %}
**All null does not mean the order is cancelled.** It's NEAR Intents saying there is nothing for you to sign; nothing happens to the order until you call `/v3/limit/cancel/submit`. Drive the flow off `nextActions`, not off which fields came back.
{% endhint %}

{% tabs %}
{% tab title="cancelTx — broadcast on-chain" %}
The wallet broadcasts a cancel transaction. It invalidates only this order and leaves token allowances alone. On a 1inch native sell it targets the order's escrow, which also returns the funds.

```json
"cancelTx": {
  "from": "0x…",
  "to": "0x…",
  "data": "0x…",
  "value": "0x0",
  "chainId": 1
}
```

Send it from `cancelTx.from` — the contract checks `msg.sender`, so another sender reverts. Then post the `txHash` to `/v3/limit/cancel/submit`.
{% endtab %}

{% tab title="typedData — sign off-chain" %}
An EIP-712 cancel message; nothing goes on-chain. Harbor's uses `CancelAndWithdraw`:

```json
"typedData": {
  "primaryType": "CancelAndWithdraw",
  "types": {
    "EIP712Domain": [
      { "name": "name",    "type": "string" },
      { "name": "version", "type": "string" }
    ],
    "CancelAndWithdraw": [
      { "name": "action",    "type": "string"  },
      { "name": "chain",     "type": "string"  },
      { "name": "l1Address", "type": "string"  },
      { "name": "nonce",     "type": "uint256" },
      { "name": "expiry",    "type": "uint256" },
      { "name": "payload",   "type": "CancelAndWithdrawPayload" }
    ],
    "CancelAndWithdrawPayload": [
      { "name": "orderId", "type": "string" }
    ]
  },
  "domain": { "name": "harbor.orderbook.trading", "version": "1" },
  "message": {
    "action":    "cancel_and_withdraw",
    "chain":     "ETH",
    "l1Address": "0x…",
    "nonce":     1714500000123456,
    "expiry":    1714500600,
    "payload":   { "orderId": "trd-<uuid>" }
  }
}
```

Sign it exactly as returned. `payload.orderId` is Harbor's own order id (`trd-…`), not SwapKit's `orderId`. `nonce` and `expiry` are JSON numbers below `Number.MAX_SAFE_INTEGER`; `expiry` is in unix seconds.
{% endtab %}

{% tab title="btcSignaturePreimage — Bitcoin Signed Message" %}
The wallet signs the canonical-JSON string as a Bitcoin Signed Message (BIP-137).

```json
"btcSignaturePreimage": "{\"action\":\"cancel_and_withdraw\",\"chain\":\"BTC\",\"domain\":\"harbor.orderbook.trading\",\"expiry\":1714500600,\"l1_address\":\"bc1q…\",\"nonce\":1714500000,\"payload\":{\"orderId\":\"trd-<uuid>\"}}"
```

Submit the base64-encoded compact secp256k1 signature.

If you rebuild the preimage instead of signing it as returned, note that it uses **snake\_case** `l1_address` (EVM uses `l1Address`), and its `domain` is a **flat string** rather than EVM's `{ name, version }` object.
{% endtab %}

{% tab title="messageToSign — NEAR Intents" %}

```json
{
  "orderId": "3f2b8c1e-…",
  "cancelTx": null,
  "typedData": null,
  "btcSignaturePreimage": null,
  "messageToSign": { "scheme": "ed25519", "message": "…" },
  "nextActions": [ ]
}
```

That's a Solana sell. EVM sells return `typedData` instead, Tron uses `tip191`, and the Bitcoin family uses `bip137` — with `btcSignaturePreimage` set as well on Bitcoin itself. Sign what came back and pass it as `signature` to `/v3/limit/cancel/submit`.

Every other sell chain, and Bitcoin taproot and script (P2SH/P2WSH) addresses, return all nulls and cancel with `{ orderId }` alone. Either way the cancel is **asynchronous** — see [below](#id-7.-submit-the-cancellation).
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Sign the preimage byte-for-byte.** `btcSignaturePreimage` is canonical JSON — keys **alphabetically sorted**, **no whitespace**, applied **recursively** — and the signature is verified over exactly those bytes. Sign the string as returned rather than re-serialising the object.
{% endhint %}

### When an order can be cancelled

`/v3/limit/cancel/build` re-checks the freshly synced order, so it catches one that filled or expired while you weren't looking.

* **Harbor:** only once Harbor has seen the deposit — usually by `OPEN`, sometimes already at `SUBMITTED`. Nothing exists upstream before that.
* **NEAR Intents:** any time, even a `PENDING`, never-funded order, because `/v3/limit/build` creates the upstream order.
* **Every provider:** never once the order is terminal (`FILLED`, `CANCELLED`, `EXPIRED`, `FAILED`) — with one exception:

{% hint style="warning" %}
**A 1inch native-asset sell stays cancellable after it ends.** Its sell amount sits in an escrow contract that only a cancel releases — expiry doesn't. Cancel an `EXPIRED` or `FAILED` one, or a `FILLED` one with a residue left, to get the funds back.
{% endhint %}

<details>

<summary>Why two calls, when <code>/cancel/submit</code> could do it alone?</summary>

So one cancel flow works on every provider: call `/cancel/build`, do what the response says, call `/cancel/submit` — no branching on the provider.

On most orders the two steps are genuinely needed. 1inch's `cancelTx` is the only thing there is to broadcast. Harbor's `/cancel/build`, and NEAR Intents' on every sell chain that needs a signature, saves the nonce and expiry that `/cancel/submit` checks the signature against — skip build and submit refuses the cancel.

Only NEAR Intents' unsigned sell chains still accept a bare `/cancel/submit`, and that list shrinks as signature checks are added. Write the flow once, with both calls.

</details>

### Errors

<table><thead><tr><th width="80">Status</th><th width="270">Error code</th><th>Scenario</th></tr></thead><tbody><tr><td>409</td><td><code>limitOrderInvalidState</code></td><td>Not cancellable: terminal (see the exception above), or Harbor hasn't seen the deposit yet. The message says which.</td></tr><tr><td>400</td><td><code>limitOrderCancelFailed</code></td><td>The provider can't build a cancel for this order.</td></tr><tr><td>400</td><td><code>validation_error</code></td><td><code>orderId</code> missing or not a UUID.</td></tr><tr><td>404</td><td><code>limitOrderNotFound</code></td><td>Unknown <code>orderId</code>.</td></tr><tr><td>401</td><td><code>unauthorized</code></td><td>Another API key's order, or an unrecognised key.</td></tr><tr><td>503</td><td><code>limitOrderActionUnavailable</code></td><td>Cancelling is switched off for one of the order's chains. Can clear without a change on your side.</td></tr></tbody></table>

***

## 7. Submit the cancellation

**Method:** `POST`\
**URL:** `https://api.swapkit.dev/v3/limit/cancel/submit`

Records the cancel transaction or signature — or, when `/v3/limit/cancel/build` returned nothing, cancels the order itself. This is the call that cancels; `/cancel/build` never does.

### Request schema

<table><thead><tr><th width="200">Parameter</th><th width="150">Type</th><th width="160">Required for</th><th>Description</th></tr></thead><tbody><tr><td><code>orderId</code></td><td><code>string</code></td><td>All cancellations</td><td>The order to cancel.</td></tr><tr><td><code>txHash</code></td><td><code>string</code></td><td><code>cancelTx</code></td><td>Hash of the broadcast cancel transaction: <code>0x</code> and 64 hex characters.</td></tr><tr><td><code>signature</code></td><td><code>string</code></td><td><code>typedData</code>, <code>btcSignaturePreimage</code>, <code>messageToSign</code></td><td>The wallet's signature: <code>0x</code>-hex for EIP-712 or TIP-191, base64 for BIP-137 or ed25519.</td></tr></tbody></table>

Send whatever `/v3/limit/cancel/build` asked for; when it returned nothing, `orderId` alone.

```json
// Broadcast cancel tx
{ "orderId": "3f2b8c1e-…", "txHash": "0x…" }

// EIP-712 signature (0x-hex)
{ "orderId": "3f2b8c1e-…", "signature": "0x…" }

// BIP-137 signature (base64)
{ "orderId": "3f2b8c1e-…", "signature": "H4sIAAA…" }

// Nothing to sign — server-side cancel
{ "orderId": "3f2b8c1e-…" }
```

### Cancel submit response schema

<table><thead><tr><th width="200">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>orderId</code></td><td><code>string</code></td><td>UUID of the order.</td></tr><tr><td><code>status</code></td><td><code>enum</code></td><td>Status after the request: <code>CANCELLED</code> on 1inch and Harbor; still <code>SUBMITTED</code>, <code>OPEN</code> or <code>PARTIAL</code> on NEAR Intents. Recovering a terminal 1inch native sell's escrow leaves its status as it was.</td></tr><tr><td><code>txHash</code></td><td><code>string</code> (optional)</td><td>The cancel transaction's hash. <code>cancelTx</code> path only.</td></tr><tr><td><code>withdrawId</code></td><td><code>string</code> (optional)</td><td>Harbor's withdrawal id. Harbor only.</td></tr><tr><td><code>cancelRequestedAt</code></td><td><code>ISO 8601 string?</code></td><td>Set when an asynchronous cancel was accepted but hasn't settled.</td></tr></tbody></table>

{% tabs %}
{% tab title="1inch and Harbor — synchronous" %}

```json
{
  "orderId": "3f2b8c1e-…",
  "status":  "CANCELLED",
  "txHash":  "0x…"
}
```

{% hint style="warning" %}
**On 1inch, `CANCELLED` is recorded when you submit the hash, not when the cancel confirms.** If the cancel transaction reverts or is dropped, the order can still fill. Confirm it before telling the user, and rebroadcast or rebuild if it fails.
{% endhint %}
{% endtab %}

{% tab title="NEAR Intents — asynchronous" %}

```json
{
  "orderId":           "3f2b8c1e-…",
  "status":            "OPEN",
  "cancelRequestedAt": "2026-10-08T12:34:56.789Z"
}
```

{% hint style="warning" %}
**An asynchronous cancel does not return `CANCELLED`, and that is not a failure.** The order stays `OPEN`, `PARTIAL` or — if never funded — `SUBMITTED`, with `cancelRequestedAt` set, until the provider confirms and the refund settles: typically minutes.
{% endhint %}

Follow it by polling [`GET /v3/limit/orders/:orderId`](#id-4.-single-order-detail), which force-syncs, or over the [webhook](https://docs.swapkit.dev/api-reference/v3-limit-place-and-manage-limit-orders.md#webhooks), and design for two things:

* **Don't retry on a non-`CANCELLED` response.** `cancelRequestedAt` means the request was accepted. A retry is harmless — the first request wins and the timestamp isn't reset — but it won't make the order terminal sooner.
* **A slice can still fill meanwhile.** The order stays non-terminal so a fill that lands mid-cancel is recorded, not dropped. `filledSellAmount` / `filledBuyAmount` can move after you've asked to cancel.
  {% endtab %}
  {% endtabs %}

{% hint style="warning" %}
**Signed cancel payloads expire 10 minutes after `/v3/limit/cancel/build`** — on Harbor and NEAR Intents alike — and each new build replaces the last. Read `expiry` off the payload, sign the latest one, and have hardware-wallet flows rebuild if they're running close.
{% endhint %}

### Errors

<table><thead><tr><th width="80">Status</th><th width="270">Error code</th><th>Scenario</th></tr></thead><tbody><tr><td>409</td><td><code>limitOrderInvalidState</code></td><td>Not cancellable now: terminal or already cancelled, not yet known to the provider, an expired payload or the wrong artifact (Harbor), or a NEAR Intents phase that can't be cancelled. The message says which.</td></tr><tr><td>400</td><td><code>limitOrderCancelFailed</code></td><td>The provider rejected the cancel, or 1inch got no <code>txHash</code>. On Harbor also an upstream outage: worth one retry.</td></tr><tr><td>403</td><td><code>limitOrderCancelSignatureInvalid</code></td><td>On a NEAR Intents sell chain that needs a signature: <code>signature</code> is missing or isn't the maker's, or there's no live payload to check it against — <code>/cancel/build</code> wasn't called, or its payload expired.</td></tr><tr><td>400</td><td><code>limitOrderRejected</code></td><td>NEAR Intents refused the cancel; the message gives its reason.</td></tr><tr><td>400</td><td><code>validation_error</code></td><td><code>orderId</code> isn't a UUID, or <code>txHash</code> isn't <code>0x</code> and 64 hex characters.</td></tr><tr><td>404</td><td><code>limitOrderNotFound</code></td><td>Unknown <code>orderId</code>, or NEAR Intents has no record of the order.</td></tr><tr><td>401</td><td><code>unauthorized</code></td><td>Another API key's order, or an unrecognised key.</td></tr><tr><td>502</td><td><code>limitOrderProviderError</code></td><td>NEAR Intents failed upstream (5xx or transport). Retry; the order is unchanged.</td></tr><tr><td>503</td><td><code>limitOrderActionUnavailable</code></td><td>Cancelling is switched off for one of the order's chains.</td></tr></tbody></table>
