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

# Trading API Key

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

Reading market data needs no credential. Ault DEX has no API keys or secrets to issue: every read
endpoint is public, and every write is a signed chain transaction.

An **agent key** is a separate key authorized to sign supported transactions on behalf of an
account. A bot can hold it instead of the account's primary key. Its authority includes more than
order placement, so review the permissions below before granting access.

## How It Works

The account holder approves an agent key on chain. The approval carries an expiry and can be
revoked. The message account, the master that authorizes it, and the key signing a transaction
can be different identities. Query balances and orders for the actual trading account, not the
agent's address.

| Action | EVM precompile method | Cosmos message |
| - | - | - |
| Authorize an agent key | `approveAgent(bytes,string,uint64)` | `/ault.agent.v1.MsgApproveAgent` |
| Revoke an agent key | `revokeAgent(address)` | `/ault.agent.v1.MsgRevokeAgent` |

Both messages carry a fee-free gas allowance. See
[Fee-Free Gas](https://docs.aultblockchain.com/dex-api/trading/open-account.md#fee-free-gas).

Signatures, argument formats, events, and `cast` examples are documented on the
[Agent precompile](https://docs.aultblockchain.com/developer-guide/precompile/agent.md). `approveAgent` takes the agent's 33-byte
compressed secp256k1 public key, a name, and an absolute expiry in Unix seconds, where `0` uses the
default.

## What an Agent Can and Cannot Do

| Scope | Agent route |
| - | - |
| CLOB | Place, modify, and cancel supported ordinary, conditional (Testnet-Only), grouped, Scale, and TWAP instructions, subject to the product's order rules |
| Perpetuals | Deposit/withdraw collateral for the message account, set leverage and margin mode, and move position margin, subject to risk checks |
| Vault management | Agent-capable Vault messages still require the account's manager/master policy and operation permissions |
| General wallet transfers | This route does not authorize arbitrary bank sends or Core/EVM token transfers |

Perpetual collateral withdrawal returns funds to the owner's Core account; it is different from an
external transfer. Approval is not a configurable per-agent order-only permission grant. An agent
can change risk and cause trading losses, even without an arbitrary transfer capability. Not every chain message has an SDK method or UI control; consult the
[SDK support table](https://docs.aultblockchain.com/developer-guide/ault-sdk.md#trading-support).

Vault accounts have a narrower CLOB policy: their agent route does not accept TWAP, conditional,
or grouped-order messages. While redemption requests are queued for the vault, the manager cannot place or modify orders, including IOC orders that reduce a position. See [Vault permissions](https://docs.aultblockchain.com/ault-dex/vaults.md#redemptions).

Read the current limits on how many agents an account may hold and how long an approval can last:

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

```json theme={null}
{
  "params": {
    "max_agents_per_account": 10,
    "default_expiry": "2592000s",
    "max_expiry": "10368000s"
  }
}
```

The values above are an example response. Read the selected network's current agent count and
expiry parameters when creating an approval.

## Verify Agent State

```bash theme={null}
# agents registered to an account
curl "https://main-api.cloud.aultblockchain.xyz/ault/agent/v1/agents/ault1..."

# one agent's detail
curl "https://main-api.cloud.aultblockchain.xyz/ault/agent/v1/agent/ault1.../ault1..."

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

Check `is_authorized` before starting and inspect each transaction's result. Expiry or revocation
rejects later agent authorization checks. It does not cancel orders, stop TWAP schedules, or close
positions already created. Another authorized signer must perform those actions.

## Signing and Replay Protection

The wallet and agent paths use different signed envelopes:

| Path | Signed data and replay scope | Concurrent writers |
| - | - | - |
| Account wallet through the EIP-712 SDK | Domain `name = Cosmos Web3`, `version = 1.0.0`, selected EVM `chainId`, `verifyingContract = cosmos`, `salt = 0`. The typed payload contains the Cosmos `chain_id`, `account_number`, `sequence`, fee, memo, and registered message fields. | Coordinate the account sequence; independent caches can collide. After uncertainty, reconcile inclusion and refresh account state. |
| Agent transaction | Cosmos `SIGN_MODE_DIRECT`, agent extension, one supported message and one signature, `unordered = true`, signature sequence 0. The sign document uses the message account's account number and Cosmos chain ID. | Replay protection is keyed by **message account plus exact `timeout_timestamp`**, not by agent key. Different agents for the same account share this namespace. |

An agent timeout must be set, must not precede block time, and must fit the node's maximum timeout
duration. The timestamp's seconds and nanoseconds are part of its uniqueness. Coordinate a unique
timestamp generator across all writers to one message account. Python 0.9's default generator uses
millisecond clock resolution, so simultaneous submissions can collide even with separate agent keys.
An expired timestamp requires a newly signed transaction, but only after reconciling the old result.

Use the SDK's registered encoders and selected network configuration. Do not sign arbitrary JSON,
reuse an EIP-712 wallet envelope as an agent signature, or substitute the agent's account number for
the message account's. A replay rejection does not tell you whether the intended order executed; retain the transaction hash and follow [reconciliation](https://docs.aultblockchain.com/dex-api/advanced/trading-operations.md#unknown-submission-result).

## Operating Safely

> [!WARNING]
>
> A leaked agent key can trade and change supported collateral or margin settings. Revoke on
> suspicion, stop the affected service, and separately reconcile and cancel its outstanding orders.

* Give each service its own agent key, so one can be revoked without stopping the others.
* Set an expiry that matches how long the bot will actually run, rather than taking the maximum.
* Treat expiry as the safety net, not the control. Revoke explicitly on decommission.
* Never place a raw private key in a shell command or a config file that is committed.
* On rotation, authorize and verify the replacement, switch writers and coordinate replay state,
  then revoke the old key. Keep the account key available for emergency cancellation.

## Next

> [card] [Place or Modify Order](https://docs.aultblockchain.com/dex-api/trading/place-or-modify-order.md)
>
> Submit orders with the account or an agent key.


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