Trade

agentswap trade is the CLI path for User Proxy agent orders. It requests a quote from the AgentSwap service, signs an AgentOrder EIP-712 message, and optionally broadcasts the signed order for on-chain execution. That flow is separate from Intent Settler orders documented under Build and open intents documented under Agent intents.

The signed struct, typehash, and on-chain checks are defined in Agent delegation — this page covers the CLI interface only, not the field list.

trade applies on the V6 chains: Base 8453, Arbitrum One 42161, BNB Smart Chain 56, Robinhood Chain 4663, and Arc 5042. It reads the owner’s proxy over the chain’s RPC (see RPC endpoints) and refuses an RPC that answers a different chain id than --chainid.

What trade signs

Item	Value
Default --mode	agent-order
Proxy	--proxy or AGENTSWAP_PROXY — the User Proxy the order is bound to
Order type	AgentOrder (nine fields; includes current policy generation)
EIP-712 domain	User Proxy agent-order domain
Default --deadline-secs	120 seconds from signing

export AGENTSWAP_PROXY=0xYourUserProxy

agentswap trade --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --proxy "$AGENTSWAP_PROXY" --key-file ./agent-signer.txt

--from, --to, and --amount select the swap legs. --amount is amountIn in raw token units. --slippage is optional and is sent to the quote step before signing.

Safety rails

Execution is opt-in. Two global flags define the boundary between an unsigned preview and a spend.

--allow-trade

Without --allow-trade, trade is forced to dry-run: it will not sign and will not broadcast. Pass --allow-trade on each invocation (or wrap the binary) when you intend real execution.

A dry run is unsigned

A dry run returns the quote, the unsigned AgentOrder, and its digest. Before returning, it reads the agent’s policy generation from the proxy and checks that the local digest equals the proxy’s hashAgentOrder, so it needs a reachable RPC and a deployed proxy. It never signs, never returns a signature or signed calldata, and never sends a transaction. Those checks do not prove the trade would execute.

# Preview only — no --allow-trade. --min-out may be omitted here.
agentswap trade --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --proxy 0xYourUserProxy --key-file ./agent-signer.txt

# Sign and self-submit. --min-out is REQUIRED once the trade can move funds.
agentswap --allow-trade trade --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --min-out 240000000000000000 \
  --proxy 0xYourUserProxy --self-submit --key-file ./agent-signer.txt

--min-out is mandatory whenever the trade is not a dry run. Without it the CLI refuses to sign, and the refusal is deliberate: the only other source of a floor is the quote server’s own output, and a protection floor taken from the party being protected against is not a floor. In dry-run the CLI will derive a preview floor from --slippage (default 50 bps); that derived value is for inspection, never for execution.

--dry-run on the trade subcommand forces preview even if --allow-trade is set.

--max-amount

--max-amount (AGENTSWAP_TRADE_MAX_AMOUNT) caps amountIn per trade in raw input-token units. If the requested --amount exceeds the cap, the CLI refuses to sign or submit.

export AGENTSWAP_TRADE_MAX_AMOUNT=5000000   # 5 USDC with 6 decimals

agentswap --allow-trade --max-amount "$AGENTSWAP_TRADE_MAX_AMOUNT" \
  trade --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --min-out 240000000000000000 \
  --proxy 0xYourUserProxy --key-file ./agent-signer.txt

This cap also applies to trades initiated through the MCP server (below). That is the case that matters: an MCP client is a model, not a person. Set --max-amount before handing an agent agentswap mcp with --allow-trade.

Flag	Env	Effect
--allow-trade	—	Required for any signature and any submission; without it trade returns an unsigned preview
--max-amount	AGENTSWAP_TRADE_MAX_AMOUNT	Upper bound on amountIn; enforced for CLI and MCP

Signer key

Provide the agent’s private key with --key-file (per-command or global AGENTSWAP_KEY_FILE). Do not pass keys on the command line.

agentswap --allow-trade --key-file ./agent-signer.txt \
  trade --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --min-out 240000000000000000 \
  --proxy 0xYourUserProxy

Optional --nonce sets the agent order nonce. Omit it and the CLI generates eight random bytes — it does not read the proxy’s nonce bitmap, so the value is unused only with overwhelming probability, not by verification. Pass --nonce explicitly when you are tracking nonces yourself. isAgentNonceUsed(agent, nonce) on the proxy is what actually answers the question.

Submission path

A live trade signs the AgentOrder. Without --self-submit it returns the signature and the proxy’s executeAsAgent target and calldata, and sends nothing; with --self-submit it also broadcasts that transaction.

Flag	Env	Behaviour
--self-submit	—	Broadcast executeAsAgent to the proxy from the --key-file wallet, which pays the gas (requires --allow-trade; a dry run never sends)

# Sign only: returns the signature and executeAsAgent calldata, sends nothing
agentswap --allow-trade \
  trade --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --min-out 240000000000000000 \
  --proxy 0xYourUserProxy --key-file ./agent-signer.txt

# Broadcast on-chain from local signer
agentswap --allow-trade \
  trade --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --min-out 240000000000000000 \
  --proxy 0xYourUserProxy --self-submit --key-file ./agent-signer.txt

--self-submit sends the transaction through the RPC configured for the chain, prints its hash on stderr before sending, and waits a bounded time for the receipt. Exit status 3 means the transaction was mined and reverted; 4 means it was sent but no receipt was read, so it may still be mined. Both print the hash and its status; look the hash up before sending again. The full table is on Agent intents.

MCP server

agentswap mcp exposes fourteen tools over the Model Context Protocol on stdio. Wire it into an MCP-capable host the same way as any other stdio server:

agentswap --allow-trade --max-amount 5000000 \
  --key-file ./agent-signer.txt mcp

Tool	Purpose
quote, batch_quote	Swap quotes from the service
tokens, pools	Token and pool inspection
trade	Preview an unsigned AgentOrder, or sign a live trade; dry_run defaults to true
intent_place	Preview an unsigned intent, or sign and announce with exactly one of relay, self_submit, or broadcast
intent_list	List intents; requires owner or agent
intent_status	Inspect intent state by bytes32 id
policy	Read an agent’s permissions, generation, and token budgets
portfolio	Discover ERC-20 holdings and optionally quote small balances
grant_link	Build an advisory grant URL; signs nothing
batch_sell_plan	Create an unsigned batch-sell review request
batch_sell_run	Run a confirmed batch-sell request
batch_sell_report	Report a confirmed batch-sell request for its owner

The last four are described under Holdings and batch sales. trade, intent_place, and batch_sell_run are the only tools that can sign. With self_submit, the MCP receipt wait ends before common MCP request timeouts; a reverted transaction, or one sent whose receipt was not read, is a tool error that carries the full outcome.

The MCP server receives settings from global flags:

• No --allow-trade — trade, intent_place, and batch_sell_run stay unsigned previews.
• --max-amount — enforced on trade, intent_place, and batch_sell_run; bounds any client cap.
• --key-file / AGENTSWAP_KEY_FILE — agent signer for order signatures.
• -k / SR_API_KEY — service authentication for quotes.

A conservative setup for an agent host:

export AGENTSWAP_TRADE_MAX_AMOUNT=1000000
export AGENTSWAP_KEY_FILE=/path/to/agent-signer.txt

agentswap --allow-trade --max-amount "$AGENTSWAP_TRADE_MAX_AMOUNT" mcp

Omit --allow-trade when the agent should quote and inspect but never move funds. See Install for credentials and Commands for the subcommand index. The AgentOrder field list is on Agent delegation.