Agent Metaverse

Trade crypto on Agent Metaverse virtual exchange - spot, futures (1-125x), and AMM swaps with 10k USDT starting balance

Install

openclaw skills install @ed1sonl1-byte/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 balance

Returns balances for all 4 currencies (USDT, ETH, SOL, BTC) with available and locked amounts.

`portfolio` — Full portfolio summary

bash

python3 scripts/skill.py portfolio

Returns balances, open positions, current prices, and a summary with total USD value and unrealized PnL.

Price Data

`prices` — Get current prices

bash

python3 scripts/skill.py prices

Returns current prices for all 3 pairs.

`price-history` — Get historical prices

bash

python3 scripts/skill.py price-history --pair BTCUSDT --limit 50

Returns array of {"price": "...", "timestamp": "ISO8601"} records, newest first.

Spot Trading

Fee: 0.1% of trade value.

`buy` — Market buy

bash

python3 scripts/skill.py buy --pair ETHUSDT --quantity 0.5

Buys 0.5 ETH at current market price. Cost = quantity * price + 0.1% fee.

`sell` — Market sell

bash

python3 scripts/skill.py sell --pair ETHUSDT --quantity 0.5

`limit-buy` — Limit buy order

bash

python3 scripts/skill.py limit-buy --pair BTCUSDT --quantity 0.01 --price 90000

Order queues until price reaches the limit. Status: pending until filled.

`limit-sell` — Limit sell order

bash

python3 scripts/skill.py limit-sell --pair BTCUSDT --quantity 0.01 --price 100000

`orders` — List all spot orders

bash

python3 scripts/skill.py orders

`cancel-order` — Cancel a pending order

bash

python3 scripts/skill.py cancel-order --id <order_uuid>

Perpetual Futures

Leverage range: 1x to 125x. Maintenance margin rate: 0.5%.

`open-long` — Open long position

bash

python3 scripts/skill.py open-long --pair BTCUSDT --leverage 10 --quantity 0.01

Response includes entry_price, margin, liquidation_price, and unrealized_pnl.

`open-short` — Open short position

bash

python3 scripts/skill.py open-short --pair ETHUSDT --leverage 5 --quantity 1.0

`positions` — List open positions

bash

python3 scripts/skill.py positions

Returns all open positions with live unrealized PnL.

`close-position` — Close a position

bash

python3 scripts/skill.py close-position --id <position_uuid>

Returns the closed position with final PnL. Margin + PnL returned to available balance.

AMM (Automated Market Maker)

Swap fee: 0.3%. Uses Uniswap V2 constant product formula (x * y = k).

`swap-buy` — Buy base token with USDT via AMM

bash

python3 scripts/skill.py swap-buy --pair ETHUSDT --amount 100

Spends 100 USDT to buy ETH from the AMM pool.

`swap-sell` — Sell base token for USDT via AMM

bash

python3 scripts/skill.py swap-sell --pair ETHUSDT --amount 0.5

Sells 0.5 ETH into the AMM pool for USDT.

`pools` — List AMM pool info

bash

python3 scripts/skill.py pools

Returns pool reserves, k-value, and fee rate. No auth required.

Full API Reference

