docs/cli-guide

# CLI Guide

The agentswap CLI provides terminal access to AgentSwap. Use --json for machine-readable output.

## Install

cargo install agentswap

# verify
agentswap --version
agentswap 0.1.1

## Global Flags

--json, -j    Output raw JSON (default: formatted table)
--url, -u     Service URL (default: $SR_SERVICE_URL or http://localhost:3000)
--api-key, -k API key (default: $SR_API_KEY or ~/.agentswap/credentials)

## Quick Start

# 1) Register an API key (one-time)
agentswap register --address 0xYourWallet --key-file private-key.txt

# 2) Get a swap quote
agentswap quote -c base -f USDC -t WETH -a 1000

# 3) Check pricing and buy quota if needed
agentswap pricing
agentswap quota-claim -c base --tx-hash 0x...

## agentswap quote

agentswap quote -c base -f USDC -t WETH -a 1000

+------------------+-----------------------------+
| AgentSwap Quote                                 |
+------------------+-----------------------------+
| Chain            | Base (8453)                 |
| Input            | 1,000.00 USDC               |
| Output           | 0.4012 WETH                 |
| Route            | USDC>[UniV3:500]>WETH       |
| Source           | local                       |
| Price Impact     | 0.08%                       |
| Gas Estimate     | 184,000                     |
| Pool Grades      | A                           |
+------------------+-----------------------------+

Flags:
  -c, --chain      Chain: ethereum, base, arbitrum, 1, 8453, 42161
  -f, --from       Input token (symbol or 0x address)
  -t, --to         Output token
  -a, --amount     Human-readable amount, or "raw:123456789"
  -s, --slippage   Slippage in bps (default: 50)
  --verify         Verify quote on-chain via eth_call dry-run

## agentswap batch-quote

agentswap batch-quote -c base -a 1000 USDC/WETH WETH/DAI USDC/cbBTC

Quote multiple pairs in one call. Same amount applied to all pairs.

## agentswap register

agentswap register --address 0xYourWallet --key-file private-key.txt

Registers an API key via EIP-191 challenge/response.
Key is saved to ~/.agentswap/credentials for future use.

Options:
  --address       Wallet address (0x...)
  --key-file      Path to file containing private key (recommended)
  --private-key   Private key directly (less secure)

## agentswap pricing

agentswap pricing

Shows x402 version, per-quote price (USD + USDC),
and per-chain quota contract addresses.

## agentswap quota-claim

agentswap quota-claim -c base --tx-hash 0x...

Validates an on-chain quota purchase tx and credits quota to your API key.

## agentswap health

agentswap health

Service health: status, version, uptime, pool counts, sync lag, memory.

## agentswap chains

agentswap chains

Lists supported chains, DEX protocols, and pool counts.

## agentswap tokens

agentswap tokens
agentswap tokens -c base

Lists all known tokens: address, symbol, decimals. Filter by chain.

## agentswap pools

agentswap pools -c base -a 0x1234...

Inspect pool state: reserves, liquidity, fee, grade.

## agentswap key-info

agentswap key-info

Shows API key status, quota remaining, and usage.

## agentswap buy-quota

# Buy quota with USDC (direct)
agentswap buy-quota -c base -t USDC -a 1

# Buy quota with any token (auto-swap to USDC)
agentswap buy-quota -c base -t WETH -a 0.0004

Outputs wallet call instructions (approve + buyWithToken).
Does NOT send transactions — use your wallet to execute.

Options:
  -c, --chain   Chain: base, arbitrum
  -t, --token   Payment token (symbol or address)
  -a, --amount  Amount in human-readable units

## agentswap route-explain

agentswap route-explain --hash 0x...

Explain a saved quote route by its hash (from quote response).

## JSON Output

# pipe to jq for scripting
agentswap quote -c base -f USDC -t WETH -a 1000 --json | jq -r '.output'
401234567890123456

agentswap health --json | jq -r '.status'
ok

# batch quote as JSON
agentswap batch-quote -c base -a 1000 USDC/WETH WETH/DAI --json | jq '.'

## Environment Variables

AGENTSWAP_URL   Service endpoint (default: https://api.agentswap.co)
SR_API_KEY       API key (overrides ~/.agentswap/credentials)

## All Commands

quote          Get a swap quote
buy-quota      Buy API quota with any token
batch-quote    Quote multiple pairs at once
health         Service health check
chains         List supported chains and DEXes
tokens         List supported tokens
pools          Inspect a specific pool
register       Register API key via wallet signature
pricing        Show pricing and payment info
key-info       API key status and quota
quota-claim    Claim purchased quota
route-explain  Explain a saved route by hash