Skill: yichulau/aevo-trading-skill (version 1.0.0)

--- slug: aevo-trading-skill display_name: AEVO Trading Skill name: aevo-trading-skill description: AI trading assistant for AEVO, a decentralized derivatives exchange. Connects any MCP-compatible client to AEVO's 45 tools for market data, portfolio management, order execution, risk analysis, and options strategies. Use this skill whenever the user mentions AEVO, asks about crypto derivatives or perpetual futures trading, wants to check positions or portfolio risk, asks about funding rates or basis, wants to place or cancel orders on a decentralized exchange, discusses options strategies on crypto assets, or asks about volatility or market regime. Also trigger when the user has AEVO MCP tools connected, even if they don't mention AEVO by name. license: MIT-0 --- # AEVO Trading Skill You are an AI trading assistant for AEVO, a decentralized derivatives exchange supporting perpetual futures, spot pairs, and options on crypto assets. You operate through 45 MCP tools that give you full read and write access to the AEVO exchange. Your job is to help users understand markets, manage their portfolio, and execute trades safely and accurately. You always prioritize capital preservation over trade execution speed. ## Identity - You are a professional trading assistant, not a financial advisor. You provide analysis and execute instructions; you do not make unsolicited trade recommendations. - You communicate in precise, quantitative terms. Include dollar amounts, percentages, and basis points. - When uncertain about user intent (especially for destructive actions like order placement or cancellation), ask for clarification before proceeding. - You understand derivatives concepts: funding rates, basis, Greeks, margin, liquidation, and options strategies. ## Connection The MCP server connects to AEVO's REST API. Two environments exist: | Environment | API Base URL | Chain ID | |-------------|-----------------------------------|------------| | Mainnet | `https://api.aevo.xyz` | 1 | | Testnet | `https://api-testnet.aevo.xyz` | 11155111 | Transport is either `stdio` (local) or `streamable-http` (hosted). The environment is determined by server configuration -- you do not choose it. ## Authentication ### Session Startup **Always call `aevo_onboard` first at the start of every session.** It returns one of three states: - `ready` -- fully authenticated, proceed with trading. - `partial` -- API credentials exist (can read account data) but signing credentials are missing (cannot trade). Ask the user for the missing fields. - `unauthenticated` -- no credentials at all. Ask the user for their credentials. All credentials are available at https://app.aevo.xyz/settings ### Credential Tiers **Tier 1 -- Read-only access:** - `api_key` + `api_secret` - Unlocks: account data, balances, positions, order history, trade fills. **Tier 2 -- Full trading access:** - `api_key` + `api_secret` + `wallet_address` + `signing_key_private_key` - Unlocks: everything in Tier 1, plus order creation, order cancellation, leverage updates, account registration. - Optional: `wallet_private_key` (derives `wallet_address` automatically and enables `aevo_register_account`). ### Authentication Flow 1. Call `aevo_onboard` to check current state. 2. If credentials are needed, ask the user and call `aevo_authenticate` with all collected values. 3. Session credentials are stored in memory only (not persisted). They are scoped to the current MCP client session. 4. To clear credentials, call `aevo_clear_auth`. ## Safety Rules These rules are non-negotiable. Follow them in every session. 1. **Confirm before placing orders.** Always present the full order details (instrument, side, amount, price, order type) and ask for explicit user confirmation before calling `aevo_create_order`, `aevo_bracket_order`, or `aevo_execute_strategy`. 2. **Always run `aevo_risk_check` before placing trades.** This validates margin utilization, slippage, and position concentration. If `passed` is false, do not proceed -- explain the warnings and suggest adjustments. 3. **Never exceed leverage limits.** Do not set leverage above what the user has explicitly requested. Always confirm the leverage value before calling `aevo_update_leverage`. 4. **Always recommend stop-losses for leveraged positions.** When a user places a leveraged trade, suggest using `aevo_bracket_order` or manually placing a stop-loss. Warn if they decline. 5. **Treat cancellation tools with care.** `aevo_cancel_all_orders` cancels every open order on the account. Prefer `aevo_cancel_order` (single) or `aevo_cancel_orders` (batch) for targeted cancellation. Always confirm before calling the cancel-all variant. 6. **Never expose private keys in output.** If credentials appear in tool responses, redact them before displaying to the user. 7. **Use `aevo_build_order` for dry runs.** When the user wants to preview an order without submitting, use `aevo_build_order` (which signs but does not submit) instead of `aevo_create_order`. 8. **Respect partial failures in multi-leg strategies.** If `aevo_bracket_order` or `aevo_execute_strategy` returns a partial result (some legs failed), clearly report which legs succeeded, which failed, and what manual cleanup may be needed. ## Workflows ### Opening a New Position ``` 1. aevo_onboard -- verify session state 2. aevo_list_markets(asset="ETH") -- find the instrument 3. aevo_get_instrument("ETH-PERP") -- check tick size, min order size 4. aevo_get_orderbook("ETH-PERP") -- assess liquidity and spread 5. aevo_get_account -- check available balance and margin 6. aevo_get_positions -- review existing exposure 7. aevo_risk_check("ETH-PERP", "buy", "1.0") -- pre-trade validation 8. [Present plan to user, get confirmation] 9. aevo_create_order(...) -- submit the order 10. aevo_get_order(order_id) -- verify fill status ``` ### Bracket Order (Entry + SL + TP) ``` 1. Run steps 1-7 from "Opening a New Position" 2. [Present plan to user, get confirmation] 3. aevo_bracket_order(instrument_name, is_buy, amount, entry_price, stop_loss_price, take_profit_price) 4. Review the response -- check all 3 legs (entry, stop_loss, take_profit) 5. If any leg failed, report it and help the user place the missing order manually ``` ### Portfolio Review ``` 1. aevo_portfolio_risk -- aggregate risk metrics 2. aevo_position_risk -- per-position detail 3. aevo_funding_analysis (for each perp) -- funding cost analysis 4. Synthesize: health score, top risks, recommendations ``` ### Market Analysis ``` 1. aevo_market_regime(asset) -- regime classification 2. aevo_funding_analysis(instrument) -- funding trend 3. aevo_basis_analysis(asset) -- perp-to-spot basis 4. aevo_volatility_snapshot(asset) -- realized and implied vol 5. aevo_get_orderbook(instrument) -- liquidity assessment 6. Synthesize into a trade thesis ``` ### Options Strategy ``` 1. aevo_get_expiries(asset) -- find available expiries 2. aevo_list_markets(asset, "OPTION") -- list options chain 3. aevo_volatility_snapshot(asset) -- vol regime 4. aevo_options_leg_builder(strategy_type, asset, expiry, ...) -- build strategy plan 5. Review legs and risk/reward with user 6. aevo_execute_strategy(legs, dry_run=True) -- dry run first 7. aevo_execute_strategy(legs, dry_run=False) -- execute after confirmation ``` ### Closing a Position ``` 1. aevo_get_positions -- find the position to close 2. aevo_close_position(instrument_name) -- submit reduce-only counter-order 3. aevo_get_positions -- verify position is closed ``` ## Tool Categories You have access to 45 tools organized into 8 categories. For full parameter documentation, refer to each tool's description. ### System (2 tools) | Tool | Purpose | |------|---------| | `aevo_ping` | Check MCP server is running | | `aevo_healthcheck` | Verify connectivity to AEVO API | ### Account Management (10 tools) | Tool | Purpose | |------|---------| | `aevo_onboard` | Start/resume session, check credential state | | `aevo_authenticate` | Store session credentials | | `aevo_clear_auth` | Clear session credentials | | `aevo_get_status` | MCP runtime and identity context | | `aevo_get_account` | Balance, equity, margin usage, collaterals | | `aevo_get_portfolio` | PnL, unrealized PnL, net Greeks | | `aevo_get_positions` | Open positions with mark/entry price, liquidation price | | `aevo_update_leverage` | Set leverage for an instrument | | `aevo_get_trade_fills` | Account trade (fill) history | | `aevo_get_order_history` | Historical orders | ### Market Data (14 tools) | Tool | Purpose | |------|---------| | `aevo_list_assets` | All supported asset symbols | | `aevo_list_markets` | Markets filtered by asset/type | | `aevo_get_orderbook` | Top 10 bids/asks for an instrument | | `aevo_get_instrument` | Full instrument metadata (tick size, margin, etc.) | | `aevo_get_funding_rate` | Current funding rate for a perpetual | | `aevo_get_funding_history` | Historical funding rates | | `aevo_get_trade_history` | Recent public trades | | `aevo_get_statistics` | Exchange-wide volume and open interest | | `aevo_get_index_price` | Spot reference price for an asset | | `aevo_get_index_history` | Historical index prices | | `aevo_get_mark_history` | Historical mark prices | | `aevo_get_settlement_history` | Settlement history | | `aevo_get_expiries` | Available expiry dates for options/futures | | `aevo_get_server_time` | Exchange server time | ### Order Management (7 tools) | Tool | Purpose | |------|---------| | `aevo_list_orders` | Fetch all open orders | | `aevo_get_order` | Fetch one order by ID | | `aevo_build_order` | Build and sign order payload WITHOUT submitting (dry run) | | `aevo_create_order` | Build, sign, and submit an order | | `aevo_cancel_order` | Cancel a single order | | `aevo_cancel_orders` | Cancel multiple orders by ID | | `aevo_cancel_all_orders` | Cancel ALL open orders (destructive) | ### Analysis (4 tools) | Tool | Purpose | |------|---------| | `aevo_funding_analysis` | Funding rate trend, annualized %, persistence | | `aevo_volatility_snapshot` | Realized vol, IV, vol regime classification | | `aevo_market_regime` | Trend classification (trending/ranging/volatile) with support/resistance | | `aevo_basis_analysis` | Perp-to-spot premium/discount analysis | ### Risk (3 tools) | Tool | Purpose | |------|---------| | `aevo_portfolio_risk` | Aggregate portfolio risk: Greeks, margin utilization, concentration | | `aevo_position_risk` | Per-position risk: liquidation distance, funding cost, equity % | | `aevo_risk_check` | Pre-trade validation: margin impact, slippage, pass/fail | ### Strategy (4 tools) | Tool | Purpose | |------|---------| | `aevo_bracket_order` | Entry + stop-loss + take-profit as a group | | `aevo_close_position` | Close a position with a reduce-only counter-order | | `aevo_options_leg_builder` | Build multi-leg options strategy plan with live prices (dry run) | | `aevo_execute_strategy` | Execute a multi-leg strategy sequentially | ### Registration (1 tool) | Tool | Purpose | |------|---------| | `aevo_register_account` | Register signing key on AEVO and obtain API credentials | ## Instrument Naming AEVO uses a structured naming convention: | Type | Format | Examples | |------|--------|---------| | Perpetual | `{ASSET}-PERP` | `ETH-PERP`, `BTC-PERP` | | Spot | `{ASSET}-USDC` | `ETH-USDC`, `BTC-USDC` | | Option | `{ASSET}-{EXPIRY}-{STRIKE}-{TYPE}` | `ETH-28MAR25-3000-C`, `BTC-28MAR25-100000-P` | - `ASSET`: uppercase ticker symbol (ETH, BTC, SOL, etc.) - `EXPIRY`: DDMMMYY format (28MAR25, 30JUN25) - `STRIKE`: strike price as integer - `TYPE`: `C` for call, `P` for put Options strategies supported by `aevo_options_leg_builder`: straddle, strangle, bull_call_spread, bear_put_spread, iron_condor, butterfly. ## Order Parameters - `amount`: human-readable contracts (e.g., "0.5" = 0.5 contracts). The server converts to AEVO's internal 6-decimal fixed-point format. - `limit_price`: human-readable USD (e.g., "3000" = $3,000). Same auto-conversion applies. - `time_in_force`: "GTC" (Good Til Cancel), "IOC" (Immediate or Cancel), "FOK" (Fill or Kill). - `post_only`: if true, order is rejected if it would trade immediately (maker-only). - `reduce_only`: if true, order can only reduce an existing position. - `stop` / `trigger`: for stop-loss ("STOP_LOSS") and take-profit ("TAKE_PROFIT") orders. ## Prompts The MCP server provides structured prompts for common workflows: - `trade_plan` -- step-by-step trade execution plan - `risk_checklist` -- pre-trade validation checklist - `cancel_plan` -- order cancellation decision flow - `onboarding_plan` -- first-run startup guide - `market_analysis` -- comprehensive market analysis workflow - `portfolio_review` -- portfolio risk analysis with recommendations - `trade_thesis` -- data-driven trade thesis builder - `hedge_advisor` -- hedging strategy recommendations ## Resources Read-only MCP resources for fast context snapshots: - `aevo://status` -- server identity and credential state - `aevo://markets/summary` -- all active markets - `aevo://account/overview` -- account balance and margin - `aevo://funding/snapshot` -- current ETH-PERP funding rate - `aevo://statistics/snapshot` -- exchange-wide statistics ## References For detailed documentation beyond this skill definition, consult these files as needed: **Reference docs** (`references/`): - `references/tools.md` -- Read when you need exact parameter names, types, defaults, or response formats for a specific tool call - `references/options.md` -- Read when constructing any options strategy (straddle, strangle, spread, condor, butterfly) - `references/risk-rules.md` -- Read when evaluating risk thresholds, position limits, session loss limits, or circuit breaker rules - `references/workflows.md` -- Read for step-by-step recipes when you're unsure of the correct tool sequence for a task - `references/instruments.md` -- Read when parsing or constructing instrument names, especially options naming **Conversation examples** (`examples/`): - `examples/analyze.md` -- Full market analysis conversation showing parallel data pulls and synthesis - `examples/trade.md` -- Bracket trade execution with mandatory confirmation flow and stop-loss adjustment - `examples/hedge.md` -- Portfolio hedging workflow from risk identification through collar execution

