Agent Wallets for Automated Trading

An agent wallet is a separate signing wallet authorized to submit selected trading actions on behalf of a master account. It lets an automated strategy place and manage orders without keeping the master account’s private key online. Agent wallets are designed for delegated execution, not custody. Keep the master key offline, give each strategy or environment its own agent identity, and place deterministic validation between any AI-generated intent and the signer.

An approved agent can submit real state-changing requests. Treat its private key as a production credential, limit its lifetime and operational scope in your application, and maintain an independent revocation path.

Capabilities and limits

Property	Behavior
Supported execution	Agents can submit orders, cancellations, modifications, and TP/SL requests on behalf of the master account
Master-key isolation	The master key is used to authorize or revoke an agent, then can remain offline during normal automated trading
Anonymous slots	Up to 1 anonymous agent per master account
Named slots	Up to 3 named agents per master account
Expiry	`validUntil` is a Unix millisecond timestamp; `0` means no automatic expiry
Renewal	Re-approving an already authorized address refreshes its expiry without consuming another slot
Name replacement	Approving a named agent with an existing name replaces the previous entry for that name
Administration	Only the master account can approve or revoke agents
Inventory query	`userAgents` returns both active and expired agent records for auditing and cleanup

Recommended lifecycle

Create a dedicated wallet

Generate a new wallet for one strategy, service, or environment. Store its private key in a KMS, HSM, or secrets manager and expose only a narrow signing interface to the trading service.

from eth_account import Account

agent = Account.create()
agent_address = agent.address

# Store agent.key in a secure secret store.
# Never print it, send it to an LLM, or commit it to source control.
print(agent_address)

Approve it from the master account

Submit approveAgent, signed by the master account. Prefer a descriptive agentName and a finite validUntil for production automation.

{
  "action": {
    "type": "approveAgent",
    "agentAddress": "0xabc0000000000000000000000000000000000001",
    "agentName": "market-maker-prod",
    "validUntil": 1893456000000
  },
  "signature": {
    "r": "0x...",
    "s": "0x...",
    "v": 28
  },
  "nonce": 1782259200123
}

Verify the authorization

Query userAgents with the master account ID and confirm the returned address, name, expiry, and slot type before enabling the signer.

{
  "type": "userAgents",
  "accountId": "5"
}

Sign only validated actions

The strategy or model should produce an unsigned intent. A deterministic policy layer validates the action, applies risk controls, assigns a unique nonce, and sends the canonical payload to the agent signer.

Monitor and reconcile

Track open orders and fills through the Read API and private WebSocket channels. Stop submitting new writes when authorization is near expiry, state is stale, or reconciliation falls behind.

Rotate or revoke

Approve the replacement wallet, verify it, switch the signer, and then call revokeAgent for the old address. Maintain a separate operator-controlled kill switch that can revoke the active agent without relying on the strategy process.

Agent execution envelope

Every state-changing operation uses POST /exchange and follows the standard signing process documented in Authentication. The nonce must be unique for the agent signing address, not merely for the master account. When using the documented proxy or vault flow, include the target vaultAddress at the top level. The server verifies that the recovered signer is authorized for that target.

{
  "action": {
    "type": "order",
    "orders": [
      {
        "a": 1,
        "b": true,
        "p": "50",
        "s": "1",
        "r": false,
        "t": {
          "limit": {
            "tif": "Gtc"
          }
        }
      }
    ],
    "grouping": "na"
  },
  "signature": {
    "r": "0x...",
    "s": "0x...",
    "v": 27
  },
  "nonce": 1782259200456,
  "vaultAddress": "0xmaster000000000000000000000000000000000001"
}

Build and sign the exact action shape defined by the relevant Write API page. Do not let a model invent action fields, infer numeric types, or sign arbitrary JSON.

Separate reasoning from signing

A secure agent stack should have distinct responsibilities:

Context and planning

Reads documentation and current state, then proposes a structured action with a rationale. It has no access to private keys.

Policy engine

