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 relays the signed order for on-chain execution. That flow is separate from Intent Settler orders documented under Build.

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

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 (eight fields; see the delegation page)
Default --deadline-secs	120 seconds from signing

export AGENTSWAP_PROXY=0xYourUserProxy

agentswap trade --chain base --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 a signing preview and a spend.

--allow-trade

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

A dry run still signs

Dry-run blocks submission, not signing. The CLI signs the AgentOrder digest unconditionally — signing is not gated on the dry-run flag at any point — so a dry-run outcome contains a real, valid agent signature. Anyone who obtains that signature can relay it until the order’s deadline passes or its nonce is spent. Treat dry-run output as a live credential, not as a screenshot.

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

# Sign and relay. --min-out is REQUIRED once the trade can move funds.
agentswap --allow-trade trade --chain base --from USDC --to WETH --amount 1000000 \
  --min-out 240000000000000000 \
  --proxy 0xYourUserProxy --relay --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 relay.

export AGENTSWAP_TRADE_MAX_AMOUNT=5000000   # 5 USDC with 6 decimals

agentswap --allow-trade --max-amount "$AGENTSWAP_TRADE_MAX_AMOUNT" \
  trade --chain base --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 relay and for any non-dry-run submission. Not required for signing — see the caution above
--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 --chain base --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 paths

After signing, choose how the order reaches the chain.

Flag	Env	Behaviour
--relay	—	Submit through a gateway
--gateway-url	AGENTSWAP_GATEWAY_URL	Gateway base URL (global; used with --relay)
--self-submit	—	Return executeAsAgent calldata for you to submit; broadcasting is deferred, and pairing it with --allow-trade errors

# Gateway relay
export AGENTSWAP_GATEWAY_URL=https://gateway.example

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

# Local calldata, for submission by some other tool
agentswap trade --chain base --from USDC --to WETH --amount 1000000 \
  --proxy 0xYourUserProxy --self-submit --key-file ./agent-signer.txt

--self-submit does not broadcast in this release. It returns the executeAsAgent calldata for you to submit yourself, and combining it with --allow-trade is an error rather than a broadcast — the CLI rejects a non-dry-run self-submit outright. Relaying (--relay) is the path that actually submits, and that one does require --allow-trade.

MCP server

agentswap mcp exposes quote and trade 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

The MCP server receives four settings from the global flags — the service client, the signer, --allow-trade and --max-amount. It does not receive --gateway-url: an MCP-initiated relay goes to the service URL, not to a gateway you configured for trade. What the four settings mean in practice:

• No --allow-trade — trades through MCP stay in dry-run, same as CLI trade.
• --max-amount — enforced on MCP-initiated trades; set it before enabling --allow-trade for an autonomous agent.
• --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 but never sign. See Install for credentials and Commands for the other subcommands. The AgentOrder field list is on Agent delegation.