> ## 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.

# Chain Queries

> [!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.

If the Ault DEX API is delayed or unavailable, most of the same market, order, balance, and fee
data can be read directly from the chain. This page lists those paths.

Hosts are the Cosmos REST and EVM JSON-RPC endpoints published on
[Mainnet](https://docs.aultblockchain.com/network-information/mainnet.md) and [Testnet](https://docs.aultblockchain.com/network-information/testnet.md). Examples use
mainnet.

## What Has a Chain Fallback

| Available on chain | Not available on chain |
| - | - |
| Market list and detail, token registry, currency metadata | Trade and fill history |
| Resting orders, including lookup by client order id | Ticker and 24-hour statistics |
| Fee and allowance queries | Price-level aggregated order book |
| Balances | |
| Account and agent state | |
| Node sync status | |

The right column requires indexing the chain's event stream, which is what this API's indexer does.
There is no chain-level substitute short of replaying the events yourself.

## Field Conventions

Chain queries differ from this API in three ways that break clients if missed:

* `market_id`, `order_id`, and `cloid` are raw bytes on the wire, and the REST gateway encodes them
  as base64, so they appear as opaque blobs. This API returns `market_id` as hex.
* Prices and quantities are decimal strings, not JSON numbers.
* List endpoints use Cosmos-standard `pagination.key`, `pagination.limit`, and `pagination.offset`,
  and return one page per call.

## Markets

Module `x/market`.

```bash theme={null}
# every trading pair
curl "https://main-api.cloud.aultblockchain.xyz/ault/market/v1/markets"

# one market, including maker_fee_rate and taker_fee_rate
curl "https://main-api.cloud.aultblockchain.xyz/ault/market/v1/markets/<base64_market_id>"

# default and maximum fee rates, allowed quote denoms
curl "https://main-api.cloud.aultblockchain.xyz/ault/market/v1/params"
```

Fallback for `GET /api/v1/markets` and `GET /api/v1/fees`.

`market_id` here is the same binary identifier this API returns as hex on
[Market Data](https://docs.aultblockchain.com/dex-api/rest/market-data.md), base64-encoded instead.

## Tokens and Currencies

Modules `x/tokenregistry` and `x/bank`.

```bash theme={null}
# every registered token pair
curl "https://main-api.cloud.aultblockchain.xyz/ault/tokenregistry/v1/token_pairs"

# one token, by ERC20 address or erc20:0x... denom
curl "https://main-api.cloud.aultblockchain.xyz/ault/tokenregistry/v1/token_pair/0x..."

# per-token EVM/Core transfer limit and remaining capacity
curl "https://main-api.cloud.aultblockchain.xyz/ault/tokenregistry/v1/transfer_limit/0x..."

# symbol, decimals via denom_units[].exponent, display denom
curl "https://main-api.cloud.aultblockchain.xyz/cosmos/bank/v1beta1/denoms_metadata"
```

Fallback for `GET /api/v1/currencies`.

## Fees

Module `x/accountx`.

```bash theme={null}
# minimum-gas settings that make certain order transactions fee-free
curl "https://main-api.cloud.aultblockchain.xyz/ault/accountx/v1/fee_free_gas_limits"
```

Per-market trading fee rates come from the market detail response as `maker_fee_rate` and
`taker_fee_rate`, and defaults from market module params. The `x/clob` params do not carry fee rates.

For account-specific discounts, query `/ault/accountx/v1/fee_tier/{address}` and
`/ault/reward/v1/fee_tier_discounts`. The fee-tier schedule's `discounts` array starts with tier 1
at index 0. Base market rates alone are not the account's final fee quote; referral and approved
builder settings can also affect the order's fee information.

## Orders and Order Book

Module `x/clob`. The chain exposes resting orders, not price-level depth.

```bash theme={null}
# active orders for a market
curl "https://main-api.cloud.aultblockchain.xyz/ault/clob/v1/orders?market_id=<base64_market_id>"

# one order by id
curl "https://main-api.cloud.aultblockchain.xyz/ault/clob/v1/orders/<base64_order_id>"

# one order by client order id
curl "https://main-api.cloud.aultblockchain.xyz/ault/clob/v1/orders/by-cloid/ault1.../<base64_cloid>"

# order constraints: max orders per address, min quote amount, max lifespan, max price ratio
curl "https://main-api.cloud.aultblockchain.xyz/ault/clob/v1/params"
```

Each order carries its id, orderer, `market_id`, `is_buy`, price, `tick`, quantity,
`open_quantity`, `remaining_deposit`, deadline, `post_only`, fee info, and cloid.

Fallback for `GET /api/v1/orders`, and a partial fallback for `GET /api/v1/orderbook/{symbol}`. This
API returns price-level aggregates, which the chain does not. Reproducing the depth book means
aggregating these resting orders yourself.

> [!NOTE]
>
> Swagger marks `market_id` as optional on the orders endpoint, but the endpoint returns
> `400 {"message":"market_id is required"}` without it. Always include it.

### TWAP Parents

**Testnet-Only.** Use `https://test-api.cloud.aultblockchain.xyz` for these native queries.

Native `Order` and `OrderByCloid` queries can return a `twap` result containing the parent `order`
and `schedule`. `GET /ault/clob/v1/twap-orders` lists active parents and accepts `orderer` plus
standard pagination. Use the account actually holding the parent when filtering.

After [cancelling a parent](https://docs.aultblockchain.com/dex-api/trading/cancel-order.md#cancelling-a-twap-schedule), verify its
committed close result and absence from active parents, then reconcile any already-created slices.
Checking the ordinary resting-order list alone does not confirm that a TWAP schedule has stopped.

## Order Validation and Throughput

| Query | Fields to inspect |
| - | - |
| `/ault/market/v1/markets/{market_id}` | `tick_precision`, `base_denom`, `quote_denom`, maker/taker base rates, `halted`, product `config` |
| `/ault/spot/v1/params` | Spot `min_order_quote_amount` |
| `/ault/perpetual/v1/params` | Perpetual `min_order_quote_amount`; separate from Spot (Testnet-Only) |
| `/ault/clob/v1/params` | `max_order_per_address`, `max_order_lifespan`, `max_order_price_ratio`; the legacy minimum field is deprecated |
| `/ault/ratelimit/v1/params` | `rate_limit_configs`: message type and base per-block `limit` |
| `/ault/accountx/v1/trading_tier/{address}` | Account `trading_tier`, separate from its fee tier |
| `/ault/reward/v1/trading_tier_benefits` | `benefits` schedule, including `rate_limit_multiplier`; index 0 corresponds to tier 1 |

Use the field encodings above with the selected network's Cosmos REST endpoint. The CLOB grid
is defined by native `tick_precision`, not the Spot API's fixed decimal compatibility field. See
[Protocol Constraints](https://docs.aultblockchain.com/dex-api/trading/place-or-modify-order.md#protocol-constraints) for preflight
rules and [Trading Operations](https://docs.aultblockchain.com/dex-api/advanced/trading-operations.md#limits-and-backoff) for the
separate read, transaction, gas, and order-capacity budgets.

## Perpetual Account and Price Queries

**Testnet-Only.** Use `https://test-api.cloud.aultblockchain.xyz` for these native queries.

These are native chain query names and fields, separate from the DEX API's Spot REST and WebSocket routes.
They require a node implementing the corresponding Perpetual module. Existing byte/base64
conventions apply; an empty `market_id` selects cross for account queries, while a market ID selects
its isolated account.

| Native query | Operational fields |
| - | - |
| `CollateralDenom` | `collateral_denom`, the deposited collateral token identity |
| `Params` | `transfer_notional_floor` and module constraints |
| Market detail with Perpetual configuration | `margin_tiers`, `isolated_only`, position/OI caps, `index_feed_id`, `external_perpetual_feed_id`, `oracle_max_age_seconds`, `mark_price_max_change_rate`, funding parameters, `impact_notional` |
| `Account`, `Position` | Account collateral; position `net_base`, `net_quote`, `last_funding_index` |
| `AccountRisk` | `equity`, `initial_margin`, `maintenance_margin`, `order_margin`, `notional`, `available_margin`, `liquidatable` |
| `Prices` | Effective `index_price`; closed-session `internal_price`; `mark_price` state with `last_update_time`, basis/local EMA values and weights |
| `ImpactPrices` | `bid`, `ask`, `last_update_time`; zero side means insufficient accepted depth |
| `Funding` | `cumulative_funding_index`, `premium_sum`, `premium_count`, `window_start_time` |

`Prices` can omit an unavailable effective index while still returning a stored mark. Price-state
and funding timestamps above use Unix seconds; they are not interchangeable with DEX API
millisecond timestamps. EMA stored values require division by their corresponding weights.
`AccountRisk.available_margin` is not the maximum withdrawal, and a false ordinary-liquidation flag does not mean a negative-equity account is safe, because ADL handles those accounts.

For calculation rules, see [Perpetuals](https://docs.aultblockchain.com/ault-dex/perpetuals.md#sizing-reference) and
[Oracle](https://docs.aultblockchain.com/ault-dex/oracle.md#price-and-funding-formulas). For metal market units, see [Perpetuals](https://docs.aultblockchain.com/ault-dex/perpetuals.md#metal-market-units).

## Trade and Fill Data

There is no native chain query for historical CLOB fills or tickers. Collect native fill events
from Cosmos RPC and use a decoder compatible with the chain version.

The native `order_filled` event emits maker updates during matching and an aggregate taker update
after that taker's matching run. Its accumulated quantities, payments, and fees are not a universal
one-event-per-match trade feed. Do not sum raw cumulative fields as independent fills. DEX API fill records are built by its indexer and can differ from these raw events.

```bash theme={null}
# all events for a block, including fill events
curl "https://main-rpc.cloud.aultblockchain.xyz/block_results?height=<height>"
```

> [!WARNING]
>
> `tx_search` filtering by event key, such as `message.sender`, returns nothing on the public RPC even
> for senders that provably emitted it. Only `tx.hash` and `tx.height` queries are dependable, since
> event-key indexing depends on node configuration. To follow one account, walk blocks by height
> instead.

For contract and precompile actions, EVM JSON-RPC also exposes logs. Those logs are a separate data source and do not replace native CLOB fill events:

```bash theme={null}
curl -X POST "https://main-json-rpc.cloud.aultblockchain.xyz" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"address":"0x...","fromBlock":"latest","toBlock":"latest"}],"id":1}'
```

`eth_getLogs` is functional and public. See the
[JSON-RPC compatibility matrix](https://docs.aultblockchain.com/developer-guide/json-rpc-api.md).

Historical trades and 24-hour statistics are exactly what this API's indexer computes from these
events. See [Market Data](https://docs.aultblockchain.com/dex-api/rest/market-data.md).

## Balances

Module `x/bank`, plus EVM JSON-RPC for the EVM side.

```bash theme={null}
# all Core-side balances
curl "https://main-api.cloud.aultblockchain.xyz/cosmos/bank/v1beta1/balances/ault1..."

# excludes vesting and otherwise locked coins
curl "https://main-api.cloud.aultblockchain.xyz/cosmos/bank/v1beta1/spendable_balances/ault1..."

# one denom
curl "https://main-api.cloud.aultblockchain.xyz/cosmos/bank/v1beta1/balances/ault1.../by_denom?denom=aault"
```

Native EVM balance, and an ERC20 balance through `balanceOf(address)`:

```bash theme={null}
curl -X POST "https://main-json-rpc.cloud.aultblockchain.xyz" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x...","latest"],"id":1}'
```

Fallback for `GET /api/v1/balance`. Moving assets between EVM and Core is a transaction, not a query.
See [Transfer Assets](https://docs.aultblockchain.com/dex-api/trading/transfer-assets.md).

> [!NOTE]
>
> For ordinary Spot orders, payment escrow moves from the account to the market's escrow address,
> so it is absent from both bank balance endpoints. The endpoints differ on vesting and other locked
> coins. Neither bank query substitutes for Perpetual equity or Lending-backed Margin collateral
> and debt, which follow separate product accounting.

## Account and Agent State

Modules `x/accountx` and `x/agent`.

```bash theme={null}
# is a trading account opened
curl "https://main-api.cloud.aultblockchain.xyz/ault/accountx/v1/is_opened/ault1..."

# account feature flags
curl "https://main-api.cloud.aultblockchain.xyz/ault/accountx/v1/label/ault1..."

# agents registered to an account
curl "https://main-api.cloud.aultblockchain.xyz/ault/agent/v1/agents/ault1..."

# whether an agent key is currently valid
curl "https://main-api.cloud.aultblockchain.xyz/ault/agent/v1/is_authorized/ault1.../ault1..."
```

See [Open Account with Fee](https://docs.aultblockchain.com/dex-api/trading/open-account.md) and
[Trading API Key](https://docs.aultblockchain.com/dex-api/trading/api-key.md).

## Node and Chain Status

```bash theme={null}
# chain height and sync
curl "https://main-rpc.cloud.aultblockchain.xyz/status"

# whether the node is still catching up
curl "https://main-api.cloud.aultblockchain.xyz/cosmos/base/tendermint/v1beta1/syncing"

# latest block
curl "https://main-api.cloud.aultblockchain.xyz/cosmos/base/tendermint/v1beta1/blocks/latest"
```

These report a chain node's height and sync state. Compare them with the API's
`GET /api/v1/status` to detect indexing lag before trading.

From the EVM side, `eth_blockNumber`, `eth_chainId`, and `eth_syncing` take the same shape:

```bash theme={null}
curl -X POST "https://main-json-rpc.cloud.aultblockchain.xyz" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

## Real-Time Subscriptions

The chain-native alternative to the [WebSocket API](https://docs.aultblockchain.com/dex-api/websocket/overview.md). Examples use
`node -e` on Node 22 or later, which connects, prints for five seconds, then exits.

New blocks, which include fills:

```bash theme={null}
node -e "const ws=new WebSocket('wss://main-rpc.cloud.aultblockchain.xyz/websocket');ws.onopen=()=>ws.send(JSON.stringify({jsonrpc:'2.0',method:'subscribe',params:{query:\"tm.event='NewBlock'\"},id:1}));ws.onmessage=e=>console.log(e.data);setTimeout(()=>process.exit(0),5000);"
```

The first message is an empty acknowledgement. Each one after that is a block, with fills under
`result.data.value.result_finalize_block.tx_results[i].events`.

Filtering by sender with `tm.event='Tx' AND message.sender='ault1...'` depends on the same
event-key indexing and should not be relied on. Subscribe to blocks and filter client-side.

EVM block headers and logs, over `eth_subscribe`:

```bash theme={null}
node -e "const ws=new WebSocket('wss://main-json-ws.cloud.aultblockchain.xyz');ws.onopen=()=>ws.send(JSON.stringify({jsonrpc:'2.0',id:1,method:'eth_subscribe',params:['newHeads']}));ws.onmessage=e=>console.log(e.data);setTimeout(()=>process.exit(0),5000);"
```

The acknowledgement returns a subscription id. Later messages are `eth_subscription` notifications
with the header or log under `params.result`.


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