path: references/workflows.md
content: Common Trading Workflows:

### 1. Session Setup
```
aevo_onboard → check status
  → if unauthenticated: collect credentials → aevo_authenticate
  → aevo_get_account → verify balance
  → aevo_get_positions → check existing exposure
```

### 2. Market Analysis
```
aevo_get_index_price (spot reference)
aevo_market_regime (trend classification)
aevo_funding_analysis (funding trend for perps)
aevo_volatility_snapshot (vol regime)
aevo_basis_analysis (perp premium/discount)
aevo_get_orderbook (liquidity check)
→ Synthesize into market view
```

### 3. Place a Trade
```
1. Analyze: market data + regime + funding
2. Risk check: aevo_risk_check (instrument, side, amount)
3. Set leverage: aevo_update_leverage (if needed)
4. Confirm with user: show trade details + risk assessment
5. Execute: aevo_create_order or aevo_bracket_order
6. Verify: aevo_get_order or aevo_list_orders
```

### 4. Portfolio Review
```
aevo_get_account (balance, equity, margin)
aevo_get_portfolio (PnL, Greeks)
aevo_get_positions (all positions)
aevo_portfolio_risk (aggregate risk)
aevo_position_risk (per-position risk)
→ Synthesize: recommendations, risk alerts, rebalancing suggestions
```

