Introduction

NexusAI is an AI-powered crypto agent platform built on Virtuals Protocol. Launch tokens, trade, and manage your portfolio through natural language commands. Connect your wallet, give the agent a directive, and let NexusAI handle the rest — from on-chain execution to real-time market analysis.

// NexusAI — AI-native crypto agent
// Powered by Virtuals Protocol

const nexus = new NexusAI({ apiKey: process.env.NEXUSAI_API_KEY });

await nexus.execute("Buy $100 of VIRTUAL when RSI drops below 35");

Quick Start

Get up and running in under two minutes. Install the CLI, authenticate with your wallet, and launch your first agent token.

npm i -g @nexusai/cli

nexusai login

nexusai launch MYTOKEN "My Agent"

Installation

Install the NexusAI CLI globally via npm or yarn. Requires Node.js 18+. After installation, set your API key as an environment variable to enable authenticated requests.

# Install via npm
npm install -g @nexusai/cli

# Or via yarn
yarn global add @nexusai/cli

# Set your API key
export NEXUSAI_API_KEY="nxai_your_key_here"

# Verify installation
nexusai --version

npm install @nexusai/sdk

# In your project
import { NexusAI } from "@nexusai/sdk";

const client = new NexusAI({
  apiKey: process.env.NEXUSAI_API_KEY,
  network: "base-mainnet", // or "base-sepolia" for testnet
});

Buy / Sell

Execute market buys and sells using natural language or structured commands. The agent automatically selects the best route and slippage settings.

# Buy tokens
nexusai buy VIRTUAL 100         # buy $100 of VIRTUAL
nexusai buy VIRTUAL 0.5 --eth   # buy with 0.5 ETH

# Sell tokens
nexusai sell VIRTUAL 50         # sell $50 worth
nexusai sell VIRTUAL all        # sell entire position

# With slippage
nexusai buy VIRTUAL 200 --slippage 1.5

Swap

Swap between any two tokens on Base. NexusAI routes through the most liquid DEX automatically, with optional limit and twap modes.

# Basic swap
nexusai swap ETH VIRTUAL 0.1     # swap 0.1 ETH → VIRTUAL
nexusai swap USDC VIRTUAL 500    # swap 500 USDC → VIRTUAL

# TWAP execution (split over time)
nexusai swap ETH VIRTUAL 1 --twap 4h

# Preview without executing
nexusai swap ETH VIRTUAL 0.1 --dry-run

Launch Token

Deploy a new AI agent token on Virtuals Protocol. Specify a ticker, agent name, and optional parameters for initial liquidity and tokenomics.

# Basic launch
nexusai launch TICKER "Agent Name"

# With description and liquidity
nexusai launch TICKER "Agent Name" \
  --desc "An AI agent that does X" \
  --liquidity 5000 \
  --supply 1000000000

# Interactive mode
nexusai launch --interactive

Analyze

Run deep AI analysis on any token or wallet. Get technical indicators, sentiment scores, holder distribution, and on-chain signals.

# Token analysis
nexusai analyze VIRTUAL
nexusai analyze 0xabc...def          # by contract address

# Wallet analysis
nexusai analyze --wallet 0xabc...def

# Output formats
nexusai analyze VIRTUAL --format json
nexusai analyze VIRTUAL --format pdf

Trending

Fetch the current trending tokens on Virtuals Protocol, filtered by volume, price change, or AI-generated momentum score.

# Show top trending tokens
nexusai trending

# Filter and sort options
nexusai trending --sort volume     # by 24h volume
nexusai trending --sort change     # by % price change
nexusai trending --sort score      # by AI momentum score
nexusai trending --limit 20        # show top 20

Wallet

Inspect wallet balances, transaction history, and portfolio performance. Supports both connected and external wallets.

# View your connected wallet
nexusai wallet

# View specific wallet
nexusai wallet 0xabc...def

# Portfolio breakdown
nexusai wallet portfolio
nexusai wallet portfolio --history 30d

# Export
nexusai wallet export --format csv

LLM Gateway — Overview

The NexusAI LLM Gateway provides a unified OpenAI-compatible API endpoint for accessing AI models with built-in crypto context, on-chain data enrichment, and DeFi tool-calling capabilities. Drop it in wherever you use OpenAI.

// OpenAI-compatible base URL
const client = new OpenAI({
  baseURL: "https://llm.nexusai.dev/v1",
  apiKey: process.env.NEXUSAI_API_KEY,
});

const response = await client.chat.completions.create({
  model: "nexus-pro",
  messages: [{ role: "user", content: "What is VIRTUAL's 7-day trend?" }],
});

Authentication

All LLM Gateway requests require a Bearer token in the Authorization header. Generate API keys from your NexusAI dashboard or via the CLI.

# Generate an API key
nexusai apikey create --name "my-app"

# Use in requests
curl https://llm.nexusai.dev/v1/chat/completions \
  -H "Authorization: Bearer nxai_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"nexus-pro","messages":[{"role":"user","content":"Hello"}]}'

Endpoints

The gateway exposes standard OpenAI-compatible endpoints alongside NexusAI-specific routes for agent orchestration and on-chain actions.

POST   /v1/chat/completions      # Chat with crypto context
POST   /v1/embeddings            # Generate embeddings
GET    /v1/models                # List available models

# NexusAI-specific
POST   /v1/agent/execute         # Execute on-chain action via LLM
POST   /v1/agent/analyze         # AI token analysis
GET    /v1/agent/status/:id      # Check agent task status

Rate Limits

Rate limits are applied per API key. Free tier allows 60 requests/min. Pro tier supports 600 requests/min with burst capacity. Limits are returned in response headers.

# Response headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1711900800

# Tiers
# Free:  60 req/min,  10k tokens/day
# Pro:   600 req/min, 2M tokens/day
# Team:  unlimited (fair-use policy)

Token Feed

Fetch a real-time feed of all tokens listed on Virtuals Protocol, with price, volume, holder count, and AI momentum scores.

GET /api/v1/tokens

# Query parameters
?sort=volume&order=desc&limit=50&page=1

# Response
{
  "tokens": [
    {
      "ticker": "VIRTUAL",
      "address": "0xabc...def",
      "price": 1.24,
      "change24h": 5.3,
      "volume24h": 2400000,
      "holders": 14320,
      "aiScore": 87
    }
  ],
  "total": 1204,
  "page": 1
}

Swap Quote

Get a swap quote for any token pair. Returns expected output, price impact, route, and gas estimate before execution.

GET /api/v1/swap/quote

# Query parameters
?tokenIn=ETH&tokenOut=VIRTUAL&amountIn=0.1

# Response
{
  "tokenIn": "ETH",
  "tokenOut": "VIRTUAL",
  "amountIn": "0.1",
  "amountOut": "1204.55",
  "priceImpact": 0.12,
  "route": ["ETH", "USDC", "VIRTUAL"],
  "gasEstimate": "0.0004 ETH",
  "expiresAt": 1711900860
}

Portfolio

Retrieve full portfolio data for a wallet address, including token balances, current values, PnL, and historical performance.

GET /api/v1/portfolio/:address

# Response
{
  "address": "0xabc...def",
  "totalValue": 12480.50,
  "pnl24h": 340.20,
  "pnlPercent24h": 2.8,
  "tokens": [
    {
      "ticker": "VIRTUAL",
      "balance": "5000",
      "value": 6200.00,
      "avgEntry": 1.10,
      "pnl": 700.00
    }
  ],
  "history": [...]
}