Mainnet currently supports Spot DEX only. Perpetuals, Oracle, Margin Trading, Lending, and Vaults are Testnet-Only. Use Testnet endpoints and assets for those products.
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.
Both messages carry a fee-free gas allowance. See
Fee-Free Gas.
Signatures, argument formats, events, and
cast examples are documented on the
Agent precompile. 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
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.
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.
Read the current limits on how many agents an account may hold and how long an approval can last:
Verify Agent State
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:
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.
Operating Safely
- 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
Place or Modify Order
Submit orders with the account or an agent key.