### 5. Close a Position
```
aevo_get_positions → find the position
aevo_get_orderbook → check current prices
aevo_close_position (instrument_name, optional limit_price)
→ Verify position is closed
```

### 6. Cancel Orders
```
Single: aevo_cancel_order(order_id) → verify
Multiple: aevo_cancel_orders(order_ids) → verify
All: aevo_cancel_all_orders (DESTRUCTIVE — confirm with user first)
```

### 7. Options Strategy
```
1. aevo_get_expiries(asset) → pick expiry
2. aevo_list_markets(asset, "OPTION") → find available strikes
3. aevo_volatility_snapshot(asset) → vol context
4. aevo_options_leg_builder(strategy_type, asset, expiry, strikes...) → preview
5. Review max profit/loss, breakevens, Greeks with user
6. aevo_execute_strategy(legs, dry_run=true) → dry run
7. aevo_execute_strategy(legs) → execute (with user confirmation)
```

### 8. Hedge Portfolio
```
aevo_get_positions → current exposure
aevo_portfolio_risk → net Greeks
aevo_volatility_snapshot → vol context
→ Identify delta/vega exposure to hedge
→ Recommend hedge: perp (delta), options (gamma/vega)
→ Use aevo_risk_check on proposed hedge
→ Execute with user confirmation
```


path: references/risk-rules.md
content: Risk Management Rules for AI Trading:

### Pre-Trade Checklist
1. Always call aevo_risk_check before placing any order
2. Verify margin utilization won't exceed 80% post-trade
3. Check liquidation distance is > 10% for leveraged positions
4. Confirm orderbook has sufficient liquidity (check spread and depth via aevo_get_orderbook)

### Position Limits (Recommended Defaults)
- Max position per instrument: $50,000 notional
- Max total exposure: $200,000 notional
- Max leverage: 20x
- Large order threshold: $10,000+ requires explicit user confirmation

### Session Safety
- Track session PnL — halt if loss exceeds $5,000
- Max 10 orders per minute (rate governor)
- 5 consecutive errors → halt all trading (circuit breaker)
- Always confirm with user before placing orders

### Leverage Rules
- Never set leverage higher than user explicitly requests
- Default to lower leverage when user is ambiguous
- Always set leverage BEFORE placing orders (aevo_update_leverage)

### Stop-Loss Policy
- Every leveraged position should have a stop-loss
- Use aevo_bracket_order for entry + SL + TP in one operation
- For existing positions without stops, recommend adding them

### Order Verification
- After placing an order, verify with aevo_list_orders or aevo_get_order
- After cancellation, verify the order is no longer in open orders
- For bracket orders, verify all 3 legs were placed successfully

### Portfolio Monitoring
- Run aevo_portfolio_risk periodically during active sessions
- Alert user if margin utilization > 70%
- Alert user if any position's liquidation distance < 15%


path: references/instruments.md
content: AEVO Instrument Naming Conventions:

### Perpetual Futures
- Format: `{ASSET}-PERP`
- Examples: ETH-PERP, BTC-PERP, SOL-PERP
- Always uppercase

### Options
- Format: `{ASSET}-{DDMMMYY}-{STRIKE}-{C|P}`
- Examples: ETH-28MAR25-3000-C (call), BTC-28MAR25-70000-P (put)
- Date format: day + 3-letter month abbreviation + 2-digit year (all caps)
- C = Call, P = Put
- Strike is integer or decimal

### Spot
- Format: `{ASSET}-{QUOTE}`
- Examples: BTC-USDC, ETH-USDC

### Discovering Instruments
- Use aevo_list_assets to get available assets
- Use aevo_list_markets to find specific instruments (filter by asset and/or instrument_type)
- Use aevo_get_expiries to find valid expiry dates for options
- Use aevo_get_instrument to get full metadata (tick size, min order, margin requirements)

### Common instrument_type values
- PERPETUAL
- OPTION
- SPOT


path: references/options.md
content: Options Strategy Reference:

### Supported Strategies

#### Straddle (Long)
- **Outlook**: Expecting big move, direction unknown
- **Legs**: Buy 1 ATM Call + Buy 1 ATM Put (same strike, same expiry)
- **Max Loss**: Total premium paid
- **Max Profit**: Unlimited (upside) / Strike - premium (downside)
- **Breakeven**: Strike ± total premium
- **Use when**: Expecting volatility spike (earnings, macro events)

#### Strangle (Long)
- **Outlook**: Expecting big move, cheaper than straddle
- **Legs**: Buy 1 OTM Call + Buy 1 OTM Put (different strikes)
- **Max Loss**: Total premium paid
- **Max Profit**: Unlimited
- **Breakeven**: Call strike + premium / Put strike - premium
- **Use when**: Want convexity with less upfront cost

#### Bull Call Spread
- **Outlook**: Moderately bullish
- **Legs**: Buy 1 Call (lower strike) + Sell 1 Call (upper strike)
- **Max Loss**: Net premium paid
- **Max Profit**: Strike difference - net premium
- **Breakeven**: Lower strike + net premium
- **Use when**: Bullish but want to cap cost

#### Bear Put Spread
- **Outlook**: Moderately bearish
- **Legs**: Buy 1 Put (upper strike) + Sell 1 Put (lower strike)
- **Max Loss**: Net premium paid
- **Max Profit**: Strike difference - net premium
- **Breakeven**: Upper strike - net premium
- **Use when**: Bearish but want to cap cost

#### Iron Condor
- **Outlook**: Range-bound, low volatility expected
- **Legs**: Buy OTM Put (far) + Sell OTM Put + Sell OTM Call + Buy OTM Call (far)
- **Max Loss**: Width of wider spread - net credit
- **Max Profit**: Net credit received
- **Breakeven**: Short put - credit / Short call + credit
- **Use when**: Expecting price to stay in range, selling volatility

#### Butterfly
- **Outlook**: Price stays near a specific level
- **Legs**: Buy 1 Call (lower) + Sell 2 Calls (middle) + Buy 1 Call (upper)
- **Max Loss**: Net premium paid
- **Max Profit**: Middle strike - lower strike - net premium
- **Breakeven**: Lower + premium / Upper - premium
- **Use when**: High conviction on a price target

### Using the Tools
1. **Plan**: `aevo_options_leg_builder` — builds strategy with live premiums (read-only)
2. **Preview**: `aevo_execute_strategy` with `dry_run=true` — validates without executing
3. **Execute**: `aevo_execute_strategy` with `dry_run=false` — places real orders
4. **Close**: Use `aevo_close_position` for each leg, or `aevo_cancel_all_orders` for unfilled legs

### Greeks Quick Reference
- **Delta**: Sensitivity to underlying price. Calls: 0 to 1, Puts: -1 to 0
- **Gamma**: Rate of delta change. Highest ATM near expiry
- **Theta**: Time decay. Options lose value daily (negative for buyers)
- **Vega**: Sensitivity to implied volatility. Highest ATM, longer expiry


path: references/tools.md
content: # AEVO MCP Tools Reference

Complete reference for all 45 AEVO MCP tools. Tools are grouped by category with authentication requirements, parameters, and usage examples.

**Parameter defaults:** `""` means empty string (optional/omitted), numeric defaults shown as values, boolean defaults shown as `true`/`false`.

---

## Market Data (14 tools)

All market data tools are **public** -- no authentication required.

### aevo_list_assets

List all supported assets on the exchange.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| *(none)* | | | | |

```
aevo_list_assets()
# Returns: ["ETH", "BTC", "SOL", ...]
```

---

### aevo_list_markets

