intents-cli | NEAR Intents for Agents

Installation

# Install the skill for your AI agent
$ npx skills add https://github.com/SurgeCode/intents-cli --skill intents-cli

# Or run the CLI directly
$ npx intents-cli@latest

Requires Node.js 18+ and near-cli-rs.

# Install near-cli-rs
$ brew install near-cli-rs # macOS
$ cargo install near-cli-rs # or with Rust

First-Time Setup

On first run, the CLI guides you through configuration:

API Key (optional) — Get one at partners.near-intents.org. Reduces swap fees from 0.1% to free.
NEAR Account (required) — Create a new implicit account, import from seed phrase (24 words), or import from private key.

Config stored at ~/.intents-cli/config.json. Credentials at ~/.near-credentials/.

Interactive Mode

Run with no arguments for the full interactive UI:

$ intents

> Get Quote & Swap
  View Balances
  Deposit to Intents
  Withdraw from Intents
  Settings
  Exit

Select tokens from your balance, review quotes with rates and slippage, and confirm to execute. Colored output, spinners, and formatted tables.

Agent CLI

Non-interactive mode with structured JSON output. Designed for AI agents, scripts, and automation pipelines.

$ intents agent <command> [options]

Command	Description
balance	Intents + native NEAR balances with USD values
tokens	List supported tokens (--chain, --search filters)
price	Read-only price check (no deposit address allocated)
quote	Get swap quote with deposit address
swap	Execute swap (--dry-run, --slippage, --min-out, --use-quote)
deposit	Deposit from NEAR wallet to intents balance
withdraw	Withdraw to any chain (--to, --chain)
status	Check swap/deposit status (--poll to wait)
batch-quote	Get quotes for multiple trades from JSON file
batch-swap	Execute multiple swaps from JSON file
account	View, create, import, list, switch accounts
config	View current configuration
ready	Check if CLI is ready for autonomous operation

JSON Response Format

// Success
{ "ok": true, "command": "swap", "data": { ... }, "meta": { "durationMs": 1234 } }

// Error
{ "ok": false, "error": { "code": "TOKEN_NOT_FOUND", "message": "...", "retryable": true, "suggestion": "..." } }

Token Format

Three ways to specify tokens in agent commands:

Format	Example	Description
Symbol	USDC	Auto-resolves (prefers NEAR chain)
Symbol:chain	USDC:eth	Specific chain (eth, sol, base, arb...)
Full assetId	nep141:wrap.near	Exact asset identifier

# 29 supported chains (use `intents agent tokens --chain=X` to browse)
near, eth, sol, base, arb, btc, avax, bsc, pol, op, ton, aptos,
sui, tron, doge, xrp, stellar, ltc, cardano, starknet, bera,
gnosis, monad, aleo, zec, bch, xlayer, plasma, turbo

# Find tokens
$ intents agent tokens --search=usdc
$ intents agent tokens --chain=near
$ intents agent tokens --chain=eth --search=weth

Swap

Swap tokens within your intents balance. Supports dry runs, slippage control, minimum output protection, and two-step quote-then-execute.

# Simple swap
$ intents agent swap --from=USDC --to=wNEAR --amount=10

# Dry run (quote only, no execution)
$ intents agent swap --from=USDC --to=wNEAR --amount=10 --dry-run

# With slippage tolerance (basis points, default: 100 = 1%)
$ intents agent swap --from=USDC --to=wNEAR --amount=10 --slippage=50

# Abort if output below minimum
$ intents agent swap --from=USDC --to=wNEAR --amount=10 --min-out=8.5

# Two-step: get quote first, execute later
$ intents agent quote --from=USDC --to=wNEAR --amount=10
$ intents agent swap --use-quote=<depositAddress>

Price Check (Read-Only)

# Get price without allocating a deposit address
$ intents agent price --from=USDC --to=wNEAR --amount=1

Returns rate, market rate, price impact, and USD values without committing to a swap.

Deposit

Move tokens from your NEAR wallet into your intents balance.

# Deposit NEAR (auto-wraps to wNEAR)
$ intents agent deposit --token=NEAR --amount=1

# Deposit wNEAR directly
$ intents agent deposit --token=wNEAR --amount=0.5

# Dry run
$ intents agent deposit --token=NEAR --amount=1 --dry-run

NEAR deposits are fully automated (wrap + transfer). For other chains, the CLI returns a deposit address where you send tokens manually.

Withdraw

Send tokens from your intents balance to any destination chain.

# Withdraw to NEAR wallet
$ intents agent withdraw --token=wNEAR --amount=1 --to=myaccount.near

# Cross-chain withdraw to Base
$ intents agent withdraw --token=USDC --amount=50 --to=0x... --chain=base

# Dry run
$ intents agent withdraw --token=USDC --amount=10 --to=0x... --chain=eth --dry-run

Status Tracking

# Check status once
$ intents agent status --address=<depositAddress>

# Poll until terminal status (SUCCESS, FAILED, EXPIRED)
$ intents agent status --address=<depositAddress> --poll

Returns status, swap details (amounts in/out, tx hashes, slippage), and full status history when polling.

Batch Operations

Execute multiple trades from a JSON file.

# trades.json
{ "trades": [
{ "from": "USDC", "to": "wNEAR", "amount": 10 },
{ "from": "wNEAR", "to": "USDC:eth", "amount": 5, "minOut": 4.5 }
] }

# Get quotes for all trades
$ intents agent batch-quote --file=trades.json

# Execute all trades
$ intents agent batch-swap --file=trades.json

# Require ALL trades valid before executing any
$ intents agent batch-swap --file=trades.json --require-all-valid

# Two-step: quote then execute with existing quotes
$ intents agent batch-swap --file=trades.json --use-quotes

Account Management

# View current account
$ intents agent account

# List all accounts
$ intents agent account list

# Create new implicit account
$ intents agent account create

# Import from private key
$ intents agent account import --account-id=mybot.near --private-key=ed25519:...

# Switch active account
$ intents agent account switch --account-id=other.near

How It Works

Your tokens on any chain
↓ DEPOSIT
INTENTS BALANCE
(intents.near contract)
↓ SWAP (instant, cross-chain)
Updated balance
↓ WITHDRAW
Any destination chain/address

Error Handling

All errors include machine-readable codes, retry hints, and recovery suggestions.

Code	Meaning
TOKEN_NOT_FOUND	Symbol not recognized
TOKEN_AMBIGUOUS	Symbol matches multiple tokens — use chain qualifier
INSUFFICIENT_BALANCE	Not enough balance for operation
QUOTE_FAILED	Failed to get quote (low liquidity, amount too small)
QUOTE_EXPIRED	Quote expired before execution
RATE_LIMITED	Too many requests (includes retryAfterSeconds)
NOT_CONFIGURED	No NEAR account configured
SWAP_FAILED	Swap execution failed
TRANSFER_FAILED	Token transfer failed

# Every error response includes:
{
  "code": "TOKEN_AMBIGUOUS",
  "message": "USDC matches 3 tokens on different chains",
  "retryable": false,
  "suggestion": "Use chain qualifier (e.g., USDC:eth)"
}

NEAR INTENTS