Near Intents Trading

NEAR Intents Trading

Orchestrate crypto portfolio management and cross-chain swaps using two CLI tools.

Install

If near-intents or portfolio are not installed:

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/FlipsideCrypto/near-intents-cli/main/install.sh | sh

Or with a specific version: VERSION=v0.1.0 curl -fsSL ... | sh

Custom install dir: INSTALL_DIR=~/.local/bin curl -fsSL ... | sh

Windows

Option A — Git Bash / MSYS2 (recommended):

The install script works in Git Bash or MSYS2. Open Git Bash and run:

curl -fsSL https://raw.githubusercontent.com/FlipsideCrypto/near-intents-cli/main/install.sh | sh

Binaries install to ~/.local/bin. If that's not in your PATH, add it:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc && source ~/.bashrc

Option B — Manual download (PowerShell / cmd):

1. Go to the latest release
2. Download near-intents_<version>_windows_amd64.zip and portfolio_<version>_windows_amd64.zip
3. Extract both .zip files
4. Move near-intents.exe and portfolio.exe to a directory in your PATH (e.g. C:\Users\<you>\bin)
5. Add that directory to your PATH if it isn't already:
   • Search "Environment Variables" in Start → Edit the user Path variable → Add the directory

Verify: open a new terminal and run near-intents --version

Tools

You MUST run both onboard commands before any other action in a session — no exceptions. Do not attempt to guess command names, flag names, or asset ID formats. Every mistake that wastes round trips (wrong flags, wrong token format, unknown commands) is documented in the onboard output. Running it takes seconds; skipping it costs minutes of failed attempts.

near-intents llm onboard
portfolio llm onboard

Run these immediately after updating. Do not proceed until you have read the output.

The Loop

OBSERVE  → portfolio balances / near-intents balances
DECIDE   → near-intents intel (feed it the portfolio summary)
PLAN     → near-intents quote (price out each swap)
CONFIRM  → present plan to user with fees and steps
EXECUTE  → near-intents swap + submit-tx
VERIFY   → near-intents status (poll until terminal)

Never skip OBSERVE. Never skip CONFIRM.

Before Anything

1. Update both tools — always run this first to ensure you have the latest version:

   near-intents update && portfolio update
   

   If either binary is missing, install first (see Install above), then update.

2. Read the onboard docs — run both of these and read the full output before proceeding:

   near-intents llm onboard
   portfolio llm onboard
   

   This is not optional. The onboard output contains exact command syntax, required flags, asset ID formats, and common mistakes. Skipping it and guessing will waste time.

3. Run portfolio setup --list — are addresses configured? If not, ask the user for their wallet addresses and add them.

4. Run portfolio balances (or near-intents balances --account <id> for NEAR-only) — establish current holdings.

5. If the user wants recommendations, summarize the balances and pass to near-intents intel --message "Here's my portfolio: [summary]. How should I rebalance?".

New User Detection

Run portfolio setup --list at the start of every session. If it's empty:

1. Ask: "What chains do you hold crypto on?" and "Do you have a NEAR account?"
2. No NEAR account → run near-intents llm topic new-account and follow it
3. No NEAR account, no other crypto → they need an exchange first
4. Add all addresses: portfolio setup --add --chain <near|evm|solana|bitcoin> --address <addr>
5. Collect API keys upfront: Flipside (~/.near-intents.json), Ankr (~/.portfolio.json)
6. Verify: portfolio balances should return data before starting any swaps

Do setup upfront — discovering missing config mid-swap wastes time.

Command Quick Reference

Key Concepts

• Signing URL is the default. Most swaps should use the cross-chain signing URL flow — user gets a link, opens it, connects wallet, signs. No near-cli needed, no wrapping, no storage deposits. Only use native mode if the user explicitly asks for it.
• Ask the user, don't assume. Present both options (signing URL vs native CLI) and let them choose. Don't probe for near-cli or check ~/.near-credentials/ unless the user wants native mode.
• assetId fields in balance output feed directly into near-intents swap --from / --to.
• Flipside intel is for analytical recommendations ("how should I rebalance?"), not balance lookups (use portfolio balances for that).
• intents vs wallet: Tokens in near-intents chain are immediately swappable. Tokens in wallet may need extra steps depending on mode.
• No withdraw CLI command. After native swaps, tokens land in intents.near. Withdraw via ft_withdraw on intents.near using near-cli directly. See onboard docs for exact syntax. (Only relevant in native mode.)

Common Mistakes