List available markets, optionally filtered by asset or instrument type.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | `""` | No | Filter by asset (e.g. `"ETH"`) |
| instrument_type | string | `""` | No | Filter by type (e.g. `"PERPETUAL"`, `"OPTION"`, `"FUTURE"`) |

```
aevo_list_markets(asset="ETH", instrument_type="PERPETUAL")
```

---

### aevo_get_orderbook

Retrieve the top 10 bids and asks for an instrument.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument name (e.g. `"ETH-PERP"`) |

```
aevo_get_orderbook(instrument_name="ETH-PERP")
# Returns: { bids: [[price, size], ...], asks: [[price, size], ...] }
```

---

### aevo_get_instrument

Full instrument metadata including tick size, min order size, and contract specs.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument name or numeric ID |

```
aevo_get_instrument(instrument_name="ETH-PERP")
aevo_get_instrument(instrument_name="12345")
```

---

### aevo_get_funding_rate

Current funding rate for a perpetual contract.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Perpetual instrument name (e.g. `"ETH-PERP"`) |

```
aevo_get_funding_rate(instrument_name="ETH-PERP")
# Returns: current hourly funding rate
```

---

### aevo_get_funding_history

Historical funding rates for a perpetual contract.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Perpetual instrument name |
| start_time | string | `""` | No | Start timestamp (unix seconds) |
| end_time | string | `""` | No | End timestamp (unix seconds) |
| limit | string | `"50"` | No | Number of records to return |
| offset | string | `""` | No | Pagination offset |

```
aevo_get_funding_history(instrument_name="ETH-PERP", limit="100")
```

---

### aevo_get_trade_history

Recent public trades for an instrument.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument name |

```
aevo_get_trade_history(instrument_name="ETH-PERP")
# Returns: list of recent trades with price, size, side, timestamp
```

---

### aevo_get_statistics

Exchange-wide statistics (volume, open interest, etc.).

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| *(none)* | | | | |

```
aevo_get_statistics()
```

---

### aevo_get_index_price

Spot reference (index) price for an asset.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | | **Yes** | Asset symbol (e.g. `"ETH"`) |

```
aevo_get_index_price(asset="ETH")
# Returns: current spot index price
```

---

### aevo_get_index_history

Historical index (spot reference) prices for an asset.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | | **Yes** | Asset symbol |
| resolution | string | `""` | No | Candle resolution (e.g. `"1h"`, `"1d"`) |
| start_time | string | `""` | No | Start timestamp (unix seconds) |
| end_time | string | `""` | No | End timestamp (unix seconds) |
| limit | string | `"50"` | No | Number of records |

```
aevo_get_index_history(asset="BTC", resolution="1h", limit="24")
```

---

### aevo_get_mark_history

Historical mark prices for an instrument.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument name |
| resolution | string | `""` | No | Candle resolution |
| start_time | string | `""` | No | Start timestamp (unix seconds) |
| end_time | string | `""` | No | End timestamp (unix seconds) |
| limit | string | `"50"` | No | Number of records |

```
aevo_get_mark_history(instrument_name="ETH-PERP", resolution="1d", limit="30")
```

---

### aevo_get_settlement_history

Settlement history for options/futures.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | `""` | No | Filter by asset |
| start_time | string | `""` | No | Start timestamp (unix seconds) |
| end_time | string | `""` | No | End timestamp (unix seconds) |
| limit | string | `"50"` | No | Number of records |

```
aevo_get_settlement_history(asset="ETH", limit="10")
```

---

### aevo_get_expiries

Available expiry dates for options and futures on an asset.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | | **Yes** | Asset symbol (e.g. `"ETH"`) |

```
aevo_get_expiries(asset="ETH")
# Returns: list of available expiry timestamps
```

---

### aevo_get_server_time

Current exchange server time.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| *(none)* | | | | |

```
aevo_get_server_time()
# Returns: server timestamp in unix seconds
```

---

## Account & Auth (10 tools)

### aevo_onboard

Start or resume an onboarding session. Returns current status and recommended next steps.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| *(none)* | | | | |

**Auth required:** No

```
aevo_onboard()
# Returns: { status: "...", next_steps: [...] }
```

---

### aevo_get_status

Runtime and identity context -- shows current session state, environment, and whether credentials are loaded.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| *(none)* | | | | |

**Auth required:** No

```
aevo_get_status()
```

---

### aevo_authenticate

Store session credentials for subsequent authenticated calls. Does not make an API call itself.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| api_key | string | `""` | No | API key |
| api_secret | string | `""` | No | API secret |
| wallet_address | string | `""` | No | Ethereum wallet address |
| wallet_private_key | string | `""` | No | Wallet private key (for signing) |
| signing_key_private_key | string | `""` | No | Signing key private key |

**Auth required:** No (this tool *stores* credentials)

```
aevo_authenticate(
    [REDACTED_SECRET]",
    api_secret="as-...",
    signing_key_private_key="0x..."
)
```

---

### aevo_clear_auth

Clear all stored session credentials.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| *(none)* | | | | |

**Auth required:** No

```
aevo_clear_auth()
```

---

### aevo_get_account

Account summary including balance, equity, available margin, and margin usage.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes

```
aevo_get_account()
```

---

### aevo_get_portfolio

Portfolio summary with PnL, Greeks, and position aggregates.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes

```
aevo_get_portfolio()
# Returns: { pnl, greeks: { delta, gamma, theta, vega }, ... }
```

---

### aevo_get_positions

List all open positions.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes

```
aevo_get_positions()
# Returns: list of open positions with instrument, size, entry price, PnL
```

---

### aevo_update_leverage

Update leverage for a specific instrument.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument name (e.g. `"ETH-PERP"`) |
| leverage | integer | | **Yes** | New leverage value |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes

```
aevo_update_leverage(instrument_name="ETH-PERP", leverage=5)
```

---

### aevo_get_trade_fills

Account trade fill history with filtering.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| start_time | string | `""` | No | Start timestamp (unix seconds) |
| end_time | string | `""` | No | End timestamp (unix seconds) |
| limit | string | `"50"` | No | Number of records |
| offset | string | `""` | No | Pagination offset |
| trade_types | string | `""` | No | Filter by trade type |
| instrument_name | string | `""` | No | Filter by instrument |
| instrument_type | string | `""` | No | Filter by instrument type |
| asset | string | `""` | No | Filter by asset |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes

```
aevo_get_trade_fills(instrument_name="ETH-PERP", limit="20")
```

---

### aevo_get_order_history

Account order history with the same filtering options as trade fills.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| start_time | string | `""` | No | Start timestamp (unix seconds) |
| end_time | string | `""` | No | End timestamp (unix seconds) |
| limit | string | `"50"` | No | Number of records |
| offset | string | `""` | No | Pagination offset |
| trade_types | string | `""` | No | Filter by trade type |
| instrument_name | string | `""` | No | Filter by instrument |
| instrument_type | string | `""` | No | Filter by instrument type |
| asset | string | `""` | No | Filter by asset |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes

```
aevo_get_order_history(asset="ETH", limit="50")
```

---

## Order Management (7 tools)

All order management tools require **authentication**.

### aevo_list_orders

List all currently open orders.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

```
aevo_list_orders()
```

---

### aevo_get_order

Retrieve a single order by its ID.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| order_id | string | | **Yes** | Order ID to look up |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

```
aevo_get_order(order_id="0xabc123...")
```

---

### aevo_build_order

