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
`portfolio`	Discover ERC-20 holdings and optionally quote small balances
`grant-link`	Build an advisory grant URL for the owner to review
`batch-sell plan`	Create an unsigned batch-sale review request
`batch-sell run`	Execute a batch sale the owner has confirmed
`batch-sell report`	Report a confirmed batch sale for its owner
`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, arc, 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`, `portfolio`, `grant-link`, `batch-sell plan`	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 quoted output; prints the verified output and deviation
`--taker`	`quote`, `batch-quote`	The owner’s V6 proxy; required for BNB Smart Chain meta-aggregator quotes
`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 wallet call for an on-chain quota purchase on Base or Arbitrum One; other chains are refused. --token USDC buys quota directly; any other token is quoted to USDC first and bought through the token path. 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`	Return the unsigned preview even when `--allow-trade` is set
`--self-submit`	Broadcast `executeAsAgent` from the `--key-file` wallet (requires `--allow-trade`; a dry run never sends)
`--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: unsigned; checks hashes against the contracts, does not relay or send
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 `--broadcast`), or preview it unsigned with `--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

Holdings and batch sales

portfolio, grant-link, and batch-sell apply on Base 8453, Arbitrum One 42161, BNB Smart Chain 56, and Robinhood Chain 4663. Batch-sell sells nothing on a chain without prices, Robinhood Chain included.

`portfolio`

agentswap portfolio --chainid 8453 --owner 0xOwner
agentswap portfolio --chainid 8453 --owner 0xOwner --max-usd 5 --quote-token USDC

Read-only: discovers the owner’s ERC-20 holdings, reads balances, and values them. --token <address>, repeatable, adds an ERC-20 address to read; discovery may be incomplete. --max-usd (a USD decimal) quotes every priced balance below it, and every unpriced token, in full to --quote-token (default USDC). Nothing is signed.

`grant-link`

# One-shot: omitted caps take current balances; weekly epoch, expiry in 24 hours
agentswap grant-link --chainid 8453 --owner 0xOwner --agent 0xAgent \
  --token 0xSpendToken --receive USDC --one-shot

# Recurring: every spend token carries an explicit raw cap
agentswap grant-link --chainid 8453 --owner 0xOwner --agent 0xAgent \
  --token 0xSpendToken:5000000 --receive USDC --epoch 1d --expiry 30d

grant-link prints an advisory URL for the owner to review and approve in the app; it signs no transaction. --token is a spend address, optionally followed by :<raw cap>. The CLI refuses native tokens, duplicates, more than 19 spend tokens plus the receive token, a grant with no positive cap, and a rendered cap longer than 32 characters. --epoch takes 1h, 1d, or 1w; --expiry takes 7d, 30d, 90d, or a future UTC timestamp ending in Z. When the agent already holds a live policy, the link is refused unless --replace is passed, and the new link replaces that policy’s entire token basket.

`batch-sell`

A batch sale has three steps: the agent plans a request, the owner confirms it on the review page, and the agent runs and then reports it.

# 1. Plan: one unsigned review request; prints its URL for the owner
agentswap batch-sell plan --chainid 8453 --owner 0xOwner --agent 0xAgent \
  --name "Portfolio agent" --receive USDC --max-loss-bps 300

# 2. Run, after the owner confirms
agentswap --allow-trade --max-amount 5000000 --key-file ./agent-signer.txt \
  batch-sell run --request REQUEST_ID_OR_URL

# 3. Report to the owner, after the run and again after open intents close
agentswap batch-sell report --request REQUEST_ID_OR_URL

Step	Requirements and limits
`plan`	`--max-loss-bps` (1 to 5000) is the requested discount from independent market value; the owner confirms or lowers it. `--receive` needs a floor-eligible independent price. `--name` (at most 32 characters) and `--note` (at most 140) appear on the review page; control and invisible characters are refused. `--min-usd`, `--max-usd`, `--token`, and `--exclude` select holdings; caps are the exact balances; at most 100 tokens including the receive token. Signs nothing.
`run`	The request must be confirmed, `--key-file` is required, and its wallet must be the request’s agent. The proxy’s live policy generation must equal the confirmed one. Without `--allow-trade` the run returns unsigned previews; `--max-amount` bounds it. `--via intent` (default) places relayed intents; `--via market` self-submits trades, with gas paid by the agent wallet.
`report`	Needs no key. Per token: status (`sold`, `partly_sold`, `open`, `expired`, `not_placed`, `unsold`, or `unknown`), amount sold, proceeds, and discount versus market; then totals. Each listed intent’s status is read from the lens. When the intent index or the lens does not answer, a token the grant budget does not show fully sold is `unknown`, `open_intents` is `null`, and the next step is to run the report again.

In intent mode, --start-premium-bps (0 to 1000, default 100) starts each intent that far above independent market value; its price falls linearly to the owner-confirmed discount floor at expiry. --wait <secs> bounds intent status polling and is available only in intent mode.

MCP server

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

mcp runs a Model Context Protocol server on stdio with fourteen tools, so an external agent can request quotes, inspect tokens and pools, trade, announce and query intents, read policies, and plan, run and report batch sales. 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