Install

The agentswap CLI is a client for the AgentSwap quote service, User Proxy agent orders, and open intents. It is not part of either on-chain protocol — the Intent Settler and the User Proxy have their own documentation on this site.

The CLI includes intent place, intent list, intent status, policy, on-chain --self-submit, the MCP server, and x402 support.

Source and licence: agentswapco/agentswap-cli, MIT.

Install

A prebuilt binary is available for Linux and macOS:

curl -fsSL https://agentswap.co/install.sh | sh
agentswap --version

The script downloads agentswap-v<version>-<target>.tar.gz and SHA256SUMS from the GitHub Release of the version tag, verifies the checksum, and installs the agentswap binary into $HOME/.local/bin without sudo.

Setting	Environment variable	Default
Version	`AGENTSWAP_VERSION`	latest
Install directory	`AGENTSWAP_INSTALL_DIR`	`$HOME/.local/bin`

Supported platforms:

OS	Architectures
Linux	`x86_64`, `aarch64`
macOS	`x86_64`, `arm64`

On any other platform, the script prints the fallback method: cargo install agentswap.

# Pin a version instead of following latest
curl -fsSL https://agentswap.co/install.sh | AGENTSWAP_VERSION=0.4.0 sh

The binary name is agentswap. Run agentswap --help for the full flag list.

Service endpoint

By default the CLI talks to https://api.agentswap.co. Override with a flag or environment variable:

Setting	Flag	Environment variable	Default
Service URL	`--url`	`AGENTSWAP_URL`	`https://api.agentswap.co`

# Point one invocation at a different service
agentswap --url http://localhost:8080 health

# Or for the whole shell
export AGENTSWAP_URL=http://localhost:8080
agentswap health

An override is only useful against a service you run yourself; the default is the one to use.

A quick connectivity check:

agentswap health

API key credentials

Authenticated commands need an API key. Supply it on each invocation, or register once and let the CLI cache it.

Setting	Flag	Environment variable	Default
API key	`-k`, `--key`	`SR_API_KEY`	cached key (see below)
Raw JSON output	`-j`, `--json`	—	off (formatted tables)

Cached key. After register succeeds, the CLI writes the key to $HOME/.agentswap/credentials (mode 0600 on Unix). Later commands read that file automatically. Whitespace is trimmed; an empty file is ignored. If HOME is unset, there is no credentials path and you must pass -k or SR_API_KEY every time.

# Use an explicit key for one command
agentswap -k "$SR_API_KEY" key-info

# Or rely on the cached file after register
agentswap key-info

Register and the private key

register proves wallet control with a signature and stores the returned API key. It accepts --private-key inline or --key-file:

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

Use --key-file. A private key passed on the command line is recorded in shell history and visible in process listings (ps). A file with restrictive permissions avoids both.

--key-file is also available as a global flag (AGENTSWAP_KEY_FILE) for trade, intent place, and the MCP server — see Trade and Agent intents.

Global flags

These apply to every subcommand.

Output and service

Flag	Env	Purpose
`-j`, `--json`	—	Emit raw JSON instead of tables
`--url`	`AGENTSWAP_URL`	Quote service base URL
`-k`, `--key`	`SR_API_KEY`	API key override
`--key-file`	`AGENTSWAP_KEY_FILE`	Local signer key file (trade / intent / MCP)

Trade and intent safety rails

Flag	Env	Purpose
`--allow-trade`	—	Opt in to execution (intent relay or broadcast); without it, `trade` and `intent place` are forced to dry-run
`--max-amount`	`AGENTSWAP_TRADE_MAX_AMOUNT`	Per-trade cap on `amountIn` in raw token units; refuses to sign or submit above it

Both flags are global so they also bound operations invoked through agentswap mcp. Details are on Trade and Agent intents.

Intent relay

Flag	Env	Default	Purpose
`--gateway-url`	`AGENTSWAP_GATEWAY_URL`	`https://app.agentswap.co`	Override the intent relay base URL for `intent place --relay`

RPC endpoints and lookback

On-chain operations (intent place --self-submit, intent list, intent status, policy, and trade --self-submit) read from and broadcast to EVM JSON-RPC endpoints.

Setting	Environment variable	Purpose
Chain RPC override	`AGENTSWAP_RPC_URL_<chainId>`	Per-chain RPC URL (e.g. `AGENTSWAP_RPC_URL_8453`, `AGENTSWAP_RPC_URL_56`)
Global RPC override	`AGENTSWAP_RPC_URL`	Fallback RPC URL for all chains

The CLI provides built-in public endpoints for the four supported chains:

Chain	Chain ID	Built-in public RPC	Default lookback
Base	`8453`	`https://mainnet.base.org`	200,000 blocks
Arbitrum	`42161`	`https://arb1.arbitrum.io/rpc`	200,000 blocks
BNB Smart Chain (BSC)	`56`	`https://bsc-rpc.publicnode.com`	9,000 blocks (see below)
Robinhood Chain	`4663`	`https://rpc.mainnet.chain.robinhood.com`	200,000 blocks

BSC lookback limit. BSC’s public RPC restricts log query depth. With the built-in RPC, the CLI defaults to 9,000 blocks on BSC. Point AGENTSWAP_RPC_URL_56 or AGENTSWAP_RPC_URL at a keyed RPC endpoint to enable the full 200,000-block lookback, or pass --lookback-blocks <U64> on individual queries.

# Set a keyed endpoint for BSC lookback
export AGENTSWAP_RPC_URL_56=https://bsc-mainnet.nodereal.io/YOUR_KEY
agentswap intent list --chainid 56 --owner 0xYourOwner

x402 paid retry

Quotes, trades and intents are served without any payment. The service answers HTTP 402 Payment Required only once a caller is past the free allowance, and that status is the whole trigger: the CLI then signs an EIP-3009 payment and retries that one request. It is off unless --x402 is set, and it pays nothing until --x402-max-amount is above zero.

Flag	Env	Default	Purpose
`--x402`	`AGENTSWAP_X402`	off	Pay and retry a request the service answered with 402
`--prefer-x402`	—	off	Prefer x402 even when an API key is configured
`--x402-key-file`	`AGENTSWAP_X402_KEY_FILE`	none	Key file for x402 EIP-3009 signatures
`--x402-chainid`	`AGENTSWAP_X402_CHAINID`	`8453`	Chain ID for x402 payments
`--x402-max-amount`	`AGENTSWAP_X402_MAX_AMOUNT`	`0`	Maximum x402 payment in raw token units
`--x402-asset`	`AGENTSWAP_X402_ASSET`	`USDC`	Asset symbol or address selector

export AGENTSWAP_X402=1
export AGENTSWAP_X402_KEY_FILE=./x402-signer.txt
agentswap quote --chainid 8453 --from USDC --to WETH --amount 1000000

Next steps

Commands — subcommands reference and examples
Agent intents — open intents, listing, status, and policy
Trade — signing User Proxy agent orders, safety rails, and MCP