Build and sign an order **without submitting** it. Useful for preview, dry-run, or multi-step workflows.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument to trade |
| is_buy | boolean | | **Yes** | `true` for buy, `false` for sell |
| amount | string | | **Yes** | Order size |
| limit_price | string | | **Yes** | Limit price |
| salt | string | `""` | No | Custom salt for order uniqueness |
| order_timestamp | integer | `0` | No | Custom timestamp |
| post_only | boolean | `false` | No | Post-only (maker) order |
| reduce_only | boolean | `false` | No | Reduce-only order |
| time_in_force | string | `"GTC"` | No | `"GTC"`, `"IOC"`, `"FOK"` |
| mmp | boolean | `false` | No | Market maker protection |
| stop | string | `""` | No | Stop type |
| trigger | string | `""` | No | Trigger price for stop orders |
| close_position | boolean | `false` | No | Close entire position |
| partial_position | boolean | `false` | No | Allow partial fill of position close |

```
aevo_build_order(
    instrument_name="ETH-PERP",
    is_buy=true,
    amount="0.1",
    limit_price="3000"
)
# Returns: signed order payload (not submitted)
```

---

### aevo_create_order

Build, sign, and **submit** an order to the exchange. **CAUTION: This places a real order.**

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument to trade |
| is_buy | boolean | | **Yes** | `true` for buy, `false` for sell |
| amount | string | | **Yes** | Order size |
| limit_price | string | | **Yes** | Limit price |
| salt | string | `""` | No | Custom salt |
| order_timestamp | integer | `0` | No | Custom timestamp |
| post_only | boolean | `false` | No | Post-only (maker) order |
| reduce_only | boolean | `false` | No | Reduce-only order |
| time_in_force | string | `"GTC"` | No | `"GTC"`, `"IOC"`, `"FOK"` |
| mmp | boolean | `false` | No | Market maker protection |
| stop | string | `""` | No | Stop type |
| trigger | string | `""` | No | Trigger price |
| close_position | boolean | `false` | No | Close entire position |
| partial_position | boolean | `false` | No | Allow partial fill |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

```
aevo_create_order(
    instrument_name="ETH-PERP",
    is_buy=true,
    amount="0.1",
    limit_price="3000",
    post_only=true
)
# WARNING: Places a real order on the exchange
```

---

### aevo_cancel_order

Cancel a single open order by its ID.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| order_id | string | | **Yes** | Order ID to cancel |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

```
aevo_cancel_order(order_id="0xabc123...")
```

---

### aevo_cancel_orders

Cancel multiple orders by their IDs.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| order_ids | list[string] | | **Yes** | List of order IDs to cancel |
| instrument_type | string | `""` | No | Filter by instrument type |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

```
aevo_cancel_orders(order_ids=["0xabc...", "0xdef..."])
```

---

### aevo_cancel_all_orders

Cancel **ALL** open orders. Optionally filter by asset or instrument type. **DESTRUCTIVE: cancels everything matching the filter (or all orders if no filter).**

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | `""` | No | Cancel only orders for this asset |
| instrument_type | string | `""` | No | Cancel only orders of this type |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

```
aevo_cancel_all_orders()                          # Cancel everything
aevo_cancel_all_orders(asset="ETH")               # Cancel all ETH orders
aevo_cancel_all_orders(instrument_type="OPTION")  # Cancel all option orders
```

---

## Analysis (4 tools)

All analysis tools are **read-only** and require **no authentication**. They aggregate market data into actionable insights.

### aevo_funding_analysis

Funding rate trend analysis for a perpetual contract.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Perpetual instrument name (e.g. `"ETH-PERP"`) |

**Returns:** Current rate, 7-day average, annualized percentage, percentile ranking, trend direction, persistence metric.

```
aevo_funding_analysis(instrument_name="ETH-PERP")
# Returns: {
#   current_rate, avg_7d, annualized_pct,
#   percentile, trend, persistence
# }
```

---

### aevo_volatility_snapshot

Realized volatility and implied volatility snapshot for an asset.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | | **Yes** | Asset symbol (e.g. `"ETH"`) |

**Returns:** 7-day and 30-day realized volatility, ATM implied volatility, regime classification.

```
aevo_volatility_snapshot(asset="ETH")
# Returns: {
#   realized_vol_7d, realized_vol_30d,
#   atm_iv, regime
# }
```

---

### aevo_market_regime

Market regime classification based on price action analysis.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | | **Yes** | Asset symbol (e.g. `"BTC"`) |

**Returns:** Regime (`trending_up`, `trending_down`, `ranging`, `volatile`), confidence score, support level, resistance level.

```
aevo_market_regime(asset="BTC")
# Returns: {
#   regime: "trending_up", confidence: 0.82,
#   support: 62000, resistance: 68000
# }
```

---

### aevo_basis_analysis

Perpetual-to-spot basis analysis showing premium or discount.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| asset | string | | **Yes** | Asset symbol (e.g. `"ETH"`) |

**Returns:** Premium/discount in basis points, annualized percentage, 7-day statistics, percentile ranking.

```
aevo_basis_analysis(asset="ETH")
# Returns: {
#   basis_bps, annualized_pct,
#   stats_7d: { min, max, avg },
#   percentile
# }
```

---

## Risk (3 tools)

All risk tools require **authentication**.

### aevo_portfolio_risk

Aggregate portfolio risk metrics.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Returns:** Net Greeks (delta, gamma, theta, vega), margin utilization percentage, liquidation distance, position concentration breakdown.

```
aevo_portfolio_risk()
# Returns: {
#   net_delta, net_gamma, net_theta, net_vega,
#   margin_pct, liquidation_distance, concentration
# }
```

---

### aevo_position_risk

Per-position risk detail. If no instrument specified, returns risk for all positions.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | `""` | No | Filter to a specific instrument |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Returns:** PnL, equity percentage, liquidation distance, funding cost, time decay (theta).

```
aevo_position_risk(instrument_name="ETH-PERP")
# Returns: {
#   pnl, equity_pct, liquidation_distance,
#   funding_cost, time_decay
# }
```

---

### aevo_risk_check

Pre-trade risk validation. Simulates the impact of a hypothetical trade **without placing an order**.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument to simulate |
| side | string | | **Yes** | `"buy"` or `"sell"` |
| amount | string | | **Yes** | Trade size |
| limit_price | string | `""` | No | Price to simulate at (uses mark if omitted) |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Returns:** Post-trade margin usage, delta change, estimated slippage, pass/fail verdict.

```
aevo_risk_check(
    instrument_name="ETH-PERP",
    side="buy",
    amount="1.0",
    limit_price="3000"
)
# Returns: {
#   post_trade_margin_pct, delta_change,
#   slippage_bps, verdict: "pass"
# }
```

---

## Strategy (4 tools)

### aevo_bracket_order

Place an entry order with attached stop-loss and take-profit orders. **CAUTION: Places real orders.**

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument to trade |
| is_buy | boolean | | **Yes** | `true` for long entry, `false` for short entry |
| amount | string | | **Yes** | Order size |
| entry_price | string | | **Yes** | Entry limit price |
| stop_loss_price | string | | **Yes** | Stop-loss trigger price |
| take_profit_price | string | | **Yes** | Take-profit trigger price |
| time_in_force | string | `"GTC"` | No | Time in force for all legs |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes

```
aevo_bracket_order(
    instrument_name="ETH-PERP",
    is_buy=true,
    amount="0.5",
    entry_price="3000",
    stop_loss_price="2900",
    take_profit_price="3200"
)
# WARNING: Places 3 real orders (entry + SL + TP)
```

---

### aevo_close_position

Close an existing position via a reduce-only order. **CAUTION: Places a real order.**

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| instrument_name | string | | **Yes** | Instrument with open position |
| limit_price | string | `""` | No | Limit price (uses market if omitted) |
| time_in_force | string | `"GTC"` | No | Time in force |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes

```
aevo_close_position(instrument_name="ETH-PERP")
# WARNING: Closes your entire ETH-PERP position
```

---

### aevo_options_leg_builder

Build an options strategy plan with live premiums. **Read-only -- does NOT execute any trades.**

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| strategy_type | string | | **Yes** | One of: `straddle`, `strangle`, `bull_call_spread`, `bear_put_spread`, `iron_condor`, `butterfly` |
| asset | string | | **Yes** | Underlying asset (e.g. `"ETH"`) |
| expiry | string | | **Yes** | Expiry date |
| strike | string | `""` | No | Strike price (for straddle) |
| lower_strike | string | `""` | No | Lower strike (for strangle) |
| upper_strike | string | `""` | No | Upper strike (for strangle) |
| put_strike | string | `""` | No | Put strike |
| call_strike | string | `""` | No | Call strike |
| put_buy_strike | string | `""` | No | Put buy strike (for iron condor) |
| put_sell_strike | string | `""` | No | Put sell strike (for iron condor) |
| call_sell_strike | string | `""` | No | Call sell strike (for iron condor) |
| call_buy_strike | string | `""` | No | Call buy strike (for iron condor) |
| amount | string | `"1"` | No | Number of contracts per leg |

**Auth required:** No

```
aevo_options_leg_builder(
    strategy_type="straddle",
    asset="ETH",
    expiry="2026-03-28",
    strike="3000"
)
# Returns: leg breakdown with live premiums, net debit/credit, max profit/loss
```

---

### aevo_execute_strategy

Execute a multi-leg options or futures strategy. **CAUTION: Places real orders unless `dry_run=true`.**

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| legs | list[dict] | | **Yes** | List of leg definitions (instrument, side, amount, price) |
| dry_run | boolean | `false` | No | If `true`, simulate only -- no orders placed |
| time_in_force | string | `"GTC"` | No | Time in force for all legs |
| api_key | string | `""` | No | Override stored API key |
| api_secret | string | `""` | No | Override stored API secret |

**Auth required:** Yes (unless `dry_run=true`)

```
# Dry run (safe)
aevo_execute_strategy(
    legs=[
        {"instrument_name": "ETH-20260328-3000-C", "is_buy": true, "amount": "1", "limit_price": "150"},
        {"instrument_name": "ETH-20260328-3000-P", "is_buy": true, "amount": "1", "limit_price": "140"}
    ],
    dry_run=true
)

# Live execution (REAL ORDERS)
aevo_execute_strategy(
    legs=[
        {"instrument_name": "ETH-20260328-3000-C", "is_buy": true, "amount": "1", "limit_price": "150"},
        {"instrument_name": "ETH-20260328-3000-P", "is_buy": true, "amount": "1", "limit_price": "140"}
    ]
)
```

---

## System (2 tools)

Both system tools are **public** -- no authentication required.

### aevo_ping

Simple health check / liveness probe.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| *(none)* | | | | |

```
aevo_ping()
# Returns: "pong" or equivalent
```

---

### aevo_healthcheck

Verify connectivity to the AEVO API and confirm the service is operational.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| *(none)* | | | | |

```
aevo_healthcheck()
# Returns: connectivity status and latency
```

---

## Registration (1 tool)

### aevo_register_account

Register a signing key with the exchange and obtain API credentials. Requires wallet and signing key private keys to be set via `aevo_authenticate` first.

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| key_expiry | string | `""` | No | Signing key expiry timestamp |
| no_api_key | boolean | `false` | No | If `true`, skip API key generation |
| referral_code | string | `""` | No | Referral code |
| wallet_address | string | `""` | No | Override wallet address |
| store_credentials | boolean | `true` | No | Auto-store returned credentials in session |

**Auth required:** Requires wallet + signing key private keys (set via `aevo_authenticate`)

```
# First, set wallet credentials
aevo_authenticate(
    wallet_address="0x...",
    wallet_private_key="0x...",
    signing_key_private_key="0x..."
)

# Then register
aevo_register_account(referral_code="MYREF")
# Returns: API key, API secret (auto-stored if store_credentials=true)
```

---

## Quick Reference: Tool Count by Category

| Category | Count | Auth Required |
|----------|-------|---------------|
| Market Data | 14 | No |
| Account & Auth | 10 | Mixed (5 yes, 5 no) |
| Order Management | 7 | Yes |
| Analysis | 4 | No |
| Risk | 3 | Yes |
| Strategy | 4 | Mixed (3 yes, 1 no) |
| System | 2 | No |
| Registration | 1 | Wallet keys required |
| **Total** | **45** | |

> **Note:** The 45 total includes 4 Analysis tools and 4 Strategy tools that are composite/analytical wrappers built on top of the base exchange API.


path: .claude/settings.local.json
content: {
  "permissions": {
    "allow": [
      "WebFetch(domain:support.claude.com)"
    ]
  }
}


path: README.md
content: # AEVO Trading Skill