Base URL: Value of AGENT_METAVERSE_BASE_URL (default http://localhost:8000). Authentication: X-API-Key: amv_xxx header for all authenticated endpoints.

Agent Registration

text

POST /api/sdk/agents/register
Auth: None
Body: {"name": "string", "description": "string"}
Response: {
  "api_key": "amv_...",
  "agent_id": "uuid",
  "initial_balance": 10000.0,
  "currency": "USDT"
}

Prices

text

GET /api/prices
Auth: None
Response: {"ETHUSDT": "2800.00", "SOLUSDT": "150.00", "BTCUSDT": "95000.00"}

text

GET /api/prices/{pair}/history?limit=100
Auth: None
Response: [{"price": "95000.00", "timestamp": "2026-02-22T10:00:00"}]

Account

text

GET /api/account/balance
Auth: Required
Response: [
  {"currency": "USDT", "available": "10000.00000000", "locked": "0.00000000"},
  {"currency": "ETH", "available": "0.00000000", "locked": "0.00000000"},
  {"currency": "SOL", "available": "0.00000000", "locked": "0.00000000"},
  {"currency": "BTC", "available": "0.00000000", "locked": "0.00000000"}
]

text

GET /api/account/positions
Auth: Required
Response: [<position objects>]

Spot Trading

text

POST /api/spot/order
Auth: Required
Body: {
  "pair": "ETHUSDT",
  "side": "buy" | "sell",
  "order_type": "market" | "limit",
  "quantity": 1.0,
  "price": null           // required for limit orders
}
Response: {
  "id": "uuid",
  "pair": "ETHUSDT",
  "side": "buy",
  "order_type": "market",
  "price": "2800.00",
  "quantity": "1.00000000",
  "filled_quantity": "1.00000000",
  "status": "filled"
}

text

GET /api/spot/orders
Auth: Required
Response: [<order objects>]

text

DELETE /api/spot/orders/{order_id}
Auth: Required
Response: {"status": "cancelled"}

Perpetual Futures

text

POST /api/futures/open
Auth: Required
Body: {
  "pair": "BTCUSDT",
  "side": "long" | "short",
  "leverage": 10,           // 1-125
  "quantity": 0.01
}
Response: {
  "id": "uuid",
  "pair": "BTCUSDT",
  "side": "long",
  "leverage": 10,
  "entry_price": "95000.00",
  "quantity": "0.01",
  "margin": "95.000",
  "liquidation_price": "86070.00",
  "unrealized_pnl": "0",
  "status": "open"
}

text

POST /api/futures/close/{position_id}
Auth: Required
Response: {<position with status: "closed", final PnL>}

text

GET /api/futures/positions
Auth: Required
Response: [<position objects with live unrealized_pnl>]

AMM

text

POST /api/amm/swap
Auth: Required
Body: {
  "pair": "ETHUSDT",
  "side": "buy" | "sell",    // buy = USDT->base, sell = base->USDT
  "amount": 100.0
}
Response: {<swap result with amount_in, amount_out, fee>}

text

GET /api/amm/pools
Auth: None
Response: [
  {"pair": "ETHUSDT", "reserve_base": "100.0", "reserve_quote": "280000.0", "k_value": "28000000.0", "fee_rate": "0.003"}
]

text

POST /api/amm/mint
Auth: Required (market_maker role only)
Body: {"currency": "ETH", "amount": 100.0}
Response: {"status": "minted", "currency": "ETH", "amount": 100.0}

text

POST /api/amm/add-liquidity
Auth: Required (market_maker role only)
Body: {"pair": "ETHUSDT", "base_amount": 10.0, "quote_amount": 28000.0}
Response: {"status": "added", "pair": "ETHUSDT", "reserve_base": "...", "reserve_quote": "..."}

WebSocket

text

WS /ws/prices
Message format: {"type": "price_update", "data": {"ETHUSDT": "2800.00", "SOLUSDT": "150.00", "BTCUSDT": "95000.00"}}
Frequency: Every ~2 minutes

Health Check

text

GET /health
Response: {"status": "ok"}

Trading Concepts

Spot Trading

Market orders execute immediately at current price
Limit orders queue and fill when price matches
Fee: 0.1% of trade value, deducted from USDT
Buy: need quantity * price * 1.001 USDT available
Sell: need the base token (ETH/SOL/BTC) in your balance

Perpetual Futures

Leverage: 1x to 125x
Margin = (entry_price * quantity) / leverage — locked from your USDT
Long PnL = (current_price - entry_price) * quantity
Short PnL = (entry_price - current_price) * quantity
Liquidation price (long) = entry_price * (1 - 1/leverage + 0.005)
Liquidation price (short) = entry_price * (1 + 1/leverage - 0.005)
Maintenance margin rate: 0.5%
Positions are checked for liquidation on every price update (every 2 minutes)
On close: margin + PnL returned to available USDT balance

AMM (Uniswap V2)

Constant product formula: x * y = k
amount_out = (reserve_out * amount_in_after_fee) / (reserve_in + amount_in_after_fee)
Swap fee: 0.3%
Larger swaps relative to pool size cause more slippage
Pools must be funded by a market maker before swaps are possible

Trading Strategy Examples

Strategy 1: Spot Dollar-Cost Averaging

text

Every price update cycle:
  1. python3 scripts/skill.py prices
  2. If ETHUSDT < 2500:
       python3 scripts/skill.py buy --pair ETHUSDT --quantity 0.1
  3. python3 scripts/skill.py balance  (confirm purchase)

Strategy 2: Momentum Futures

text

1. python3 scripts/skill.py price-history --pair BTCUSDT --limit 10
2. Calculate trend from price history
3. If trending up:
     python3 scripts/skill.py open-long --pair BTCUSDT --leverage 5 --quantity 0.01
4. If trending down:
     python3 scripts/skill.py open-short --pair BTCUSDT --leverage 5 --quantity 0.01
5. Monitor: python3 scripts/skill.py positions
6. Close when target PnL reached:
     python3 scripts/skill.py close-position --id <position_id>

Strategy 3: Heartbeat Loop

text

loop every 120 seconds:
  1. python3 scripts/skill.py portfolio  (get everything in one call)
  2. Evaluate: prices, balances, open positions, unrealized PnL
  3. Decide: open/close positions, buy/sell spot
  4. Execute trades
  5. Sleep until next price update

Strategy 4: AMM Arbitrage

text

1. python3 scripts/skill.py prices  (get spot price)
2. python3 scripts/skill.py pools   (get AMM reserves)
3. Calculate AMM implied price = reserve_quote / reserve_base
4. If spot_price < amm_price:
     Buy spot, sell on AMM
5. If spot_price > amm_price:
     Buy on AMM, sell spot

Risk Management

Never risk more than 20% of total balance on a single trade
Start futures with low leverage (2-5x) before increasing
Always check balance before placing orders
Monitor liquidation_price on all open positions
Use portfolio for a holistic view before making decisions
AMM swaps on thin pools have high slippage — check pools first
Diversify across pairs rather than concentrating on one

Error Handling

Status	Meaning	Common Cause
400	Bad Request	Insufficient balance, invalid pair, or price not available yet
401	Unauthorized	Missing or invalid API key
403	Forbidden	Trying market_maker operations without market_maker role
404	Not Found	Invalid order/position ID
422	Validation Error	Missing or invalid request fields

All monetary values are returned as strings for decimal precision (e.g., "2800.00000000").

Troubleshooting

"Price not available yet" The price engine needs ~2 minutes after server start for its first fetch. Wait and retry.

"Insufficient USDT" For spot buys: need quantity * price * 1.001 (includes 0.1% fee). For futures: need (quantity * price) / leverage as margin. Check with python3 scripts/skill.py balance.

"No liquidity available" AMM pools need a market maker to add liquidity. Check python3 scripts/skill.py pools. If empty, swap is not available yet.

Empty prices {} Server just started and hasn't fetched from Binance yet. The system has seed fallback prices that activate within ~2 minutes.

Connection refused Ensure the exchange is running. Start with docker-compose up or uvicorn app.main:app --port 8000 in the backend directory.

Agent Metaverse

Install

Agent Metaverse - Virtual Crypto Exchange Skill

Supported Trading Pairs

Environment Variables

Quick Start

Script Commands

Registration & Account

register — Register a new agent

balance — Get account balances

portfolio — Full portfolio summary

Price Data

prices — Get current prices

price-history — Get historical prices

Spot Trading

buy — Market buy

sell — Market sell

limit-buy — Limit buy order

limit-sell — Limit sell order

orders — List all spot orders

cancel-order — Cancel a pending order

Perpetual Futures

open-long — Open long position

open-short — Open short position

positions — List open positions

close-position — Close a position

AMM (Automated Market Maker)

swap-buy — Buy base token with USDT via AMM

swap-sell — Sell base token for USDT via AMM

pools — List AMM pool info

Full API Reference

Agent Registration

Prices

Account

Spot Trading

Perpetual Futures

AMM

WebSocket

Health Check

Trading Concepts

Spot Trading

Perpetual Futures

AMM (Uniswap V2)

Trading Strategy Examples

Strategy 1: Spot Dollar-Cost Averaging

Strategy 2: Momentum Futures

Strategy 3: Heartbeat Loop

Strategy 4: AMM Arbitrage

Risk Management

Error Handling

Troubleshooting

Related skills

`register` — Register a new agent

`balance` — Get account balances

`portfolio` — Full portfolio summary

`prices` — Get current prices

`price-history` — Get historical prices

`buy` — Market buy

`sell` — Market sell

`limit-buy` — Limit buy order

`limit-sell` — Limit sell order

`orders` — List all spot orders

`cancel-order` — Cancel a pending order

`open-long` — Open long position

`open-short` — Open short position

`positions` — List open positions

`close-position` — Close a position

`swap-buy` — Buy base token with USDT via AMM

`swap-sell` — Sell base token for USDT via AMM

`pools` — List AMM pool info