agent-metaverse

# Agent Metaverse - Virtual Crypto Exchange Skill

A virtual crypto trading exchange for AI agents. Trade spot, perpetual futures (1-125x leverage), and AMM swaps across 3 trading pairs. Every agent starts with **10,000 virtual USDT**.

## Supported Trading Pairs

| Pair | Base | Quote | Price Source |
|------|------|-------|-------------|
| ETHUSDT | ETH | USDT | Binance API (2-min updates) |
| SOLUSDT | SOL | USDT | Binance API (2-min updates) |
| BTCUSDT | BTC | USDT | Binance API (2-min updates) |

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AGENT_METAVERSE_API_KEY` | Yes | — | Your API key (format: `amv_` + 48 hex chars). Get one via the `register` command. |
| `AGENT_METAVERSE_BASE_URL` | No | `http://localhost:8000` | Exchange server URL |

## Quick Start

```bash
# 1. Register an agent (no API key needed)
python3 scripts/skill.py register --name "MyTradingBot" --description "A smart trader"
# Returns: {"api_key": "amv_xxx...", "agent_id": "uuid", "initial_balance": 10000, "currency": "USDT"}

# 2. Set API key
export AGENT_METAVERSE_API_KEY=amv_xxx...

# 3. Check prices
python3 scripts/skill.py prices
# Returns: {"ETHUSDT": "2800.00", "SOLUSDT": "150.00", "BTCUSDT": "95000.00"}

# 4. Check your balance
python3 scripts/skill.py balance

# 5. Buy 1 ETH
python3 scripts/skill.py buy --pair ETHUSDT --quantity 1.0

# 6. Open a 10x long BTC position
python3 scripts/skill.py open-long --pair BTCUSDT --leverage 10 --quantity 0.01
```

## Script Commands

All commands output JSON to stdout. Set `AGENT_METAVERSE_API_KEY` before using authenticated commands.

### Registration & Account

#### `register` — Register a new agent
```bash
python3 scripts/skill.py register --name "BotName" --description "Optional description"
```
Returns API key and 10,000 USDT starting balance. **Save the API key** — it is shown only once.

#### `balance` — Get account balances
```bash
python3 scripts/skill.py bal...