shekel-hyperliquid

What this skill does

# Shekel Hyperliquid Skill — Complete Documentation

## ⚠️ MANDATORY: Always Check for Latest Skill Version

**Before EVERY interaction with Shekel endpoints**, you MUST:

1. Call `GET /skill/version` to get the current skill hash
2. Compare it to your cached version
3. If different (or no cache), fetch `GET /skill` and use the updated instructions

```bash
# Quick version check (do this before any Shekel action)
curl https://shekel-skill-backend.onrender.com/skill/version
# Returns: { "version": "abc123...", "fetchUrl": "...", "instruction": "..." }
```

**Why?** Supported networks, deposit methods, and API behavior change. Using outdated instructions will cause errors or give users wrong information.

> **Health check** (no auth): `GET /health` — also returns `skillVersion` hash for comparison.

---

## Quick Reference

| Goal | Endpoint |
|---|---|
| **Browser UI (no code needed)** | `GET /dashboard` → `https://www.shekel.xyz/hl-skill-dashboard` |
| **Service health** | `GET /health` |
| New user onboarding | `POST /auth/register/managed` |
| Check deposit / activation | `GET /auth/deposit-status` |
| Retry stuck deposit | `POST /auth/retry-deposit` |
| **Run agent (all whitelist tickers)** | `POST /agent/run` |
| Run agent (single ticker) | `POST /agent/run` with `{ "ticker": "BTC" }` |
| Close all open positions | `POST /account/close-positions` |
| View config | `GET /agents` |
| View balances | `GET /account/balances` |
| View positions | `GET /account/portfolio` |
| View open orders | `GET /account/orders` |
| View trade history | `GET /account/trades` |
| **View performance metrics** | `GET /agent/performance` |
| **View trading memory + improvement plan** | `GET /agent/memory` |
| View LLM reasoning logs | `GET /agent/llm-logs` (supports `?ticker=BTC&action=LONG&executed=true&limit=100&offset=0`) |
| View on Hyperliquid explorer | `GET /account/url` |
| Update strategy | `PATCH /agent/prompt` |
| Update whitelist / settings | `PUT /agents/:id` |
| Enable / change schedule | `PUT /agents/:id` with `runScheduleMinutes` |
| Disable schedule | `PUT /agents/:id` with `{ "runScheduleMinutes": null }` |
| Set risk limits | `PUT /agents/:id` with `maxOpenPositions`, `maxDailyLossPct`, `maxDrawdownPct` |
| Browse data sources | `GET /agents/data-sources` |
| Toggle data sources | `PUT /agents/:id` with `dataSourceConfig` |
| Set margin mode | `PUT /agents/:id` with `{ "marginMode": "isolated" \| "cross" }` |
| Pause / resume agent | `PATCH /agent/active` |
| Deposit address (top-up) | `GET /account/deposit-address` |
| Bridge funds (manual, usually not needed) | `POST /account/bridge` |
| Withdraw to Arbitrum | `POST /account/withdraw` |
| Rotate API key | `POST /auth/rotate-key` |
| Export trading wallet key | `POST /auth/export-agent-key` |
| Delete account | `DELETE /auth/account` |
| Available models | `GET /agents/models` — returns `{ venice: [...], rei: [...] }` |
| Available markets | `GET /markets/tickers` |

---

## Dashboard (Browser UI)

Users who prefer a visual interface can manage their agent at **https://www.shekel.xyz/hl-skill-dashboard** — no code required.

### What the dashboard provides
- Account overview: balances, open positions, trade history
- Agent configuration: strategy, whitelist, risk limits, schedule
- LLM reasoning logs: see what the agent was thinking on each run
- One-click actions: run agent, close positions, pause/resume

### How to connect
1. Direct the user to `https://www.shekel.xyz/hl-skill-dashboard`
2. They enter their `apiKey` (`sk_...`) on the login screen
3. The dashboard authenticates using the same `Authorization: Bearer <apiKey>` header as the REST API — no separate credentials needed

### If the user has no account yet
Offer two paths:
- **Via dashboard**: Visit the URL above and use the "Create Account" flow
- **Via AI**: Run through the onboarding steps below (Steps 1–5) and hand them their `apiKey` when done

