> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aultblockchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Place or Modify Order

> [!NOTE]
>
> Mainnet currently supports Spot DEX only. Perpetuals, Oracle, Margin Trading, Lending, and Vaults are **Testnet-Only**. Use Testnet endpoints and assets for those products.

Orders are signed transactions submitted to Ault Core. This API is read-only and
never holds keys, so there is no REST endpoint that places an order.

Ault Core also supports modifying a resting order in place, so a client does not have to
cancel and replace. One transaction, and no window in which the account has no order on the book.

> [!NOTE]
>
> Use an SDK version with the required message builder and EIP-712 support. The
> [SDK trading support table](https://docs.aultblockchain.com/developer-guide/ault-sdk.md#trading-support) shows which features have verified Python 0.9 methods and which need native messages. TypeScript and Python support can differ.

## Prerequisites

1. A trading account opened on Ault Core. See
   [Open Account with Fee](https://docs.aultblockchain.com/dex-api/trading/open-account.md).
2. Collateral on the Core side. See [Transfer Assets](https://docs.aultblockchain.com/dex-api/trading/transfer-assets.md).
3. Order messages carry a fee-free gas allowance, so `AULT` is needed only past it. See
   [Fee-Free Gas](https://docs.aultblockchain.com/dex-api/trading/open-account.md#fee-free-gas).
4. The market's `precision` from
   [Markets & Currencies](https://docs.aultblockchain.com/dex-api/rest/markets-and-currencies.md), and the module constraints below.

Order transactions can be signed by the account key or by an authorized agent key. See
[Trading API Key](https://docs.aultblockchain.com/dex-api/trading/api-key.md).

## Messages

| Message | Use |
| - | - |
| `/ault.clob.v1.MsgPlaceLimitOrder` | A limit order, including post-only |
| `/ault.clob.v1.MsgPlaceMarketOrder` | Payment-sized Spot market order; use an IOC limit for Perpetuals |
| `/ault.clob.v1.MsgPlaceScaleOrder` | One order distributed across a price range |
| `/ault.clob.v1.MsgModifyOrders` | Modify one or more resting orders |

The modify message is plural, so several orders can be repriced or resized in a single transaction.
Missing IDs can be returned as failed items while other modifications proceed. A different
validation error can reject the batch, and a batch with no valid modifications is rejected.
Do not list the same live order twice in one modify batch. Inspect its committed response rather
than assuming one successful transaction changed every input.

## Order Attributes

An order on the book carries these attributes:

| Attribute | Required | Description |
| - | - | - |
| Market | yes | The market the order belongs to |
| Side | yes | Buy or sell |
| Price | yes | Limit price, exactly on the native market's tick grid |
| Quantity | yes | Base quantity in the message's canonical units, meeting executable-size and product minimum checks |
| Deadline | yes | Absolute time at which the order expires |
| Post only | no | Rejects the order rather than executing if it would cross the spread |
| Client order id | no | 8-byte identifier, reported as 16 hex characters |

> [!NOTE]
>
> Every order carries a deadline. There is no open-ended resting order, so a long-lived quote needs a
> deadline far out, capped by `max_order_lifespan` below, and replacement before it expires.

Ault DEX also supports scale orders, which distribute quantity across a price range.

## Protocol Constraints

Read the native market and product parameters before building orders. The Spot REST market response
provides display metadata, but its compatibility fields do not replace these validators:

| Rule | Authoritative lookup | Validation |
| - | - | - |
| Market identity, tick grid, base maker/taker rates, halt state | Native market detail: `base_denom`, `quote_denom`, `tick_precision`, `maker_fee_rate`, `taker_fee_rate`, `halted` | Off-tick prices fail; a halt rejects new and modified orders |
| Spot minimum quote amount | `x/spot` Params: `min_order_quote_amount` | Enforced on the rounded-up canonical quote amount |
| Perpetual minimum quote amount | `x/perpetual` Params: `min_order_quote_amount` | Separate from Spot; an exact reduce-only full-position close is exempt from this notional minimum |
| Order capacity and deadline | `x/clob` Params: `max_order_per_address`, `max_order_lifespan` | Capacity and deadline are checked when the order is submitted |
| Spot market-order tolerance | `x/clob` Params: `max_order_price_ratio` | Bounds the market-order price-protection calculation below |
| Perpetual position/OI and margin constraints | Market Perpetual config and account risk | Product checks apply beyond the common order rules |

The CLOB parameter named `min_order_quote_amount` is deprecated in V3. Query the owning product's
parameter instead. [Chain Queries](https://docs.aultblockchain.com/dex-api/advanced/chain-queries.md#order-validation-and-throughput)
lists the routes. The response below illustrates the older CLOB shape; its sample numbers are not
the current Spot or Perpetual minimum:

```bash theme={null}
curl "https://main-api.cloud.aultblockchain.xyz/ault/clob/v1/params"
```

```json theme={null}
{
  "params": {
    "max_order_per_address": "1000",
    "min_order_quote_amount": "10000000000000000000",
    "max_order_lifespan": "7776000s",
    "max_order_price_ratio": "0.100000000000000000"
  }
}
```

Do not infer the enforced minimum from `limits.cost.min` or a universal 18-decimal quote asset.
Convert the product's canonical amounts using its token and market units. Minimum executable base quantity is another requirement. An order can pass the limits shown by REST and still be rejected. Use decimal arithmetic within the SDK's supported numeric range.

### Tick examples

For positive price `P` and native `tick_precision = p`, the grid step in its price decade is
`10^(floor(log10(P)) - p)`. A limit price must be an exact multiple of that step.

For a hypothetical market with `p = 2`:

| Price range | Step | Valid price | Invalid price |
| - | - | - | - |
| 0.1 to below 1 | 0.001 | 0.123 | 0.1234 |
| 1 to below 10 | 0.01 | 1.23 | 1.234 |
| 10 to below 100 | 0.1 | 12.3 | 12.34 |

Use decimal arithmetic and the native grid, including at a power-of-ten boundary. The examples
describe price validation, not a contract's quantity unit or an active market's parameters.

## Price Protection

For a Spot market order, let `L` be the local last trade and `t` the supplied `price_tolerance`, or
`max_order_price_ratio` when omitted. A supplied tolerance must be positive and no greater than
the configured maximum. The allowed interval is `[L * (1 - t), L * (1 + t)]`.

* A buy defaults to the upper bound. An explicit `worst_price` above it is clamped to that bound;
  a value below the lower bound is rejected.
* A sell defaults to the lower bound. An explicit `worst_price` below it is clamped to that bound;
  a value above the upper bound is rejected.
* The executable buy bound rounds down to a valid tick; the sell bound rounds up. No last trade
  means a Spot market order is rejected.

For example, at `L = 100` and `t = 0.02`, a buy with `worst_price = 105` is bounded at 102, while
one with `worst_price = 97` is rejected. These are hypothetical inputs, not a live tolerance.
The parameter does not impose this same band on every ordinary limit order. Perpetual immediate
execution uses an IOC limit's explicit price instead of this generic market instruction.

## Client Order IDs

A client order id is 8 bytes. Supplying one lets you find the order without waiting for the
chain-assigned id.

This API reports it as 16 hex characters, as `clientOrderId` on
[Orders](https://docs.aultblockchain.com/dex-api/rest/orders.md). The chain query takes the same 8 bytes base64-encoded, not the hex
form:

```bash theme={null}
# base64 of the 8 bytes, for example LTjm0BVEKSQ=
curl "https://main-api.cloud.aultblockchain.xyz/ault/clob/v1/orders/by-cloid/ault1.../<base64_cloid>"
```

Passing the hex form there returns `400 cloid must be 8 bytes, got 12`.

> [!WARNING]
>
> The chain prevents conflicts in its current client-ID index and also marks pending placements
> while they wait in the mempool. A client ID is not a permanent idempotency token: closed orders can
> remain in API history after the native index is removed. Use a fresh value for each logical order,
> retain its transaction hash, and reconcile an unknown submission before creating a replacement.

## Modifying

Price and quantity can change on an order that is still resting. Attributes fixed at placement, such
as side and market, require a new order. A client order id cannot be changed by a modify.

An order that has already filled, expired, or been cancelled cannot be modified.

### What Changes Depends on the Field

| Changed | Effect |
| - | - |
| Quantity only | Amends in place, keeping the order id and price-time priority; growth must pass funding and risk checks |
| Price | The order is closed and a new one is created, with a new order id |

> [!WARNING]
>
> A price change is a replace, not an edit. The order id you were tracking no longer exists, and the
> new order enters the book fresh rather than keeping the old one's place in the queue. Re-read the id
> after any price change, from `orderUpdates` on [Subscriptions](https://docs.aultblockchain.com/dex-api/websocket/subscriptions.md) or
> [Orders](https://docs.aultblockchain.com/dex-api/rest/orders.md).
>
> The client order id is carried over to the new order, so a `cloid` lookup keeps working across a
> price change. That makes `cloid` the more stable handle for anything that reprices.

### Partially Filled Orders

A partially filled order's `new_quantity` is the **new total quantity, including previous fills**.
For example, after 3 of 10 base units fill, setting it to 5 leaves 2 open; setting it to 12 leaves 9
open. `filled`, `remaining`, and
`info.remaining_deposit` on [Orders](https://docs.aultblockchain.com/dex-api/rest/orders.md) show what is left, where
`info.remaining_deposit` is the escrow still held.

Reducing the target to the filled amount or below closes the order. The native modify path also
closes the order if the remaining quantity would be one smallest base unit or less. Read `filled`
before sizing a reduction. A pure reprice without `new_quantity` retains the previous open size.

### Modify or Cancel and Replace

| | Modify | Cancel and replace |
| - | - | - |
| Transactions | One | Two |
| Window with no order on the book | None | Between the two transactions |
| Order id | Kept on a quantity change, new on a price change | New |
| Client order id | Carried over | Needs a fresh value |

Prefer modify when only price or quantity changes. Even for a reprice, where both approaches produce
a new order id, modify does it in one transaction and leaves no window in which the account has no
order on the book.

## Confirming the Result

A successful broadcast means the transaction was accepted, not that the order rested.

The chain can reject orders for off-tick prices, insufficient funds or margin, a product minimum,
halted markets, order capacity, or `cloid` conflicts. State can change between acceptance and execution. Inspect both the committed transaction code and each batch result; a successful
transaction does not mean that every requested modification succeeded.

Confirm through one of:

* The transaction result and its events.
* The `orderUpdates` channel on [Subscriptions](https://docs.aultblockchain.com/dex-api/websocket/subscriptions.md), matched on `oidHex` or
  `cloid`.
* A read of [Orders](https://docs.aultblockchain.com/dex-api/rest/orders.md), where `info.chain_status` carries the granular status.

> [!WARNING]
>
> Never treat a broadcast response as a resting order. Reconcile the actual terminal state and fills;
> an IOC order may execute without ever appearing as `open`. Follow
> [Trading Operations](https://docs.aultblockchain.com/dex-api/advanced/trading-operations.md#unknown-submission-result) if confirmation
> times out.

## Next

> [card] [Cancel Order](https://docs.aultblockchain.com/dex-api/trading/cancel-order.md)
>
> Remove a resting order and release its escrow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.