```
██╗  ██╗██╗  ██╗██╗   ██╗██╗   ██╗    ███████╗██╗  ██╗██╗██╗     ██╗
╚██╗██╔╝╚██╗██╔╝╚██╗ ██╔╝╚██╗ ██╔╝    ██╔════╝██║ ██╔╝██║██║     ██║
 ╚███╔╝  ╚███╔╝  ╚████╔╝  ╚████╔╝     ███████╗█████╔╝ ██║██║     ██║
 ██╔██╗  ██╔██╗   ╚██╔╝    ╚██╔╝      ╚════██║██╔═██╗ ██║██║     ██║
██╔╝ ██╗██╔╝ ██╗   ██║      ██║       ███████║██║  ██╗██║███████╗███████╗
╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝      ╚═╝       ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝
```

# XXYY Skill

> On-chain token trading and real-time data queries, powered by AI agents.

**Supported chains:** Solana | Ethereum | BSC | Base

With XXYY CLI, your AI agent can query real-time trending token rankings, token fundamentals, security checks, wallet balances, PNL analysis, KOL and smart money activity, and execute market orders — all through natural language or direct CLI commands.

---

## Why XXYY CLI

**1. Real-time on-chain data**
Live data across SOL / ETH / BSC / Base on every query. Trending tokens, feed scanning, token security checks, holder analysis — no cache, built for AI agent real-time decision-making.

**2. Trade faster**
Same routing as the XXYY web trading interface. Anti-sandwich protection (MEV) by default, fast mode optional. Sell by percentage — no manual amount calculation needed.

**3. Zero hallucination**
Every command maps to a real API endpoint with structured output. AI agents call the CLI directly instead of guessing URLs or scraping web pages. `--raw` flag outputs pipe-friendly JSON for programmatic use.

**4. Simple setup**
One `npm install`, one API key. No private keys needed — XXYY uses a custodial wallet model. Configure once, trade from any AI client.

---

## What You Can Do

**Real-time chain scanning**
- Scan for newly launched, almost graduated, or graduated Meme tokens on SOL/BSC
- Browse multi-chain trending token rankings (1m to 24h granularity)
- Track KOL and Smart Money buying activity in real time

**Token analytics**
- Query token fundamentals: price, market cap, holders, volume, social links
- Security check: honeypot detection, open source, ownership renounced, liquidity locked
- Tax rate analysis: buy/sell tax warnings for high-tax tokens
- Top holder breakdown and developer holding percentage

**Wallet & PNL**
- List all wallets linked to your API key with native token balances
- Query specific wallet details and token holdings
- Full PNL analysis: buy/sell totals, current holdings, profit in native + USD

**Trading**
- Market buy/sell orders with configurable tip, slippage, and execution model
- Sell by percentage (e.g., sell 50% of holdings)
- Launch new tokens on SOL or BSC with optional initial buy

---

## Quick Start

### Quick Start (AI Agent)

The following steps are for AI Agents. Some steps require the user to complete actions in a browser.

**Step 1 — Install CLI**

```bash
npm install -g xxyy-skill
```

**Step 2 — Verify installation**

```bash
xxyy-skill --version
```

If the version number appears, the CLI is installed correctly. Continue to Step 3.

**Step 3 — Configure API Key**

Tell the user:

> "To use XXYY CLI, you need an API key. Go to https://xxyy.io/apikey to create one, then send it back to me."

Once the user provides the key, run:

```bash
xxyy-skill config set XXYY_API_KEY <user_api_key>
```

**Step 4 — Verify connection**

```bash
xxyy-skill ping
```

If output shows `pong — API Key is valid.`, setup is complete.

**Step 5 — (Optional) Check IP whitelist**

If the API key has IP whitelist enabled:

```bash
xxyy-skill ip
```

Show the IP to the user and ask them to add it to their whitelist at https://xxyy.io/apikey.

### Quick Start (Manual)

```bash
# Install
npm install -g xxyy-skill

# Configure API key
xxyy-skill config set XXYY_API_KEY <your_key>

# Verify
xxyy-skill ping
```

---

## Installation

### npm Global Install

```bash
npm install -g xxyy-skill
```

### Verify

```bash
xxyy-skill --version
```

---

## Get Your API Key

1. Go to https://xxyy.io/apikey
2. Create a new API key
3. (Optional) Set IP whitelist for swap operations
4. Copy the key (format: `xxyy_ak_xxxx`)

**Important:** Your API key is linked to your XXYY account wallets. Anyone with your key can execute trades. Keep it safe.

---

## Configuration

### Config file (recommended)

```bash
xxyy-skill config set XXYY_API_KEY xxyy_ak_xxxx
```

This writes to `~/.config/xxyy/.env` with `600` permissions.

### Environment variable

```bash
export XXYY_API_KEY=xxyy_ak_xxxx
```

### CLI flag (per-command override)

```bash
xxyy-skill ping --api-key xxyy_ak_xxxx
```

### Priority order

1. `--api-key` CLI flag (highest)
2. `XXYY_API_KEY` environment variable
3. `~/.config/xxyy/.env` config file

### Custom API base URL

```bash
xxyy-skill config set XXYY_API_BASE_URL https://custom.xxyy.io
```

---

## Usage

### Natural language prompts

Send these to your AI agent:

