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 and protocol signer, 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 broadcast a User Proxy agent order
intent place	Sign and announce an agent-placed open intent
intent list	List announced intents by owner or agent
intent status	Inspect an announced intent by bytes32 id
policy	Show the policy and token budgets for an agent
mcp	Run an MCP server over stdio

Service and discovery

agentswap health
agentswap chains
agentswap tokens --chainid 8453
agentswap tokens                    # all chains
agentswap pools --chainid 8453 --address 0xPoolAddress

health needs no API key. chains, tokens, and pools are read-only discovery against the service. Every command that selects a chain takes its --chainid as the numeric chain id (8453 for Base); known aliases such as base, arb, bsc, robinhood, and ethereum are also accepted where one is convenient.

Quotes

agentswap quote --chainid 8453 --from USDC --to WETH --amount 1000000

agentswap quote --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --slippage 50 --verify

agentswap batch-quote --chainid 42161 --amount 1000000 USDC/WETH WETH/ARB

agentswap route-explain --hash 0xQuoteRouteHash

Flag	Commands	Meaning
--chainid	quote, batch-quote, pools, tokens, buy-quota, quota-claim, trade, intent, policy	Chain id of the network the command runs on
--from, --to, --amount	quote, trade, intent place	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

Every monetary input on the CLI and over MCP is an unsigned decimal integer in the asset’s smallest unit: 1000000 is one USDC and 1000000000000000000 is one WETH. No input is scaled by token decimals, there is no second input format, and a value that is not digits is rejected before any quote, RPC call, signature, relay, or broadcast. Human-readable values appear only beside the raw one in output.

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 --chainid 8453 --token USDC --amount 10000000
agentswap quota-claim --chainid 8453 --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 broadcasts it. Defaults, safety rails, and MCP integration are documented on Trade.

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

# Self-submit on-chain. --allow-trade and --min-out are both required.
agentswap --allow-trade --max-amount 5000000 \
  trade --chainid 8453 --from USDC --to WETH --amount 1000000 \
  --min-out 240000000000000000 \
  --proxy 0xYourUserProxy --self-submit --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
--self-submit	Broadcast executeAsAgent on-chain transaction (requires --allow-trade; dry-run returns calldata preview)
--key-file	Signer key for this invocation (overrides global)

Intents and policy

Open intents are signed against the owner proxy and can be inspected before or after announcement. Complete workflows and options are on Agent intents.

# Dry-run preview: signs locally, verifies against contracts, does not broadcast or relay
agentswap intent place --chainid 8453 --proxy-owner 0xOwner --from USDC --to WETH \
  --amount 100000000 --start-out 40000000000000000 --end-out 35000000000000000 --dry-run --key-file ./agent-key.txt

# List announced intents by owner or agent
agentswap intent list --chainid 8453 --owner 0xOwner

# Inspect live intent status by id
agentswap intent status --chainid 8453 --id 0xIntentId

# Show policy, expiry, and token budgets for an agent
agentswap policy --chainid 8453 --owner 0xOwner --agent 0xAgent

Subcommand	Meaning
intent place	Sign and announce an intent (--relay, --self-submit, or --dry-run)
intent list	List announced intents matching --owner or --agent
intent status	Fetch live status and lens preview for an intent --id
policy	Read agent policy parameters and per-token cap/used amounts

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, inspect tokens and pools, trade, announce and query intents, and read policies. The same --allow-trade and --max-amount global flags apply. See Trade.

JSON output

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

agentswap -j chains
agentswap -j quote --chainid 8453 --from USDC --to WETH --amount 1000000
agentswap -j intent list --chainid 8453 --owner 0xOwner