Commands

Every subcommand inherits the global flags (--url, -k, --json, trade safety rails, x402, and the rest). This page lists what each command is for and shows runnable examples.

The CLI is a quote-service client, not an on-chain protocol component.

Command index

Command	Purpose
`health`	Check service health
`chains`	List supported chains and DEX info
`tokens`	List supported tokens
`pools`	Inspect a specific pool
`quote`	Get a swap quote
`batch-quote`	Quotes for multiple token pairs at once
`route-explain`	Explain a saved quote route by hash
`register`	Register an API key via wallet signature
`key-info`	API key status, quota and usage
`pricing`	Quote pricing and the quota-purchase contract mapping
`buy-quota`	Print the wallet call for buying API quota
`quota-claim`	Claim purchased quota with an on-chain tx hash
`trade`	Quote, sign, and optionally relay an agent order
`mcp`	Run an MCP server over stdio

Service and discovery

agentswap health
agentswap chains
agentswap tokens --chain base
agentswap tokens                    # all chains
agentswap pools --chain base --address 0xPoolAddress

health needs no API key. chains, tokens, and pools are read-only discovery against the service.

Quotes

agentswap quote --chain base --from USDC --to WETH --amount 1000000

agentswap quote --chain base --from USDC --to WETH --amount 1000000 \
  --slippage 50 --verify

agentswap batch-quote --chain arbitrum --amount 1000000 USDC/WETH WETH/ARB

agentswap route-explain --hash 0xQuoteRouteHash

Flag	Commands	Meaning
`--chain`	`quote`, `batch-quote`, `pools`, `tokens`, `buy-quota`, `quota-claim`, `trade`	Chain name or ID understood by the service
`--from`, `--to`, `--amount`	`quote`, `trade`	Input token, output token, amount in raw units
`--slippage`	`quote`, `trade`	Slippage tolerance in basis points (optional)
`--verify`	`quote`	Ask the service to verify the route
`pairs…`	`batch-quote`	One or more `FROM/TO` pair strings after `--amount`
`--hash`	`route-explain`	Saved route hash to decode

amount is always in the input token’s smallest unit (wei for 18-decimal tokens, micro-units for USDC, and so on).

API key lifecycle

agentswap register --address 0xYourWallet --key-file ./signer-key.txt
agentswap key-info
agentswap pricing

register signs with the wallet named by --address. Pass the signing key with --key-file, not on the command line — shell history and ps expose inline secrets. On success the CLI caches the API key under $HOME/.agentswap/credentials.

key-info reports status, quota, and usage for the current key. pricing prints quote pricing and the on-chain contract mapping for purchasing quota.

Quota purchase

agentswap buy-quota --chain base --token USDC --amount 10000000
agentswap quota-claim --chain base --tx-hash 0xYourPurchaseTx

buy-quota prints the calldata or wallet instructions for an on-chain quota purchase. After the transaction confirms, quota-claim posts the chain id and the transaction hash to the service. What the service does with them is outside this interface; key-info is how you check the result.

Trade

trade quotes a swap, signs a User Proxy AgentOrder, and optionally relays it. It is the only command that moves funds on-chain. Defaults, safety rails, and MCP integration are documented on Trade.

# Dry-run: no --allow-trade, so no relay. --min-out may be omitted here.
agentswap trade --chain base --from USDC --to WETH --amount 1000000 \
  --proxy 0xYourUserProxy --key-file ./signer-key.txt

# Relay through the gateway. --allow-trade and --min-out are both required.
agentswap --allow-trade --max-amount 5000000 --gateway-url https://gateway.example \
  trade --chain base --from USDC --to WETH --amount 1000000 \
  --min-out 240000000000000000 \
  --proxy 0xYourUserProxy --relay --key-file ./signer-key.txt

Flag	Meaning
`--mode`	Signing mode; default `agent-order`
`--proxy`	User Proxy address (`AGENTSWAP_PROXY`)
`--min-out`	Minimum output in raw token units. Optional in dry-run; required once `--allow-trade` makes the trade executable
`--nonce`	Agent order nonce (optional)
`--deadline-secs`	Order deadline offset; default `120`
`--dry-run`	Force preview even when `--allow-trade` is set
`--relay`	Submit through `--gateway-url`
`--self-submit`	Return `executeAsAgent` calldata to submit yourself. Broadcasting is deferred in this release; combining it with `--allow-trade` is an error
`--key-file`	Signer key for this invocation (overrides global)

MCP server

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

mcp runs a Model Context Protocol server on stdio so an external agent can request quotes and trades. The same --allow-trade and --max-amount global flags apply — an MCP client is software, not a human at the keyboard. See Trade.

JSON output

Append -j to any command for machine-readable output:

agentswap -j chains
agentswap -j quote --chain base --from USDC --to WETH --amount 1000000