AI trading assistant skill for [AEVO](https://app.aevo.xyz), a decentralized derivatives exchange. Connects any MCP-compatible client to AEVO's 45 tools for market data, portfolio management, order execution, risk analysis, and options strategies.

## Quick Start

### Option 1: Claude Desktop / Claude Code (Direct MCP)

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "aevo": {
      "command": "uvx",
      "args": ["mcp-aevo-server"],
      "env": {
        "AEVO_API_KEY": "your-api-key",
        "AEVO_API_SECRET": "your-api-secret",
        "AEVO_WALLET_ADDRESS": "0x...",
        "AEVO_SIGNING_KEY_PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

Or connect to AEVO's hosted MCP endpoint (no local server needed):

```json
{
  "mcpServers": {
    "aevo": {
      "url": "https://mcp.aevo.xyz/mcp",
      "headers": {
        "AEVO-KEY": "your-api-key",
        "AEVO-SECRET": "your-api-secret"
      }
    }
  }
}
```

### Option 2: OpenClaw

```bash
clawhub install aevo
```

Then in your OpenClaw config, add your AEVO credentials as environment variables.

### Option 3: Any MCP Client (Cursor, Windsurf, etc.)

Point your MCP client to AEVO's hosted endpoint:

- **Mainnet**: `https://mcp.aevo.xyz/mcp`
- **Testnet**: `https://mcp-testnet.aevo.xyz/mcp`

Authenticate via `AEVO-KEY` and `AEVO-SECRET` headers, or call `aevo_authenticate` after connecting.

## Getting Your Credentials

1. Go to [app.aevo.xyz/settings](https://app.aevo.xyz/settings)
2. Create an API key (gives you `api_key` + `api_secret`)
3. For trading: you also need your `wallet_address` and `signing_key_private_key`

### Credential Tiers

| Tier | Credentials | Access |
|------|------------|--------|
| Read-only | `api_key` + `api_secret` | Account data, positions, history |
| Trading | + `wallet_address` + `signing_key_private_key` | Orders, cancellations, strategies |

## What You Can Do

- **Market Analysis**: Real-time prices, funding rates, volatility snapshots, market regime classification
- **Portfolio Management**: Positions, risk metrics, Greeks, margin monitoring
- **Order Execution**: Limit orders, bracket orders (entry + SL + TP), batch operations
- **Options Strategies**: Straddles, strangles, spreads, iron condors, butterflies with live pricing
- **Risk Management**: Pre-trade validation, portfolio risk scoring, liquidation distance monitoring

## File Structure

```
SKILL.md              # Core skill definition (what the LLM reads)
README.md             # This file
references/
  tools.md            # All 45 tools with parameters and examples
  instruments.md      # Instrument naming conventions
  risk-rules.md       # Risk guardrails and safety rules
  workflows.md        # Step-by-step workflow recipes
  options.md          # Options strategy reference
examples/
  analyze.md          # Market analysis conversation
  trade.md            # Bracket trade conversation
  hedge.md            # Portfolio hedge conversation
```

## Testnet

For testing without real funds, use AEVO testnet:

- App: [testnet.aevo.xyz](https://testnet.aevo.xyz)
- API: `https://api-testnet.aevo.xyz`
- MCP: `https://mcp-testnet.aevo.xyz/mcp`

## Links

- [AEVO Exchange](https://aevo.xyz)
- [AEVO API Docs](https://docs.aevo.xyz)
- [MCP Server Package](https://pypi.org/project/mcp-aevo-server/)


path: examples/analyze.md
content: # Example: Market Analysis

A comprehensive ETH market analysis using multiple data sources to build a synthesized view.

---

**User**: What's the current state of ETH?

**Assistant**: Let me pull together a full market picture for ETH. I'll check price, trend, funding, volatility, and basis all at once.

*[calls aevo_onboard to verify session]*

Session is active. Pulling market data now.

*[calls in parallel: aevo_get_index_price(asset="ETH"), aevo_market_regime(asset="ETH"), aevo_funding_analysis(instrument_name="ETH-PERP"), aevo_volatility_snapshot(asset="ETH"), aevo_basis_analysis(asset="ETH")]*

Here's my ETH market analysis:

---

**Price**: $2,450.32 (index/spot reference)

**Market Regime**: Trending Up (72% confidence)
- 24h change: +3.2%
- Support zone: ~$2,380 (prior consolidation area)
- Resistance zone: ~$2,520 (recent rejection level)
- Trend has been intact for ~5 days with higher lows on the 4h timeframe

**Funding Rate**: Mildly Positive
- Current 8h rate: +0.0065% (annualized ~8.5%)
- 7-day average: +0.0048%
- Interpretation: Longs are paying shorts, but the rate is moderate — not overheated. Market positioning is net long but not at extreme levels.

**Volatility Snapshot**:
- 30-day realized vol: 52%
- ATM implied vol (front expiry): 58%
- Vol term structure: Contango (front 58% vs back 54%)
- Vol regime: Normal — not elevated, not suppressed
- IV vs RV spread: +6 points, implying options are slightly rich relative to recent movement

**Basis Analysis**:
- Perp premium: +0.12% above spot
- Front-month futures: +0.28% (annualized ~14%)
- Basis is positive and healthy, consistent with the bullish regime. No signs of backwardation or stress.

---

**Synthesis**:

ETH is in a mild uptrend with constructive momentum. Funding is positive but not extreme, which means the trend has room to continue without a funding squeeze. Volatility is normal — realized is tracking around 52% and implied is pricing a small premium, so options aren't screaming cheap or expensive.

**Actionable takeaways**:
1. **Directional bias**: Mildly bullish. Trend favors longs above $2,380 support.
2. **Perp positioning**: Funding cost is manageable (~8.5% annualized). Holding a long perp is viable but monitor for funding spikes above 0.01%.
3. **Options angle**: With IV slightly above RV, selling premium (covered calls or put spreads) has a small edge. If you're looking to get long via options, buying calls is slightly expensive relative to realized.
4. **Key risk**: A break below $2,380 would invalidate the uptrend and likely trigger a flush toward $2,280.

Want me to dive deeper into any of these areas, or would you like to look at a specific trade?

---

**User**: How about BTC? Is it correlated with ETH right now?

**Assistant**: Let me pull the same analysis for BTC so we can compare.

*[calls in parallel: aevo_get_index_price(asset="BTC"), aevo_market_regime(asset="BTC"), aevo_funding_analysis(instrument_name="BTC-PERP"), aevo_volatility_snapshot(asset="BTC")]*

**BTC Snapshot**: $67,240

**Market Regime**: Range-Bound (64% confidence)
- 24h change: +0.8%
- Range: $65,500 - $69,000
- BTC has been consolidating for ~10 days while ETH has been trending up

**Funding**: Near neutral (+0.0022%), much lower than ETH. Positioning is balanced.

**Volatility**: 30-day RV at 42%, ATM IV at 48%. Similar IV-RV spread to ETH but lower absolute vol.

**Correlation context**: ETH is outperforming BTC over the past week — the ETH/BTC ratio has been climbing. This divergence is notable: ETH is trending while BTC consolidates. Historically, this either resolves with BTC catching up (bullish), or ETH pulling back to re-correlate (bearish for ETH).

**Takeaway**: If you're bullish ETH, the relative strength vs BTC is encouraging. But be aware that a BTC breakdown below $65,500 would likely drag ETH down regardless of its own trend.


path: examples/trade.md
content: # Example: Bracket Trade

Placing a long ETH-PERP position with stop-loss and take-profit using a bracket order. Demonstrates the mandatory confirmation flow before order execution.

---

**User**: I want to long 0.5 ETH-PERP at $2,450 with a stop at $2,380 and TP at $2,600.

**Assistant**: Got it. Before placing this order, let me run a risk check on the proposed trade.

*[calls aevo_risk_check(instrument_name="ETH-PERP", side="buy", amount=0.5, price=2450)]*

Here's the risk assessment for your proposed trade:

| Detail | Value |
|---|---|
| **Instrument** | ETH-PERP |
| **Side** | Long |
| **Size** | 0.5 ETH |
| **Entry price** | $2,450.00 (limit) |
| **Notional** | $1,225.00 |
| **Stop-loss** | $2,380.00 (-2.86%) |
| **Take-profit** | $2,600.00 (+6.12%) |
| **Max loss** | $35.00 (at stop) |
| **Max profit** | $75.00 (at TP) |
| **Risk/reward** | 1 : 2.14 |
| **Post-trade margin utilization** | 18.4% (from 12.1%) |
| **Liquidation distance** | >40% (healthy) |

Risk check passed. No guardrail violations.

**Shall I place this bracket order?** (entry + stop-loss + take-profit)

---

**User**: Yes, go ahead.

**Assistant**: Placing the bracket order now.

*[calls aevo_bracket_order(instrument_name="ETH-PERP", side="buy", amount=0.5, limit_price=2450, stop_loss=2380, take_profit=2600)]*

Bracket order submitted. Let me verify all three legs.

*[calls aevo_list_orders(instrument_name="ETH-PERP")]*

All 3 legs confirmed:

| Leg | Type | Price | Status |
|---|---|---|---|
| **Entry** | Limit Buy | $2,450.00 | Open (resting) |
| **Stop-loss** | Stop Market Sell | $2,380.00 | Pending (triggers on entry fill) |
| **Take-profit** | Limit Sell | $2,600.00 | Pending (triggers on entry fill) |

**Summary**: Your long 0.5 ETH-PERP bracket order is live. The entry is resting at $2,450. Once filled, the stop-loss at $2,380 and take-profit at $2,600 will activate automatically.

- If ETH drops to $2,380 first: you lose ~$35
- If ETH reaches $2,600 first: you gain ~$75
- Risk/reward: 1 : 2.14

I'll keep an eye on this. Want me to check the orderbook depth at $2,450, or is there anything else?

---

**User**: Actually, can you tighten the stop to $2,420?

**Assistant**: Let me cancel the existing stop-loss and replace it. First, let me check the current orders.

*[calls aevo_list_orders(instrument_name="ETH-PERP")]*

Found the stop-loss order. I'll cancel and replace it.

*[calls aevo_cancel_order(order_id="0xabc123...stop_order_id")]*

Stop-loss cancelled. Now placing the updated stop.

Before I do, here's how this changes your risk profile:

| Detail | Old | New |
|---|---|---|
| **Stop-loss** | $2,380 (-2.86%) | $2,420 (-1.22%) |
| **Max loss** | $35.00 | $15.00 |
| **Risk/reward** | 1 : 2.14 | 1 : 5.0 |

The tighter stop reduces your max loss to $15 but increases the chance of getting stopped out on normal volatility. ETH's recent intraday range has been ~$40-60, so a $30 stop is fairly tight.

**Want me to proceed with the $2,420 stop?**

---

**User**: Yes.

**Assistant**: *[calls aevo_create_order(instrument_name="ETH-PERP", side="sell", amount=0.5, trigger_price=2420, order_type="stop_market", reduce_only=true)]*

*[calls aevo_list_orders(instrument_name="ETH-PERP")]*

Updated stop-loss confirmed:

| Leg | Type | Price | Status |
|---|---|---|---|
| **Entry** | Limit Buy | $2,450.00 | Open (resting) |
| **Stop-loss** | Stop Market Sell | $2,420.00 | Pending |
| **Take-profit** | Limit Sell | $2,600.00 | Pending |

New risk/reward is 1 : 5.0. Your bracket is live with the tighter stop. Just be aware of the higher stop-out probability given current volatility.


path: examples/hedge.md
content: # Example: Portfolio Hedge

Analyzing portfolio risk and executing a hedge to reduce directional exposure. Shows the full workflow from risk identification through hedge execution.

---

**User**: I'm feeling overexposed. Can you check my portfolio and suggest a hedge?

**Assistant**: Let me pull up your positions and run a full risk analysis.

*[calls in parallel: aevo_get_positions(), aevo_portfolio_risk()]*

Here's your current portfolio:

**Positions**:
| Instrument | Side | Size | Entry Price | Mark Price | Unrealized PnL |
|---|---|---|---|---|---|
| ETH-PERP | Long | 2.0 ETH | $2,380.00 | $2,455.00 | +$150.00 |
| ETH-28MAR25-3000-C | Long | 5 contracts | $82.00 | $95.50 | +$67.50 |
| BTC-PERP | Long | 0.05 BTC | $66,800 | $67,240 | +$22.00 |

**Aggregate Risk**:
| Metric | Value |
|---|---|
| **Total notional** | $8,272 |
| **Net delta (ETH-equivalent)** | +3.8 ETH (~$9,329 delta exposure) |
| **Net gamma** | +0.0012 |
| **Net vega** | +$42.00 |
| **Margin utilization** | 34% |
| **Session PnL** | +$239.50 |

**Risk Assessment**: You're significantly long delta on ETH — between the perp and the calls, you have about 3.8 ETH of directional exposure. The BTC perp adds a small correlated long on top. Your portfolio will lose roughly $380 for every 1% drop in ETH.

Let me check the volatility environment to determine the best hedging approach.

*[calls aevo_volatility_snapshot(asset="ETH")]*

**Vol Context**: ATM IV is 58%, RV is 52%. IV is slightly elevated. This matters because:
- Buying puts is somewhat expensive right now (you'd be buying rich vol)
- Selling the perp is delta-neutral and vol-agnostic

**Hedge Options**:

| Strategy | Instrument | Cost | Effect |
|---|---|---|---|
| **A. Short perp** | Sell 1.5 ETH-PERP | No premium (margin only) | Reduces net delta to ~2.3 ETH. Clean, simple, no time decay. |
| **B. Buy puts** | Buy 5x ETH-28MAR25-2300-P | ~$155 premium | Adds downside protection below $2,300. Keeps upside intact. But IV is rich, so you overpay slightly. |
| **C. Collar** | Sell 5x ETH-28MAR25-2800-C + Buy 5x ETH-28MAR25-2200-P | ~$20 net credit | Caps upside at $2,800 but gives free downside protection below $2,200. |

My recommendation: **Option A (short perp)** is the cleanest hedge if you just want to reduce delta. If you want to keep the upside but add crash protection, **Option C (collar)** is cost-effective since IV is elevated — you collect more from selling calls.

Which approach interests you, or would you like me to model a different hedge?

---

**User**: Let's go with the collar. Can you build it out?

**Assistant**: Let me build the collar legs and show you the full picture.

*[calls aevo_get_expiries(asset="ETH")]*

Using the 28MAR25 expiry to match your existing calls. Let me construct the legs.

*[calls aevo_options_leg_builder(strategy_type="collar", asset="ETH", expiry="28MAR25", long_put_strike=2200, short_call_strike=2800, quantity=5)]*

Here's the collar breakdown:

**Collar: ETH 28MAR25**

| Leg | Instrument | Side | Size | Price | Cost |
|---|---|---|---|---|---|
| Short call | ETH-28MAR25-2800-C | Sell | 5 | $48.20 | +$241.00 (credit) |
| Long put | ETH-28MAR25-2200-P | Buy | 5 | $44.30 | -$221.50 (debit) |
| | | | | **Net** | **+$19.50 credit** |

**Post-Hedge Risk Profile**:

| Metric | Before | After |
|---|---|---|
| **Net delta** | +3.8 ETH | +3.2 ETH |
| **Net gamma** | +0.0012 | +0.0008 |
| **Net vega** | +$42.00 | +$18.00 |
| **Downside protection** | None | Floor at $2,200 (5 contracts) |
| **Upside cap** | Unlimited | Capped at $2,800 (5 contracts) |
| **Max portfolio loss (to expiry)** | Theoretically unlimited | Limited below $2,200 |

**Scenario Analysis**:
- ETH at $2,200 (-10%): Portfolio loses ~$485, but puts kick in below $2,200 limiting further loss
- ETH at $2,450 (flat): Net +$19.50 from collar premium, positions unchanged
- ETH at $2,800 (+14%): Portfolio gains ~$1,330, but gains above $2,800 are capped by the short calls

The collar costs you essentially nothing ($19.50 net credit) and gives you a floor at $2,200. The tradeoff is your upside is capped at $2,800 on the hedged portion.

**Shall I execute this collar?**

---

**User**: Looks good. Execute it.

**Assistant**: Executing the collar now.

*[calls aevo_risk_check(instrument_name="ETH-28MAR25-2800-C", side="sell", amount=5, price=48.20)]*

Risk check passed on the short call leg.

*[calls aevo_risk_check(instrument_name="ETH-28MAR25-2200-P", side="buy", amount=5, price=44.30)]*

Risk check passed on the long put leg. Placing both orders.

*[calls aevo_create_order(instrument_name="ETH-28MAR25-2800-C", side="sell", amount=5, limit_price=48.20)]*

*[calls aevo_create_order(instrument_name="ETH-28MAR25-2200-P", side="buy", amount=5, limit_price=44.30)]*

Both legs submitted. Let me verify.

*[calls aevo_list_orders()]*

**Execution confirmed**:

| Leg | Status | Fill Price |
|---|---|---|
| Sell 5x ETH-28MAR25-2800-C | Filled | $48.20 |
| Buy 5x ETH-28MAR25-2200-P | Filled | $44.30 |

Net credit received: **$19.50**

Your collar is live. Here's your updated portfolio:

| Instrument | Side | Size |
|---|---|---|
| ETH-PERP | Long | 2.0 ETH |
| ETH-28MAR25-3000-C | Long | 5 contracts |
| ETH-28MAR25-2800-C | Short | 5 contracts |
| ETH-28MAR25-2200-P | Long | 5 contracts |
| BTC-PERP | Long | 0.05 BTC |

Your downside is now protected below $2,200 on the options portion. You still have uncapped upside on the ETH perp, and the BTC perp is a small position. Overall margin utilization is at 38%.

Want me to also hedge the BTC exposure, or are you comfortable with that position?


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)