> Call `GET /dashboard` to get the latest URL and access instructions programmatically.

---

## Returning Users

> This is the common case — check here first.

**Check your memory first.** If you saved credentials during onboarding (see Step 2a), load them from `MEMORY.md` — do not ask the user for their API key if you already have it. Only ask if memory is empty or the key returns a `401`.

If you must ask the user, only ask for their `apiKey` — that is the only credential needed for everything.

```
GET /agents                 → returns agentName, config, strategy
GET /account/balances       → show current funds
GET /auth/deposit-status    → confirm account is active
```

Then based on what you find:
- `status !== "active"` → follow Steps 3–5 of onboarding below
- `isActive === false` on agent → ask if they want to resume: `PATCH /agent/active { "active": true }`
- Want to change strategy → `PATCH /agent/prompt`
- Want to top up → `GET /account/deposit-address` (send USDC, it auto-bridges in ~30-60s)
- Want to see trades → `GET /account/url` for Hyperliquid explorer link

---

## Onboarding (New User)

### Quick Start (recommended)

**Offer this first** — most users just want to get going. Don't overwhelm with 15 questions.

> "I can set up your trading agent with sensible defaults. Just answer 4 questions:
> 1. **Which coins?** (default: BTC, ETH, SOL)
> 2. **Risk level?** conservative / moderate / aggressive
> 3. **How much USDC are you depositing?** (minimum 5 USDC)
> 4. **How often should the agent trade?** (default: every 4 hours)
>
> That's it — I'll use a momentum strategy with appropriate position sizes. You can customize everything later."

**Quick start defaults by risk level:**

| Risk | `positionSizeMax` | `maxTradeSize` | `importantNotes` |
|---|---|---|---|
| Conservative | 10% | 10% of deposit | "Max 3x leverage. Always use stop losses within 3% of entry. Avoid trading during high volatility news events. Never risk more than 5% of account on any single trade." |
| Moderate | 20% | 20% of deposit | "Max 5x leverage. Use stop losses on every trade. Exit losing positions quickly. Scale into winners gradually." |
| Aggressive | 35% | 40% of deposit | "Max 10x leverage allowed. Use tight stop losses. Accept higher drawdowns for higher returns. Trade momentum aggressively." |

**Quick start registration payload example (moderate risk, $500 deposit):**

```json
{
  "agentName": "My Trading Agent",
  "model": "grok-41-fast",
  "tradingStyle": "momentum",
  "strategyDescription": "Enter longs on price breakouts above recent highs with above-average volume. Enter shorts on breakdowns below recent lows. Exit when momentum reverses or RSI indicates overbought/oversold. Avoid ranging, low-volume markets. Use stop losses on every trade.",
  "importantNotes": "Max 5x leverage. Use stop losses on every trade. Exit losing positions quickly. Scale into winners gradually.",
  "minTradeSize": 10,
  "maxTradeSize": 100,
  "positionSizeMin": 5,
  "positionSizeMax": 20,
  "usdcRangeMin": 300,
  "usdcRangeMax": 1000,
  "whitelist": ["BTC", "ETH", "SOL"]
}
```

**After registration:** Set up the run schedule with `PUT /agents/:id` using `{ "runScheduleMinutes": 240 }` (4 hours).

If the user wants to fully customize, use the full flow below.

---

### LLM Provider Selection

Agents can use one of two LLM providers. The default is **Venice AI** (no user API key needed — platform-provided).

| Provider | `provider` value | `model` options | Key required? |
|---|---|---|---|
| Venice AI | `"venice"` | `grok-41-fast`, `qwen3-235b`, others | No (platform key) |
| Rei Intelligence | `"rei"` | `rei-coder-pro` (shown as **GPT-5.4**), `rei-coder-lite`, `rei-qwen3-coder` | Yes — user supplies `llmApiKey` |

To use Rei, include `provider` and `llmApiKey` in registration or agent update:

```json
{
  "provider": "rei",
  "model": "rei-coder-pro",
  "llmApiKey": "user_rei_api_key_here",
  ...
}
```

The Rei API key is encrypted at rest. Use `GET /agents/models` to see all available models per provider.

---

##