Trading Tokens
Use the npx agnic@latest trade command to swap tokens on Base network. You must be authenticated to trade.
Confirm wallet is initialized and authed
npx agnic@latest status
If the wallet is not authenticated, refer to the authenticate-wallet skill.
Command Syntax
npx agnic@latest trade <amount> <from> <to> [options]
Arguments
| Argument | Description |
|---|---|
amount |
Amount to swap (see Amount Formats below) |
from |
Source token: alias (usdc, eth, weth) or contract address (0x...) |
to |
Destination token: alias (usdc, eth, weth) or contract address (0x...) |
Amount Formats
| Format | Example | Description |
|---|---|---|
| Dollar prefix | '$1.00', '$0.50' |
USD notation (decimals based on token) |
| Decimal | 1.0, 0.50, 0.001 |
Human-readable with decimal point |
| Whole number | 5, 100 |
Interpreted as whole tokens |
| Atomic units | 500000 |
Large integers treated as atomic units |
Auto-detection: Large integers without a decimal point are treated as atomic units. For example, 500000 for USDC (6 decimals) = $0.50.
IMPORTANT: Always single-quote amounts that use $ to prevent bash variable expansion (e.g. '$1.00' not $1.00).
Token Aliases
| Alias | Token | Decimals | Address |
|---|---|---|---|
| usdc | USDC | 6 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| eth | ETH | 18 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
| weth | WETH | 18 | 0x4200000000000000000000000000000000000006 |
Options
| Option | Description |
|---|---|
-s, --slippage <n> |
Slippage tolerance in basis points (100 = 1%) |
--json |
Output result as JSON |
Input Validation
Before constructing the command, validate all user-provided values to prevent shell injection:
- amount: Must match
^\$?[\d.]+$(digits, optional decimal point, optional$prefix). Reject if it contains spaces, semicolons, pipes, backticks, or other shell metacharacters. - from / to: Must be a known alias (
usdc,eth,weth) or a valid0xhex address (^0x[0-9a-fA-F]{40}$). Reject any other value. - slippage: Must be a positive integer (
^\d+$).
Do not pass unvalidated user input into the command.
Examples
# Swap $1 USDC for ETH (dollar prefix — note the single quotes)
npx agnic@latest trade '$1' usdc eth
# Swap 0.50 USDC for ETH (decimal format)
npx agnic@latest trade 0.50 usdc eth
# Swap 0.01 ETH for USDC
npx agnic@latest trade 0.01 eth usdc
# Swap with custom slippage (2%)
npx agnic@latest trade '$5' usdc eth --slippage 200
# Get JSON output
npx agnic@latest trade '$1' usdc eth --json
Prerequisites
- Must be authenticated (
npx agnic@latest statusto check) - Wallet must have sufficient balance of the source token
- Trading is only available on Base mainnet
Error Handling
Common errors:
- "Not authenticated" — Run
npx agnic@latest auth loginfirst - "Invalid token" — Use a valid alias (usdc, eth, weth) or 0x address
- "Cannot swap a token to itself" — From and to must be different
- "Swap failed: TRANSFER_FROM_FAILED" — Insufficient balance or approval issue
- "No liquidity" — Try a smaller amount or different token pair
- "Amount has X decimals but token only supports Y" — Too many decimal places