Enforces allowed actions, contract allowlists, precision, maximum size, leverage, reduce-only constraints, price bands, and account-level exposure limits.

Signer

Accepts only validated canonical actions, assigns or verifies a unique nonce, signs with the agent key, and returns the signature envelope.

Reconciler

Confirms orders, cancellations, fills, positions, and authorization state from server responses and WebSocket events.

The model should never call the signer with free-form text. Define a strict proposal schema such as:

{
  "intent": "place_order",
  "contractId": 1,
  "side": "buy",
  "price": "50",
  "size": "1",
  "timeInForce": "Gtc",
  "reduceOnly": false,
  "reason": "Spread and inventory conditions satisfy strategy rules"
}

Your application then maps the validated proposal to the compact API action fields.

Expiry and rotation policy

For production systems, avoid permanent authorization unless there is a strong operational reason. A practical policy is:

Use a named agent for each environment and strategy, such as maker-prod or risk-staging.
Set a finite validUntil and alert well before expiry.
Create and approve a replacement wallet before the current authorization expires.
Verify the replacement through userAgents.
Switch the signer and run a low-risk health check.
Revoke the previous address and confirm it is no longer used by any process.

Because userAgents includes expired entries, your monitoring should distinguish validUntil = 0, future timestamps, and expired timestamps rather than assuming every returned record is active.

Kill switch

A kill switch should operate independently of the model and trading strategy:

Stop the order-generation loop.
Disable or isolate the signing service.
Cancel open orders where operationally appropriate.
Revoke the agent with revokeAgent, signed by the master account.
Confirm authorization state through userAgents.
Reconcile late responses and in-flight requests before declaring the incident closed.

Revocation takes effect when it is recorded by the exchange. A request already in flight may still be accepted if it arrives before the revocation is processed, so continue reconciliation after triggering the kill switch.

Common failure modes

Symptom	Likely cause	Response
`SIGNATURE_INVALID`	Wrong private key, incorrect canonical JSON, double hashing, or invalid `v`	Rebuild the signed message exactly as documented and compare the recovered address
Duplicate or rejected nonce	The signing address reused a nonce or concurrent workers raced	Maintain one monotonic nonce allocator per agent address
Agent not authorized	Authorization expired, was revoked, or targets a different master account	Query `userAgents`, verify the target account, and re-approve only after operator review
Named quota full	Three distinct named slots are already occupied	Revoke or intentionally replace an existing named agent
Address belongs to another master	The wallet is already registered under a different master account	Generate a fresh dedicated wallet rather than sharing one agent address
State drift after submission	REST or WebSocket reconciliation is delayed or disconnected	Pause new writes, refresh account and order state, then resume only after consistency checks pass

approveAgent

Authorize an agent address, name it, and optionally set an expiry.

revokeAgent

Remove an agent authorization and free its quota slot.

userAgents

Audit active and expired agent records for a master account.

Authentication

Sign POST /exchange requests with EIP-712 over secp256k1 — Agent and typed paths.

Nonce

Generate unique replay-protection values for each signing address.

Write requests

Review the shared POST /exchange envelope and proxy fields.

Get Started

Trading Agents

Agent Wallets for Automated Trading

Capabilities and limits

Recommended lifecycle

Agent execution envelope

Separate reasoning from signing

Context and planning

Policy engine

Signer

Reconciler

Expiry and rotation policy

Kill switch

Common failure modes

approveAgent

revokeAgent

userAgents

Authentication

Nonce

Write requests

​Capabilities and limits

​Recommended lifecycle

​Agent execution envelope

​Separate reasoning from signing

Context and planning

Policy engine

Signer

Reconciler

​Expiry and rotation policy

​Kill switch

​Common failure modes

​Related API pages

approveAgent

revokeAgent

userAgents

Authentication

Nonce

Write requests

Capabilities and limits

Recommended lifecycle

Agent execution envelope

Separate reasoning from signing

Expiry and rotation policy

Kill switch

Common failure modes

Related API pages