```
buy 0.1 SOL of <token_address>
sell 50% of <token_address> on BSC
check if <token_address> is safe to buy on solana
show trending tokens on SOL for the last 1 hour
show KOL buy activity on SOL
show my wallets on SOL
query token details for <token_address>
check PNL for my wallet on <token_address>
scan for new tokens on SOL
show smart money activity on BSC
```

### Typical workflows

**Research a token:**
```
token info  →  check security / tax  →  check holders  →  decide buy/skip
```

**Discover opportunities:**
```
market trending  →  pick top candidates  →  token info  →  buy
```

**Execute a trade:**
```
wallet list (find wallet)  →  token info (confirm token)  →  buy  →  trade query (check status)
```

**Monitor PNL:**
```
wallet list  →  pnl (check profit)  →  sell if target reached
```

---

## CLI Reference

### Global Flags

| Flag | Description |
|------|-------------|
| `--raw` | Output raw JSON (pipe-friendly, works with `jq`) |
| `--api-key <key>` | Override API key for this command |
| `--base-url <url>` | Override API base URL |
| `-V, --version` | Show version |
| `-h, --help` | Show help |

### Token

```bash
# Query token details
xxyy-skill token info <address> --chain sol
xxyy-skill token info <address> --chain bsc --raw
```

### Market

```bash
# Trending tokens
xxyy-skill market trending --period 1H --chain sol
xxyy-skill market trending --period 5M --chain bsc

# KOL buy list
xxyy-skill market kol --chain sol

# Smart money / whale buy list
xxyy-skill market smart-money --chain sol

# Label tokens (AGENT_KOL)
xxyy-skill market label --chain sol --type AGENT_KOL

# AI trend signals
xxyy-skill market signal --chain sol --type open-ai-trending
```

### Feed (Chain Scanning)

```bash
# Scan newly launched tokens
xxyy-skill feed new --chain sol

# Almost graduated tokens
xxyy-skill feed almost --chain bsc

# Graduated tokens with filters
xxyy-skill feed completed --chain sol --filters '{"mc":"10000,500000","holder":"50,"}'
```

### Wallet

```bash
# List all wallets
xxyy-skill wallet list --chain sol

# Query specific wallet
xxyy-skill wallet info <address> --chain sol

# Check token holdings
xxyy-skill wallet info <address> --chain sol --token <token_address>
```

### Trade

```bash
# Query trade status
xxyy-skill trade query <txId>

# Trade history
xxyy-skill trade list --wallet <address> --chain sol
xxyy-skill trade list --wallet <address> --chain sol --token <token_address> --page 1 --size 10
```

### Swap (Buy / Sell)

```bash
# Buy token
xxyy-skill buy \
  --chain sol \
  --wallet <wallet_address> \
  --token <token_address> \
  --amount 0.1 \
  --tip 0.0001

# Sell 50% of holdings
xxyy-skill sell \
  --chain sol \
  --wallet <wallet_address> \
  --token <token_address> \
  --amount 50 \
  --tip 0.0001

# With options
xxyy-skill buy \
  --chain sol \
  --wallet <address> \
  --token <address> \
  --amount 0.1 \
  --tip 0.001 \
  --slippage 15 \
  --model 2
```

### PNL

```bash
xxyy-skill pnl --wallet <address> --token <token_address> --chain sol
```

### Launch Token

```bash
# Launch on SOL
xxyy-skill launch \
  --chain sol \
  --wallet <address> \
  --name "My Token" \
  --symbol MTK \
  --sol-uri "https://example.com/metadata.json" \
  --buy-amount 0.1

# Launch on BSC
xxyy-skill launch \
  --chain bsc \
  --wallet <address> \
  --name "My Token" \
  --symbol MTK \
  --bsc-desc "Token description" \
  --bsc-image "https://example.com/image.png" \
  --buy-amount 0.001
```

### Config

```bash
xxyy-skill config set XXYY_API_KEY <key>
xxyy-skill config get XXYY_API_KEY
xxyy-skill config list
xxyy-skill config path
```

### Utility

```bash
# Verify API key
xxyy-skill ping

# Check outbound IP (for whitelist)
xxyy-skill ip
```

---

## Supported Chains

| Commands | Chains |
|----------|--------|
| token / wallet / trade / pnl / swap | sol / eth / bsc / base |
| feed / market trending / kol / smart-money / signal | sol / bsc |
| market label | sol |
| launch | sol / bsc |

---

## Upgrade

```bash
npm install -g xxyy-skill
xxyy-skill --version
```

---

## Security & Disclaimer

**About your API key**

Your XXYY API key is linked to your account's custodial wallets. It can be used to execute trades and query wallet data. If compromised, an attacker could trade using your wallets. Rotate it immediately at https://xxyy.io/apikey if you suspect exposure.

**Best practices**

- Never commit your API key to version control
- Use `xxyy-skill config set` which stores credentials with `600` permissions
- Do not share your API key in logs, screenshots, or chat messages
- Enable IP whitelist on your API key for swap operations
- Before every swap, review the trade parameters (chain, wallet, token, amount) carefully
- Test with small amounts first before executing larger trades
- Always use the latest version: `npm install -g xxyy-skill`

**Disclaimer**

Use of this tool and any financial decisions made based on its output are entirely at your own risk. XXYY is not liable for any trading losses, errors, or unauthorized access resulting from model hallucination, prompt injection, improper credential management, or user confirmation errors. On-chain transactions are irreversible once confirmed and may result in financial loss. By using this tool, you acknowledge that you have fully understood the above risks and voluntarily accept all responsibility.

---

## License

MIT