# Custom Data Endpoint
Source: https://docs.shekel.xyz/agent/custom-data
Feed your agent any external signal — proprietary indicators, on-chain metrics, alternative data
The Custom Data Endpoint lets you inject any external data into your agent's decision context. Your endpoint returns JSON; Shekel injects it into the prompt as a labeled `custom_data` block that the agent reads before deciding.
There are **two separate integration modes** with different API contracts — one for live agents, one for the backtest engine.
***
## Live Trading Agent
### How It Works
Before every run cycle, your agent sends a GET request to your URL with no parameters. Whatever JSON your endpoint returns is injected into the agent's prompt verbatim. The agent reads it and can factor it into its decision.
### Your Endpoint Requirements
| Requirement | Detail |
| ------------- | ------------------------------------------------------- |
| Method | `GET` |
| Parameters | None required |
| Response | Valid JSON (any structure) |
| Response time | Under 30 seconds (request times out at 30s) |
| Auth | Must be publicly accessible — no auth headers supported |
| Protocol | HTTPS only |
### Example Request
```
GET https://your-endpoint.com/signals
```
### Example Response
```json theme={null}
{
"btc_ema_distance_pct": 2.3,
"eth_ema_distance_pct": -0.8,
"signal": "BTC extended above 50-EMA, ETH oversold below 200-EMA",
"bias": "neutral",
"generated_at": "2024-03-15T08:00:00Z"
}
```
The agent receives this as a labeled block:
```
btc_ema_distance_pct: 2.3
eth_ema_distance_pct: -0.8
signal: BTC extended above 50-EMA, ETH oversold below 200-EMA
bias: neutral
```
### Tell Your Agent What the Data Means
Add a description to your strategy prompt so the agent knows how to interpret the custom data:
```
My custom endpoint provides EMA distance signals.
- ema_distance_pct > 3: price is extended, mean reversion likely
- ema_distance_pct < -3: price is oversold, bounce likely
- "bias" field indicates overall directional lean for the day
Use this alongside the standard technical indicators to inform your decision.
```
The clearer your strategy prompt describes the custom data, the better the agent will use it. Don't assume the AI will infer what your fields mean.
***
## Backtest Engine
The backtest engine simulates decisions step-by-step through historical time. At each step it queries your endpoint for the data that would have existed at that exact moment in the past — your endpoint must return **time-series historical data** covering the full backtest window.
### How It Works
Before the simulation loop begins, the engine pre-fetches all custom data for each coin and the full date range in a single request per coin. This data is cached locally and looked up during the simulation using nearest-prior matching.
### API Contract
```
GET {your-url}?symbol={COIN}&start_ms={unix_ms}&end_ms={unix_ms}&interval=4h
```
### Query Parameters
| Parameter | Type | Description |
| ---------- | ------- | ------------------------------------------------------------- |
| `symbol` | string | Token ticker (e.g. `BTC`, `ETH`, `SOL`) |
| `start_ms` | integer | Start of requested range — Unix timestamp in **milliseconds** |
| `end_ms` | integer | End of requested range — Unix timestamp in **milliseconds** |
| `interval` | string | Always `"4h"` — the backtest decision interval |
### Required Response Format
```json theme={null}
{
"symbol": "BTC",
"interval": "4h",
"data": [
{ "time": 1705276800000, "your_field": 1.234, "another_field": 0.567 },
{ "time": 1705291200000, "your_field": 1.290, "another_field": 0.541 },
{ "time": 1705305600000, "your_field": 1.180, "another_field": 0.612 }
]
}
```
### Data Rules
* `"time"` is **required** in every row — millisecond UTC timestamp
* All other field names are up to you — use descriptive names
* Numeric values are preferred; strings are accepted and passed through
* Data should cover the full requested date range
* Rows without a `"time"` field are silently dropped
* Extra fields (like `"symbol"` or `"interval"`) inside the `data` array are ignored
### Timestamp Alignment
At each 4h decision step, the engine looks up the **most recent data point at or before** that timestamp. It does not interpolate — your data must already be aligned to 4h candle boundaries.
4h candle boundaries in UTC: `00:00`, `04:00`, `08:00`, `12:00`, `16:00`, `20:00`
**Convert datetime to milliseconds:**
```python theme={null}
from datetime import datetime, timezone
dt = datetime(2024, 1, 15, 8, 0, 0, tzinfo=timezone.utc)
ms = int(dt.timestamp() * 1000) # → 1705305600000
```
**Convert milliseconds back to datetime:**
```python theme={null}
from datetime import datetime, timezone
dt = datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
```
**Align a raw timestamp to the nearest 4h boundary:**
```python theme={null}
FOUR_HOURS_MS = 4 * 3600 * 1000
aligned_ms = (raw_ms // FOUR_HOURS_MS) * FOUR_HOURS_MS
```
**Convert Date to milliseconds:**
```javascript theme={null}
const dt = new Date('2024-01-15T08:00:00Z');
const ms = dt.getTime(); // → 1705305600000
```
**Align to 4h boundary:**
```javascript theme={null}
const FOUR_HOURS_MS = 4 * 3600 * 1000;
const aligned_ms = Math.floor(raw_ms / FOUR_HOURS_MS) * FOUR_HOURS_MS;
```
### Full Example — Liquidation Data
This shows a correctly formatted response for liquidation heatmap data (CoinGlass-style):
```json theme={null}
{
"symbol": "BTC",
"interval": "4h",
"data": [
{
"time": 1705276800000,
"liq_buy_usd": 12400000,
"liq_sell_usd": 8900000,
"liq_net": 3500000
},
{
"time": 1705291200000,
"liq_buy_usd": 9100000,
"liq_sell_usd": 15200000,
"liq_net": -6100000
},
{
"time": 1705305600000,
"liq_buy_usd": 5600000,
"liq_sell_usd": 6300000,
"liq_net": -700000
}
]
}
```
And the corresponding strategy prompt note:
```
My custom endpoint provides 4h liquidation data:
- liq_buy_usd: buy-side liquidations (short squeeze pressure)
- liq_sell_usd: sell-side liquidations (long squeeze pressure)
- liq_net: positive = more shorts liquidated, negative = more longs liquidated
Large spikes in liq_sell_usd often precede cascading long liquidations.
Use this data to identify liquidity voids and potential squeeze targets.
```
### Caching
The engine caches endpoint responses per coin and date range as CSV files in `.cache/custom/`. If you update your historical data source, clear the cache to force a fresh fetch:
```bash theme={null}
rm -rf .cache/custom/
```
Or on Windows:
```
rmdir /s /q .cache\custom
```
### SSRF Security
For security, the backtest engine blocks requests to private IP ranges, loopback addresses, and cloud metadata endpoints. Your endpoint must:
* Use `https://` (not `http://`)
* Resolve to a public IP address
* Not include credentials in the URL
***
## Registering Your Endpoint
Go to **Modify Agent → Data Sources → Custom Data Endpoint**.
Paste your HTTPS URL and save. The agent will call it on the next run.
In the Backtest configuration screen, expand **Data Sources** and paste your URL in the **Custom Endpoint** field.
The engine will pre-fetch all data before the simulation starts.
# Data Sources
Source: https://docs.shekel.xyz/agent/data-sources
Every market signal your agent can see — and the exact field names you can reference in your strategy
Each run, your agent receives a **live context package** before it makes a trading decision. You choose which sources go into that package under **Modify Agent → Data Sources**. The richer the context, the better the agent can reason — but premium sources cost extra credits, so turn on only what your strategy actually uses.
Free sources are on by default. **Premium sources cost extra credits per ticker, per scheduled run** — the credit chip next to each toggle shows the price (e.g. `+10cr/ticker`). A run with four `+10` premiums on a 5-token whitelist adds `4 × 10 × 5 = 200` credits over the base model cost. Pay only for what you enable.
## Sources at a glance
| Source | Cost / ticker / run | Default | What it gives the agent |
| --------------------------- | ------------------- | ------- | ---------------------------------------------------------- |
| **Token Data** | Free | ON | Price, technicals, EMAs, swing structure (Hyperliquid) |
| **Fear & Greed Index** | Free | ON | Macro sentiment regime (0–100) |
| **Token Derivatives** | +15 cr | OFF | Per-perp OI, funding TWAPs, basis, mark/index spread |
| **Sentiment** | +10 cr | ON | 12h macro + crypto news recap (Gloria AI) |
| **Liquidation Data** | +20 cr | ON | Long/short ratio, liquidation flow, OI change (CoinGlass) |
| **Smart Money** | +10 cr | ON | Whale positioning & notional flows by token |
| **Futures/Options Signals** | +10 cr | ON | Derivatives directional bias + confidence (Athena AI) |
| **Max Pain** | +50 cr | OFF | Institutional liquidation max-pain magnets (CoinGlass Pro) |
| **ETF Flows** | +5 cr | ON | Daily net BTC + ETH spot-ETF flows (BTC/ETH only) |
| **Custom Endpoint** | Free | — | Your own API → injected as a custom context block |
The agent reads your strategy as English narrative — it does **not** parse field paths automatically. To make it reason about a specific value, **name the field and explain how to read it** in your prompt (e.g. *"stand down when `adx.4h` \< 20 — low-trend regime"*). The exact field names live in the [Data Points Reference](#data-points-reference) below.
***
## Token Data — Free · ON
Per-token live snapshot: price, order-book depth, funding rate, open interest, RSI, MACD, VWAP, Bollinger Bands, a full EMA grid, and swing structure — sourced directly from Hyperliquid.
**How to leverage:** this is the bedrock context — leave it on unless you have a very good reason. Any strategy that mentions *RSI, MACD, VWAP, EMA distance,* or *order-book imbalance* relies on it. Without it your agent is flying blind on technicals.
## Fear & Greed Index — Free · ON
The crypto Fear & Greed Index (0 = extreme fear, 100 = extreme greed) — a macro regime indicator.
**How to leverage:** best as a *regime filter,* not a trade trigger. Pairs powerfully with **Smart Money** — retail panicking (extreme fear) while whales accumulate is one of the highest-conviction contrarian setups on the platform.
## Token Derivatives — +15 cr · OFF
Per-ticker live perpetual structure from Hyperliquid via Shekel's indexer: open interest with 1h/4h/24h change, funding rate plus 1h/8h/24h TWAPs, perp mark/index spread, basis, and max available leverage.
**How to leverage:** for strategies that read *positioning* — funding TWAP divergences, OI building into a move, perp premium/discount as a crowding gauge. Heavier than Token Data's basic funding field; turn it on when your edge is derivatives-structure-driven.
## Sentiment — +10 cr · ON
12-hour macro and crypto news recaps from Gloria AI — distilled headlines and themes the agent can read while deciding.
**How to leverage:** for strategies that react to *narrative* (Fed pivots, ETF approvals, regulatory or exchange news). Purely technical prompts ("RSI cross + EMA confluence") can leave it off and save the credits.
## Liquidation Data — +20 cr · ON
CoinGlass derivatives feed: long/short ratio, aggregated liquidation flow (longs vs shorts wiped out), OI percent-change, and OI-weighted funding.
**How to leverage:** tells you what's happening *under* the price — who's getting hurt and how leveraged the market is. Needed for *fade-the-flush, long-capitulation, short-squeeze,* or *funding-extreme* strategies. Funding-rate divergence from price action is a classic tell.
## Smart Money — +10 cr · ON
Whale positioning and notional flows per token, from leaderboard-wallet activity — long/short bias by token from the largest positioned traders.
**How to leverage:** for *follow-smart-money* or *fade-retail-when-whales-disagree* setups. Most powerful when whale positioning contradicts retail Fear & Greed. Whales are early but not always right — use as conviction weighting, not gospel.
## Futures/Options Signals — +10 cr · ON
Directional signals from futures and options markets with confidence scores (Athena AI): basis spreads, term-structure shifts, and short/medium/long-term bias from derivatives positioning.
**How to leverage:** especially for **swing strategies (1h+ intervals)** where derivatives lead spot by hours-to-days. Short-frequency scalping (15m/30m) gets less — the signal cadence doesn't match.
## Max Pain — +50 cr · OFF
Institutional-grade liquidation max-pain levels — the price zone where the most leveraged positions across the market would be wiped out. The same data MMs and prop desks use to map liquidity targets (CoinGlass Pro tier).
**How to leverage:** max pain acts as a probability-weighted **price magnet** — markets statistically gravitate toward the level that maximizes liquidation damage on the overcrowded side. Use for *"limit orders at liquidity targets," "fade extended moves toward max pain,"* or *"size up when distance from max pain exceeds X%."* Combine with Liquidation Data: max pain tells you **where** the liquidity sits, liquidation flow tells you **who** is getting hurt right now.
Max pain is a **magnet, not a wall** — strong news can punch through it. Backtest coverage starts **2026-05-11** (when Shekel began indexing it); earlier backtest dates simply run without a max-pain section. Best for liquidity-event strategies and 4h+ swing trading; less useful for pure momentum.
## ETF Flows — +5 cr · ON (BTC + ETH only)
Daily net flow into BTC and ETH spot ETFs — an institutional macro-demand signal. Most recent daily flow plus 7-day and 30-day cumulative trends.
**How to leverage:** a slow macro tide, not a trade trigger. Sustained inflows support a structurally bullish bias on BTC/ETH; persistent outflows are a caution flag.
## Custom Endpoint — Free · advanced
Feed your agent any external data — proprietary signals, on-chain metrics, custom indicators — by pointing it at your own API. See [Custom Data](/agent/custom-data) for the full request/response contract (live **and** backtest).
***
## Data Points Reference
The complete field-by-field schema of everything your agent sees, per source. **Use these exact names in your strategy prompt** to make the agent reason about specific values — e.g. *"when `rsi.4h` > 70 AND `funding_rate.annualized_pct` > 30%, treat as exhaustion."* Names match what the model literally sees inside the ``, ``, etc. blocks of the prompt. Unavailable values (e.g. a weekly 200-EMA on a young token) come through as `null` and the agent handles that gracefully.
**Symbol & price**
```
symbol "TICKER/USDC:USDC"
base token symbol (e.g. "BTC")
quote quote currency (always "USDC")
mark_price current Hyperliquid mark price
mid_price current Hyperliquid mid price
price_change_24h absolute USD change over 24h
price_change_percent_24h % change over 24h
```
**Funding rate**
```
funding_rate.current_value raw per-payment funding (decimal)
funding_rate.annualized_pct annualized funding rate %
```
**Per-timeframe technicals** (`{tf}` = 15m, 1h, 4h, 1d)
```
rsi.{tf} Relative Strength Index (14)
atr.{tf} Average True Range (14, raw price)
atr.percentage_{tf} ATR as % of price (use for dynamic stops)
macd_line_slope.{tf}.macd_line MACD line (12/26/9)
macd_line_slope.{tf}.signal_line
macd_line_slope.{tf}.histogram MACD histogram (line − signal)
obv.{tf} On-Balance Volume (cumulative)
adx.{tf} Avg Directional Index (14). <20 weak / >25 trending
vwap.{tf} Volume-Weighted Avg Price (daily reset)
```
**Bollinger Bands** (1h, 20-period, 2σ)
```
bollinger.band_width (upper − lower) / middle — regime gauge
bollinger.upper_band
bollinger.lower_band
bollinger.middle_band 20-period SMA (1h)
```
**EMA grid** — 4 timeframes (1h, 4h, daily, weekly) × 3 periods (20, 50, 200), distance + slope per cell:
```
ema.{tf}_{period}_distance_pct signed % from price to EMA (+ above, − below)
ema.{tf}_{period}_slope_pct 5-bar % change of the EMA (+ up-sloping)
```
e.g. `ema.daily_20_distance_pct`, `ema.4h_50_slope_pct`. A daily `|slope_pct| < ~0.1%` is effectively flat.
**StochRSI** (14/14/3)
```
stochrsi_4h [0,1]. <0.2 oversold, >0.8 overbought
stochrsi_1d higher-TF confluence
```
**Swing structure** (Bill Williams fractal pivots, confirmed-only)
```
swing.4h.last_pivot_high.price / .bars_ago (4h micro: N=2)
swing.4h.prev_pivot_high / last_pivot_low / prev_pivot_low
swing.1d.last_pivot_high.price / .bars_ago (daily structural: N=5)
swing.1d.prev_pivot_high / last_pivot_low / prev_pivot_low
```
Use for *"broke last swing low → exit long"* or *"higher highs + higher lows → uptrend intact."* Fresh pivots (`bars_ago` \< 10 on 4h, \< 5 on 1d) are higher-conviction.
```
asset token symbol
open_interest.value current OI (notional)
open_interest.change_pct_1h / _4h / _24h
funding.current_value current funding (decimal)
funding.annualized_pct
funding.twap_1h_annualized
funding.twap_8h_annualized
funding.twap_24h_annualized
mark_index_spread_bps perp premium/discount vs index
(+ perp premium = longs paying; − = shorts paying)
basis_bps basis spread vs reference
max_leverage_available current HL max leverage cap
_meta.indexer_observed_at when snapshot was taken
_meta.indexer_latency_sec age of snapshot (seconds)
_meta.stale_warning true if snapshot > 30 min old
```
```
status "success"
data.value 0–100 score
data.value_classification "Extreme Fear" … "Extreme Greed"
data.timestamp Unix seconds
```
Narrative text, not structured numbers.
```
recap paragraph(s) of recent macro + crypto headlines/themes
generated_at timestamp of the recap
```
Reference in prompts like *"if news mentions a Fed pivot, increase risk aversion."*
```
long_short_ratio_4h global L/S ratio (1.0 balanced; >1 longs; <1 shorts)
ls_signal "long_dominance" / "short_dominance" / "neutral"
long_liq_dominance_4h % of 4h liquidations that were longs
(>0.6 long capitulation; <0.4 short squeeze)
liq_signal "long_capitulation" / "short_squeeze" / "neutral"
oi_change_4h_pct open interest % change over 4h
avg_funding_rate_oi OI-weighted average funding rate
ts snapshot timestamp
```
Array of per-token records (BTC, ETH, SOL, XRP pinned; others rotate):
```
token symbol
total_positions # of tracked whale positions
position_percentage e.g. "60% SHORT"
money_percentage notional-weighted bias (e.g. "86% SHORT")
percentage numeric majority side %
position "LONG" / "SHORT" / "NEUTRAL"
signal_duration "short-term" / "mid-term" / "long-term"
avg_hold_hours / median_hold_hours
total_notional_value total $ of all tracked positions
net_notional_value net directional exposure (signed)
```
Per symbol (BTC, ETH primarily), from Athena AI:
```
Symbol
Monthend_MP / Quarterend_MP max-pain projections
Top_Long / Top_Short % of top traders long/short
Global_Long / Global_Short % of all traders long/short
Top_Ratio / Global_Ratio long/short ratios
Funding_Rate / Close_Basis
Futures_Signal "Strong Long" … "Very Short"
Options_Shortterm_Signal short-term options bias
Options_Midterm_Signal ~1 month
Options_Longterm_Signal ~3+ month
Athena_Wisdom_Basis / _Shortterm / _Midterm / _Longterm composites
```
```
symbol / current_price
near_term.window "24h"
near_term.long_max_pain.price / .liq_level_usd / .distance_pct
near_term.short_max_pain.price / .liq_level_usd / .distance_pct
extended.window "7d"
extended.long_max_pain.* / extended.short_max_pain.*
# top-level mirror (defaults to near-term)
long_max_pain.* / short_max_pain.*
max_pain_price single canonical max-pain price
distance_pct % distance from current price
```
Both windows update every \~30 min across \~30 tokens.
```
asset "BTC" or "ETH"
latest_date last observation (YYYY-MM-DD)
latest_flow_usd most recent daily net flow ($, + inflow / − outflow)
latest_price_usd spot price at last observation
trend_7d_net 7-day cumulative net flow ($)
trend_30d_net 30-day cumulative net flow ($)
ts snapshot timestamp
```
### Referencing fields in your prompt
The agent reads your strategy as narrative and reasons about it alongside the live data — it doesn't blindly execute rules. Naming specific fields gives it concrete anchors, which produces tighter, more repeatable decisions than vague phrasing. Examples that work:
```text theme={null}
"Stand down when adx.4h < 20 — low-trend regime."
"Only take longs when ema.daily_20_distance_pct > 0 AND
ema.daily_20_slope_pct > 0 (price above an up-sloping 20-day EMA)."
"Exit long if price closes below swing.1d.last_pivot_low.price —
structural break against the position."
"If liq_signal is 'long_capitulation' AND ema.4h_50_distance_pct < 0,
treat as a bullish refuel candidate."
```
Whatever data sources you enable for **live** trading, the [Backtest Engine](/backtesting/overview) feeds the agent the same sources at each historical decision point — so a strategy that leans on a given signal behaves the same in simulation as in production (subject to each source's historical coverage window).
# Dynamic Trading
Source: https://docs.shekel.xyz/agent/dynamic-trading
Let your agent wake up the moment a market event fires — not just on its schedule
By default your agent thinks on a **fixed schedule** — every 4 hours, every hour, whatever you set. That's a clean rhythm for trend-following, but it means the agent is asleep when something happens between intervals. If BTC breaks the 200 EMA at 3:42 AM and your next run isn't until 8:00 AM, you've missed four hours.
**Dynamic Trading** adds event-driven wake-ups **on top of** your schedule. Both run side by side: the schedule keeps its cadence, and event triggers fire extra runs when something worth reacting to happens.
## Enabling it
1. Open **Modify Agent → ⚡ Dynamic Trading** and toggle it on.
2. Choose which signals the agent reacts to.
3. Set your guard rails (cooldown, daily cap).
## Available signals (V1)
Wakes the agent when BTC's 4h close crosses above or below the 200 EMA — a widely-followed trend-flip indicator. Good for *"load up on the regime change"* or *"de-risk when trend breaks"* strategies.
Wakes the agent when total crypto liquidations in a 1-hour window exceed your configured USD threshold (e.g. \$500M). Good for *fade-the-flush* or volatility-expansion plays.
More signals are planned — tell us what events you'd want your agent to react to.
## Guard rails
* **Cooldown (minutes)** — minimum time between fires. Default **60 min**; prevents the agent from spamming itself if a signal flickers across its threshold.
* **Daily Cap** — max dynamic fires per day. Default **6**; keeps credit spend predictable.
* **Credit balance** — dynamic fires use the same balance check as scheduled runs. If your balance hits zero, dynamic fires pause along with the schedule.
## Audit trail
Every dynamic fire is logged with the signal that fired, the threshold value at trigger time, what the agent decided, and how many credits it used — reviewable alongside your scheduled runs.
## Backtest parity
The [Backtest Engine](/backtesting/overview) replays the same dynamic-signal logic against historical data, so you can A/B test your strategy **with and without** event triggers before going live — just toggle Dynamic Trading on the backtest config the same way.
Dynamic Trading is included with credits — no separate subscription or staking gate. You only pay for the runs your agent actually executes.
# Managing Your Agent
Source: https://docs.shekel.xyz/agent/managing
How your agent manages positions, and how you pause, modify, and stop it
## How your agent manages positions
Your agent doesn't just open and close trades — it actively **manages** a position over its life. You don't configure any of this; it's part of how the agent reasons each run, governed by your strategy and risk limits.
| Action | What it does |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scale in (add)** | If conviction grows, the agent adds to an existing position. On Hyperliquid you hold one position per token, so adding blends your average entry and grows size — never beyond your **Position Size Max %**. |
| **Reduce (partial profit / de-risk)** | Closes *part* of a position (e.g. 50%) at market to lock gains or trim exposure while staying in the trade. |
| **Take-profit ladders** | Instead of one target, the agent rests **multiple** TP rungs on the exchange (e.g. 40% at the first, 35% higher, let the rest run). Each fills on its own. In the Positions table, a laddered TP shows a dropdown arrow — click it to see every rung's price and %. |
| **Manage exits** | As a trade moves your way, the agent raises the stop toward break-even and re-sets the TP ladder — *without* changing position size. |
| **Flip** | If the thesis reverses, an opposite-direction trade nets against the position and can flip you to the other side. |
| **Close** | Fully exits (100%). |
Your **Position Size Max %** still caps how large one position can grow, and **Max Open Positions** still caps how many tokens you hold. [Backtests](/backtesting/overview) model scale-ins, reduces, flips, TP ladders, and stop adjustments identically to live — so a strategy that builds, trims, and manages exits behaves the same in simulation as in production.
## Pause & Resume
Tap **Pause** on the home screen dashboard to temporarily halt your agent. The agent will not make any new decisions while paused, but all open positions remain active on Hyperliquid.
Tap **Resume** when you are ready to restart. The agent will pick up on its next scheduled interval.
Pausing is the right move before a major market event or scheduled news release where you want manual control. Your settings and strategy are preserved exactly as-is.
## Modify Agent
Go to **Modify Agent** from the dashboard (or tap ⋯ → Modify) to update:
* **Strategy Prompt & Important Notes** — refine your trading thesis
* **Model** — switch AI model at any time
* **Token Whitelist** — add or remove tradeable assets
* **Run Schedule** — change how often the agent wakes up
* **Risk Parameters** — adjust position sizes, drawdown limits, daily loss limits
* **Data Sources** — toggle data sources on and off
All changes take effect on the **next scheduled run** — the current cycle is not interrupted.
You can also ask your agent to propose changes via chat. If you ask it to review your strategy or risk settings, it may respond with a formal proposal card you can Apply or Dismiss. See [Setting Change Proposals](/chat/setting-proposals).
## Stop Agent
To fully shut down your agent and release the Hyperliquid API key:
Go to **Modify Agent → Deactivate Agent**.
This stops all scheduled runs. Your backtest history and account data are preserved. You can launch a new agent at any time.
Stopping the agent does not close your open Hyperliquid positions. Those must be closed manually on Hyperliquid or via a Manual Trade in the app.
## Manual Trade
While your agent is running, you can place one-off manual orders from the app:
Tap **⋯ → Manual Trade** from the dashboard.
Manual trades execute immediately and are logged separately from the agent's automated decisions.
## Checking Agent Status
The dashboard hero card shows your agent's current state:
| Status | Meaning |
| -------------------- | ------------------------------------------------------ |
| **LIVE** (green dot) | Agent is active and running on schedule |
| **PAUSED** | Agent is paused — no new decisions until resumed |
| **DISCONNECTED** | Agent cannot reach the backend — check your connection |
The **Next run** countdown shows exactly when the agent will next wake up.
# AI Models
Source: https://docs.shekel.xyz/agent/models
Choose the right model for your strategy and budget
Every agent decision is powered by an AI language model. You can switch models at any time from Modify Agent — the change takes effect on the next run.
All models run privately through [Venice AI](https://venice.ai). Your prompts, strategies, and trade data are never used to train any model.
## Model Comparison
| Model | Speed | Credit Cost | Best For |
| --------------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| **Claude Fable 5** | Slower | ●●●● | New flagship. The most capable model — for the most demanding, nuanced strategies. 1M-token context. |
| **Claude Opus 4.8** | Slower | ●●● | **Recommended default.** Excellent for complex, nuanced strategies at a lower cost than Fable 5. |
| **Claude Sonnet 4.6** | Fast | ●●○ | Fast & efficient — strong reasoning at lower cost. |
| **Claude Opus 4.7** | Slower | ●●● | Prior-generation flagship. Powerful and nuanced. |
| **Claude Opus 4.6** | Slower | ●●● | Powerful, slightly older generation. |
| **Grok 4.5** | Medium | ●●● | Latest Grok — xAI's flagship, Opus-class reasoning with strong market intuition. |
| **Grok 4.3** | Fast | ●●○ | Fast, capable Grok. Strong market intuition. |
| **Grok 4.2** | Fast | ●●○ | Proven performer. Good all-rounder. |
| **Grok 4.1 Fast** | Fastest | ●○○ | Speed-focused. Good for high-frequency schedules. |
| **DeepSeek v4 Pro** | Medium | ●●○ | Strong analytical reasoning. |
| **DeepSeek v4 Flash** | Fastest | ●○○ | Lightweight. Good for simple rule-based strategies. |
| **Qwen 3 235B** | Medium | ●○○ | Large open model. Capable generalist. |
| **Llama 3.3 70B** | Fastest | ○○○ | Budget option. Good for simple strategies. |
## Choosing a Model
**Start with Claude Opus 4.8** — the recommended default, with an excellent balance of nuanced reasoning and cost. Reach for **Fable 5** when a strategy is unusually demanding and you want the most capable model available; drop to **Sonnet 4.6** when you want speed and efficiency.
**Step up to a flagship (Opus 4.8 / Fable 5) if:**
* Your strategy requires nuanced judgment across many signals simultaneously
* You run at lower frequency (4h+) and credit cost per run matters less
* Your backtests show the strategy benefits from deeper reasoning
**Step down to Grok Fast or DeepSeek Flash if:**
* You run at high frequency (15 min or 30 min) and want to preserve credits
* Your strategy is mostly rule-based with clear numeric thresholds
* You're in testing mode and don't need top-tier performance yet
## Chat Models
The model powering your **agent chat** is independent of your trading model. You can switch it per-session from the model picker in the chat header.
| Model | Credits per Message | Best For |
| ------------- | ------------------- | -------------------------------------- |
| Grok Fast | 15 cr | Quick lookups, simple questions |
| Grok 4.3 | 30 cr | Strategy analysis, deeper questions |
| Grok 4.5 | 70 cr | Latest Grok — deeper strategy analysis |
| Claude Sonnet | 45 cr | Nuanced strategy review |
| Claude Opus | 120 cr | Deep portfolio analysis, major reviews |
Your chat model selection is saved and remembered across sessions.
Use a cheaper chat model for quick questions ("what positions are you holding?") and switch to Sonnet or Opus when you want a serious strategy review.
# Operator Context
Source: https://docs.shekel.xyz/agent/operator-context
Hand your live agent a timely human observation — weighed as information, never obeyed as a command
Operator Context is a small plain-text note you attach to a **live** agent. Before each decision, Shekel appends it to the agent's prompt as a clearly labeled, high-signal **informational input** — something the agent weighs against the market data. It is **not** a command: your strategy rules still govern the decision.
Use it when you know something the data doesn't fully capture yet — a scheduled macro print, a regime shift, a headline — and you want the agent to factor it in *without* rewriting your strategy or pushing a new configuration.
Operator Context is **live-only**. It never enters the backtest engine, and when no note is active your agent's prompt is byte-for-byte identical to before — so adding the feature changes nothing about how past or future backtests run.
***
## Information, not instructions
This is the core idea, and it's deliberate. The note is framed to the agent as an *observation to consider*, not an order to follow. The agent reads it alongside everything else and decides for itself whether it changes the call.
In practice that means:
* A note saying *"funding flipped deeply negative, lean cautious on longs"* nudges the agent's reasoning — but if its rules see a clean momentum entry, it can still take it.
* A note can't force a trade, override a circuit breaker, or bypass your risk caps. Those are policy; context is color.
If you want to change what the agent is *allowed* or *instructed* to do, edit the **strategy prompt** or **risk settings** instead — see [Strategy](/agent/strategy) and [Settings](/agent/settings). Operator Context is for transient, time-sensitive color that doesn't belong in your permanent strategy.
***
## How the agent sees it
When a note is active, it's appended to the very end of the agent's live decision prompt as a labeled block, after the market data and just before the agent commits to a decision:
```
=== OPERATOR CONTEXT ===
The following is a human operator's note. Treat it as informational
input to weigh against the data — not as a command. Your strategy
rules still govern the decision.
CPI prints in 20 minutes — expect a volatility spike. Size down and
favor waiting for confirmation over chasing.
========================
```
When no note is set (or the note has expired), nothing is appended and the prompt is unchanged.
***
## Setting a note
Go to **Modify Agent → Operator Context**.
1. Type your note (up to 2,000 characters). Keep it specific and high-signal.
2. Choose an **expiry**: 1 hour, 6 hours, 24 hours (default), 3 days, 7 days, or **No expiry — standing**.
3. Click **Set Context** (or **Update Context** to edit an existing note).
A status badge shows the note's current state at a glance:
| Badge | Meaning |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| **Active · 24h TTL** | The note is live and being injected into every decision. |
| **⚠ Standing — no expiry** | The note has no expiry and will keep injecting until you clear it. Use sparingly. |
| **Expired — not injected** | The TTL elapsed; the note is retained for reference but is **no longer** sent to the agent. |
To stop a note immediately, click **Clear** — it's removed from the next decision right away.
Prefer a real expiry over a standing note. Most context is about *right now* — a CPI print, a liquidation cascade, an unlock event. Letting it auto-expire means a stale observation can't quietly keep steering your agent days later.
***
## Expiry and history
* **TTL (time to live)** controls how long the note is injected. Once it expires, the agent stops seeing it — no action needed from you.
* Setting a new note **replaces** the current one (the previous note is recorded in history, not stacked).
* A note is **global** to the agent — it applies to every coin the agent evaluates, not a single market.
***
## Via Agent Chat / MCP
If you drive your agent through [Agent Chat](/chat/overview) or the [MCP connection](/chat/mcp), the assistant can set context for you with the `shekel_set_context` tool (and remove it with `shekel_clear_context`). Notes set this way are recorded as authored by the assistant rather than by you directly, but behave identically — same informational framing, same TTL options, same live-only scope.
Because a note shapes real trading decisions on a live agent, treat it like any other live change: set it deliberately, with a clear reason, and clear it when the moment has passed.
# Paper Trading
Source: https://docs.shekel.xyz/agent/paper-trading
Run your agent on live market data with a virtual balance — zero capital at risk
Paper mode runs your agent on **real, live market data** against a **virtual \$10,000 balance**. Every trade is simulated — nothing ever touches your Hyperliquid account. It's the dress rehearsal between backtesting and going live.
Paper mode is the middle gate of the recommended path: **configure → backtest → paper-trade 1–2 weeks → review with the AI → go live.** Your agent will guide you through it — ask it *"how's my paper trading going?"* or *"ready to go live?"* for an honest read.
## How it works
* Your agent runs on **exactly** the same schedule, data sources, strategy, and risk limits as live mode.
* Trades execute against a simulated **\$10,000 USDC** portfolio at **real mark prices**.
* Positions, P\&L, fees, and funding rates are all tracked and shown on your dashboard, just like live.
* The AI chat assistant sees your paper portfolio and can discuss performance, suggest adjustments, or tell you when results look live-ready.
## What's fully simulated
| Behaves like live | Detail |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Risk caps** | Max drawdown, daily loss, and max open positions are enforced identically. |
| **Stop-loss & take-profit** | Including multi-rung TP **ladders** (each rung fills as a partial close). A backend poller checks mark prices every \~2 minutes and fills them when triggered — mirroring live execution. |
| **Limit orders** | Simulated against real mark prices. |
| **Funding** | Accrued every 8 hours at real Hyperliquid rates. |
| **Credits** | Standard credit cost still applies — the agent reads data and calls the model the same way. |
## What's different from live
* **No real capital is ever at risk.** The \$10,000 is virtual.
* **No slippage simulation (v1).** Fills are at the current mark price, so paper P\&L may **slightly outperform** live — treat it as optimistic.
* **`[PAPER]` badges** appear throughout the dashboard and chat so you always know which mode you're in.
## Switching modes
Open **Modify Agent → Trading Mode** card → tap **Go Paper** or **Go Live**.
* **Going Paper is instant** — no funding needed.
* **Going Live** requires a confirmed USDC deposit into your agent's Hyperliquid account.
Paper-trade for at least 1–2 weeks across different market conditions before going live. A strategy that looks great in a single calm week can behave very differently in a volatile one.
# Decision Records & Self-Improvement
Source: https://docs.shekel.xyz/agent/self-improvement
Let your agent review its own track record and propose upgrades
Shekel can save a structured record of every trading decision your agent makes, then run a **structured review** over that history to suggest concrete improvements to your strategy and settings. Find it on the web app under **Settings** in the sidebar.
Open **Settings** from the **sidebar** (the account page) — not the gear icon on the dashboard, which opens *Modify Agent*.
## Decision records (on by default)
Shekel saves a structured record of each trading decision — what the agent saw, what it decided, and (when possible) what happened afterward. This powers the self-improvement review.
Turn off **Save my agent's decision records** if you don't want new records stored. Turning it off also disables scheduled reviews and auto-apply.
## Self-improvement review — 35 credits / run
The **Self-improvement** section runs a structured review over recent trades and decision records. It can suggest up to **three** changes across strategy text, risk limits, sizing, whitelist, schedule, and related settings.
* Tap **Run reflection (35 credits)** for an on-demand review.
* Suggestions appear in **agent chat** as cards with **Apply / Dismiss** per change (and in Settings when you open a past run).
* Expand a completed run to read the full **Review** text.
Reviews run on **Venice AI** — not your BYOA chat model.
## Scheduled reviews
Enable **Run reflections automatically** and pick an interval — every **1, 3, 7, or 14 days**, or a custom hour interval (12–2160 hours). The next scheduled time is shown when enabled. Requires decision records to stay on.
## Auto-apply (beta)
An optional checkbox. When on, approved-style changes apply automatically after each review — **including risk and sizing limits** — without your clicking Apply.
Auto-apply is still in **beta**. It does not replace your judgment on risk — monitor every upgrade in chat (green **Auto-applied** cards per change) or in Settings after each run.
## Backtest history feeds learning
Every backtest you complete is saved to your account and is available to the review (and to your agent in chat). Pin a **gold standard** run in Backtest History (📌) and the agent automatically measures new variants against it. See [Backtesting → Results](/backtesting/results).
# Agent Settings
Source: https://docs.shekel.xyz/agent/settings
Every configurable parameter for your live trading agent
## Agent Identity
**Agent Name**
A display label for your agent — shown on the dashboard, in chat, and in notifications. Purely cosmetic.
**Token Whitelist**
The set of tickers your agent is allowed to trade. The agent will never open a position in anything not on this list.
```
BTC, ETH, SOL, WIF, HYPE
```
Start with 3–5 tokens you know well. A tighter whitelist means the agent's context is more focused and its per-token analysis is deeper.
## Run Schedule
How often the agent wakes up to analyze the market and potentially make a decision.
| Schedule | Use Case | Credit Cost |
| -------- | ------------------------ | ----------- |
| 15 min | Scalping, high-frequency | Highest |
| 30 min | Active intraday | High |
| 1h | Balanced intraday | Medium |
| 2h | Intraday swing | Medium |
| 4h | Standard swing | Low |
| 8h | Slow swing | Low |
| 12h | Daily trend | Very low |
| 24h | Long-term positioning | Lowest |
| Custom | Any interval in hours | Varies |
A run only costs credits when it calls the AI model. A WAIT decision is cheaper than a trade decision because WAIT responses are typically shorter.
## Risk Parameters
These are enforced hard limits — the agent checks these before executing any trade, and also uses them to guide its reasoning.
### Max Open Positions
Maximum number of concurrent open trades.
**Default:** 5\
**Recommendation:** 3–5 for most strategies. Lower for conservative approaches.
### Position Size (Min / Max %)
The range of capital the agent can allocate per individual trade, expressed as a percentage of total account value.
**Default:** 5% min / 20% max\
**Example:** With $1,000 in your account and 5–20% range, each position will be between $50 and \$200.
### Max Drawdown %
The agent pauses automatically if your portfolio drops this percentage from its peak value during the session.
**Default:** 15%\
**How it works:** If your account peaks at $1,000 and falls to $850, the agent pauses and sends a notification.
The agent pauses — it does not close positions. Open positions remain on Hyperliquid and continue to be affected by market movement after the pause. Go to the app to manually close if needed.
### Max Daily Loss %
Similar to Max Drawdown but resets at midnight UTC. The agent pauses if daily P\&L reaches this threshold.
**Default:** 5%
## Modifying Settings
Go to **Modify Agent** from the dashboard to update:
* Strategy prompt and important notes
* Model selection
* Token whitelist
* Run schedule
* Risk parameters
* Data source toggles
Changes take effect on the **next scheduled run**.
You can also ask your agent to **propose changes** via chat — it will surface a formal proposal card that you can apply or dismiss with one tap. See [Setting Change Proposals](/chat/setting-proposals).
# Writing Your Strategy
Source: https://docs.shekel.xyz/agent/strategy
The strategy prompt is the most important setting — here's how to write a good one
Your strategy prompt is the single instruction the AI reads before every trading decision. It defines your agent's personality, philosophy, and rules. Everything else is context — the strategy is judgment.
## What Makes a Good Strategy
"Focus on momentum breakouts with high volume confirmation on BTC and ETH. Avoid the first 2 hours after any major macro news event."
"Never hold more than 3 positions at once. Only enter when potential upside is at least 2x the risk. Prioritize capital preservation."
"I am macro-bearish on altcoins through Q3. Only go long on BTC and ETH. Short altcoin weakness — especially low-cap memes."
"This is a 4h swing strategy. Do not react to noise within a single candle. Look for setups that align across the 4h and daily timeframes."
Vague prompts like "trade profitably" give the AI no real direction. The model will still make decisions — they just won't be grounded in any coherent thesis.
## Strategy Examples
```
You are a momentum trader focused on Hyperliquid perpetuals.
Your edge is catching breakouts early and riding the trend:
- Look for price breaking above recent consolidation with strong volume
- EMA crossovers (9/21) should confirm the direction
- RSI above 55 for longs, below 45 for shorts
- Open interest increasing on the breakout confirms conviction
Risk rules:
- Maximum 3 simultaneous positions
- Position size 10–20% of capital per trade
- Exit immediately if price closes back inside the range
Do not chase — if you missed the initial breakout, wait for a retest.
```
```
You are a mean-reversion trader. Your thesis is that most crypto moves overextend and snap back.
Setups to look for:
- RSI below 25 (oversold) for long entries, above 75 for short entries
- Price significantly extended from the 20-period VWAP (>3%)
- Funding rate extremes (very negative = likely reversion up, very positive = likely reversion down)
Risk rules:
- Positions should be smaller (5–10% of capital) because this strategy trades against trend
- Take profit at VWAP or RSI 50
- Hard stop if price continues >5% in the wrong direction
Never average down. One entry per setup.
```
```
You are a macro-driven directional trader. Your primary inputs are sentiment, fear/greed, and broad market structure.
Thesis: I trade with the macro trend, not against it.
- When Fear & Greed is below 25, the market is likely bottoming — start building longs on BTC and ETH
- When Fear & Greed is above 80, the market is euphoric — reduce exposure or flip short on altcoins
- Strong BTC dominance rising = rotate out of alts into BTC
- Strong BTC dominance falling = alts are leading, consider smaller alt positions
Risk rules:
- Maximum 30% of capital deployed at any one time
- Never short BTC unless macro is clearly turning (multiple confirming signals)
- Positions held across multiple run cycles; do not react to single-candle noise
```
## The Important Notes Field
Use **Important Notes** for hard rules the agent must follow regardless of market conditions. Think of this as the strategy prompt's override layer — rules that cannot be reasoned away.
Examples:
```
Never trade DOGE or SHIB under any circumstances.
Always close all positions before Friday 5pm UTC.
Never use leverage above 3x.
If BTC drops more than 10% in a single day, close all positions and wait.
```
## Prompt vs. Important Notes
| Strategy Prompt | Important Notes |
| ------------------------------ | ---------------- |
| How to think | What never to do |
| Reasoning framework | Hard constraints |
| Updated as your thesis evolves | Stable rules |
| The agent can reason around it | Always honored |
## Tips
* **Iterate** — your first strategy won't be your best. Run a backtest, read the agent's reasoning, then refine.
* **Be concrete about signals** — instead of "use technicals," say which ones and what thresholds you care about.
* **Mention your timeframe** — an agent running every 4h should think differently than one running every 15 min.
* **State what you don't want** — the AI will explore the full action space unless you constrain it.
# Obstacle Course
Source: https://docs.shekel.xyz/backtesting/obstacle-course
Stress-test a strategy prompt in minutes — a PASS/WEAK/FAIL verdict on how it behaves in the market moments that matter
The Obstacle Course is the fast first gate for any strategy-prompt change. Instead of simulating a full price path like a [backtest](/backtesting/overview), it replays your prompt against a curated battery of frozen market **stations** — trend tops, parabolic pullbacks, short squeezes, choppy ranges, trend refuels — and grades the decision your prompt produces in each one.
It answers one question: **does this wording produce the right *actions* in the moments that matter, consistently?** — in a few minutes instead of hours.
Use it as the first step of the testing loop: **Obstacle Course (minutes) → a short backtest → a full backtest.** If the course says FAIL, fix the prompt before you spend a backtest on it.
***
## Running it
1. In the app, open **Backtesting** and switch to the **Obstacle Course** tab.
2. The strategy prompt and notes from your current agent are prefilled — edit them freely, or paste any prompt. Only the prompt is tested.
3. Pick a **decision model**. The cost updates with the model — that's the only thing that changes the price.
4. Click **Run Obstacle Course**. Results are ready in \~3–10 minutes.
The course only ever replays its own curated snapshots. It never touches your live whitelist or your funds, and it never places a trade.
***
## Reading the report
### Verdict — the gate
| Verdict | Meaning |
| -------- | ------------------------------------------------------------------------------------------------------- |
| **PASS** | Clears every critical situation, consistently. |
| **WEAK** | Too many sub-optimal decisions, or inconsistent behavior in a critical situation. |
| **FAIL** | Took a forbidden action in a critical situation — e.g. failed to protect a large winner at a trend top. |
The **verdict is the gate.** There's also a 0–100 **course score**, but it's a *trend metric only* — never compare two prompts by subtracting scores. Compare them cell-by-cell.
### Cell matrix
A heatmap of every **station × position-context** (for example `top / winner`). Each cell shows pass/miss/fail counts, a consistency bar, and the full mix of actions your prompt chose — *"WAIT 2 of 6 at the top"* is exactly the kind of intel you're looking for. Click any cell to drill in.
### Decision drill
Click any graded decision to read the **full reasoning**, the raw model response, and the exact frozen market state the model was shown — no re-running required.
***
## Cost
Each run is charged a flat, **model-aware** credit fee, shown before you launch:
* A cheaper model is a cheaper run.
* The test battery itself is fixed, so **nothing other than the model changes the price**.
* The fee is charged at launch and **refunded automatically** if the engine can't start the run.
* You can have **one run in progress at a time**.
Iterating on a prompt? Start on a fast, cheap model to find obvious failures, then confirm your final wording on the model you actually trade with.
***
## From chat / MCP
You can also run the course from [Agent Chat](/chat/overview) or the [MCP connection](/chat/mcp) with the `shekel_run_obstacle_course` tool, and read results with `shekel_obstacle_course_report` — same verdict, cell matrix, and per-decision drill.
# Backtest Engine
Source: https://docs.shekel.xyz/backtesting/overview
Simulate any strategy against historical Hyperliquid data before going live
The Backtest Engine lets you simulate your strategy against historical market data — running real AI decisions on past candles, so you can see how your strategy would have performed before risking real capital.
Unlike traditional backtests, Shekel's engine uses the same AI model and strategy prompt you'd run live. At each decision point, the model sees real historical data and makes a decision exactly as it would in production.
Run a backtest before going live. A strategy that sounds good in plain English may behave differently than expected when the AI actually works through real market conditions.
## How to Run a Backtest
Tap **Backtest** in the navigation. Available in the web app at [app.shekel.xyz/backtest](https://app.shekel.xyz/backtest) and the mobile app.
Connect your Shekel API key to load your saved strategy, whitelist, and risk settings automatically. Or configure a custom strategy from scratch.
* **Tokens** — which assets to simulate trading
* **Date Range** — the historical period to test (minimum 3 months recommended)
* **Interval** — how often the AI makes decisions (matches your live agent's run schedule)
* **Model** — which AI model makes the decisions
* **Capital** — starting portfolio value for the simulation
* **Data Sources** — which data sources to include (same options as live)
Before running, you'll see an estimated credit cost. The estimate is conservative — actual cost is settled from real token usage after the run completes, and any over-reservation is refunded automatically.
Tap **Run Backtest**. The engine runs in the cloud — you can close the app and return when it's complete. Active backtests appear on the dashboard.
## What Happens During a Backtest
The engine steps through time at your chosen interval. At each step:
1. Historical market data is assembled for that exact timestamp (prices, order book, technicals, sentiment, etc.)
2. Your custom endpoint is queried for data at that timestamp (if configured)
3. The AI model reads the full context and decides: open (**LONG/SHORT**), **add** to a position, **reduce** (partial close), set or re-tune a **take-profit ladder**, **manage exits** (trail the stop, re-set targets), **flip**, **close**, or **wait**
4. If the decision is actionable, the simulated trade executes at the historical price
5. Portfolio state is updated (position sizes, P\&L, drawdown)
This continues until the backtest period ends. The engine models scale-ins, reduces, flips, take-profit ladders, and stop adjustments **identically to live**, so a strategy that builds, trims, and manages exits behaves the same in simulation as in production.
## Tips for Good Backtests
**Use at least 3 months of data.** Shorter windows may fit noise rather than signal — a strategy that "works" on a 2-week period isn't meaningful.
**Test multiple models on the same strategy.** Different AI models produce meaningfully different results. Claude Opus and Grok 4.3 may reason differently about the same setup.
**Watch for overfitting.** If a strategy only works on one specific time period, it's probably not robust. Test across different market regimes (trending, ranging, high-volatility).
**Compare against your live results.** Once you're live, use the agent chat to compare your live performance against backtest expectations. Divergence is signal — ask your agent why.
**Match your backtest settings to your live settings.** Use the same model, interval, whitelist, and data sources. Differences between backtest and live configurations are a common source of confusion.
## Rigorous Mode (5× range report)
A normal backtest is **one** run — but because the AI runs at a temperature above 0, a single run is just one of many possible outcomes (it can look great or poor by luck). Toggle **🎲 Rigorous (5×)** on the config to run the exact same test **5 times** and see the *range* of what could happen instead of one number.
You get one card (with a live running mean P\&L while the 5 run) and, when all finish, a **Range Report**:
* Average and median return, and the full spread (worst → best run)
* How many of the 5 runs were profitable, and the worst-case drawdown
* A plain-English robustness verdict — **Robust / Moderate / Fragile / Coin-flip**
* A **stress floor** (your worst run) so you judge the downside, not just the upside
A tight band around a positive number = a reliably good strategy; a wide band straddling zero = you got lucky (or unlucky) on a single run. Rigorous costs \~5× a normal run, so it's a premium check best used right before you fund an agent.
Set **Temperature above 0** before running Rigorous — at 0 the 5 runs cluster together and there's little spread to measure.
See the [Shekel Score](/backtesting/results#the-shekel-score) on the Results page — the single live-readiness grade that comes out of a Rigorous set.
## Pause & Resume long runs
Every running test's card has a **⏸ Pause** button. Pause saves the run's full state at its next decision step, bills only what it used so far, and refunds the rest (like Stop, but with a bookmark). The card turns amber (*Paused @ X%*) and **▶ Resume** continues the *same* test from the exact step it paused at. Paused runs stay resumable for **7 days**; **🗑 Kill** discards a paused run immediately. Rigorous packs pause/resume all 5 runs at once.
## Dynamic Whitelist
The **Modify Agent Settings** panel on the Backtest page has a **Dynamic Whitelist** toggle. When on, instead of a fixed token list the engine re-ranks the crypto universe each cycle and rotates to the strongest-trending, most-liquid tokens (your whitelist becomes the starting seed). Config: Rotate Every, Max Slots, **Min Score (0–10)**, Pinned, Max Churn/Cycle. Requires LLM Full mode.
The liquidity data behind the rotation only goes back to **mid-May 2026**. A dynamic-whitelist backtest that *starts* before then can't pick tokens for the early window. For honest tests, start mid-May 2026 or later. "Approximate OI" can fill the gap for rough exploration of older periods, but those early results are estimates, not faithful.
The **Momentum** tab in the left nav shows the same universe ranking live (0–10 momentum score, LONG/SHORT bias, one-line thesis per token) — measuring each token's strength *independent of Bitcoin*. It's read-only and the same board your agent's auto-rotating whitelist draws from.
## Backtest History
Every completed backtest is automatically saved to your account. Your last 5 backtests are available to your agent in chat — ask it to analyze patterns across runs, compare models, or explain why live results differ. Pin one run as your **gold standard** (📌) and the agent measures new variants against it; if an engine upgrade could change results, a banner tells you to re-run the gold standard before comparing.
Your backtest history is also accessible from **Results** in the app for detailed replay and analysis.
# Reading Backtest Results
Source: https://docs.shekel.xyz/backtesting/results
Every metric explained and what to look for
## The Shekel Score
The **Shekel Score (0–100)** is the single answer to *"is this agent live-ready?"* It only appears on a [Rigorous (5×)](/backtesting/overview#rigorous-mode-5-range-report) set — it's a cross-run metric, so a single Explore backtest has no Shekel Score. You see it two places: a compact grade + number chip on the rigorous card, and the full breakdown at the top of the Range Report. One headline grade — **Robust / Solid / Risky / Fragile / Avoid**.
It's deliberately tough and grades the **downside**, not the highlight reel:
* **Realized only.** It scores your *banked* return, not open-position paper gains — a +900% headline that's mostly unrealized marks is exposure, not edge.
* **Consistency is hard-weighted.** An agent profitable in only 3 of 5 runs is capped at "Risky" no matter how big the headline — a coin-flip in a costume isn't live-ready.
* **Disqualifies blowups.** Any run that breached your max-drawdown cap or got liquidated shows **DQ** — because in real life you only run once.
* **Big returns flatten.** Past \~+200% the curve barely moves (huge returns are usually luck or leverage), so a clean +150% can outscore a wild +900%.
Next to the grade you always see **"% realized"** and **"X of 5 profitable"** — the two numbers a flashy headline hides.
***
## Headline Metrics
### Total Return %
The portfolio's percentage gain or loss over the full backtest period, starting from your configured initial capital.
**What to look for:** Absolute return matters less than risk-adjusted return. A 30% return with a 40% max drawdown is worse than a 15% return with a 5% max drawdown.
***
### Sharpe Ratio
Risk-adjusted return: how much return you're getting per unit of volatility.
```
Sharpe = (Portfolio Return - Risk-Free Rate) / Standard Deviation of Returns
```
| Sharpe | Interpretation |
| --------- | ----------------------------------------------- |
| Below 0 | Negative risk-adjusted return — worse than cash |
| 0 – 0.5 | Poor |
| 0.5 – 1.0 | Acceptable |
| 1.0 – 2.0 | Good |
| Above 2.0 | Excellent |
**What to look for:** > 1.0 is a useful bar for a strategy worth running live. Higher is better.
***
### Sortino Ratio
Like Sharpe, but only penalizes **downside** volatility. Upside volatility (big wins) doesn't count against you.
The Sortino is usually higher than the Sharpe. If your Sortino is much higher than your Sharpe, it means most of your volatility comes from large wins — a good sign.
**What to look for:** Same interpretation as Sharpe, but use it alongside Sharpe rather than instead of it.
***
### Max Drawdown %
The worst peak-to-trough portfolio decline during the backtest period.
**Example:** If your portfolio peaked at $12,000 and later bottomed at $9,600 before recovering, your max drawdown was 20%.
**What to look for:** Should be consistent with your configured Max Drawdown limit. If the backtest drawdown frequently exceeded your live drawdown limit, your live agent will pause often.
***
### Win Rate %
Percentage of closed trades that were profitable.
**Caution:** Win rate alone is misleading. A strategy with a 40% win rate can be very profitable if wins are 3x larger than losses. Always look at win rate alongside profit factor.
***
### Profit Factor
Gross profit divided by gross loss across all closed trades.
```
Profit Factor = Total Winning Trade P&L / Total Losing Trade P&L
```
| Profit Factor | Interpretation |
| ------------- | --------------- |
| Below 1.0 | Losing strategy |
| 1.0 – 1.5 | Marginal |
| 1.5 – 2.0 | Healthy |
| Above 2.0 | Strong |
**What to look for:** > 1.5 is a practical threshold for a strategy worth running. > 2.0 is excellent.
***
## Equity Curve
The equity curve plots your portfolio value over time. This is often more informative than any single metric.
**What to look for:**
* **Smooth upward slope** — consistent performance across the period
* **Sharp drops followed by recovery** — high-volatility but mean-reverting; check your max drawdown tolerance
* **Long flat periods** — the strategy sat out a lot; check if this aligns with your WAIT reasoning
* **Consistent decline** — the strategy lost money steadily; the thesis may be wrong for this period
***
## Per-Token Breakdown
Performance statistics for each individual token in your whitelist:
* Win rate per token
* Total P\&L per token
* Number of trades
**What to look for:** Tokens where the agent consistently loses money are candidates to remove from your whitelist. Tokens with high win rates but few trades may need a longer backtest window.
***
## Trade Log
The full list of every decision made during the backtest — including WAIT decisions. Each entry includes:
* Timestamp
* Token and direction
* Entry and exit price
* P\&L on the trade
* The AI's full reasoning at the time of the decision
Reading through the reasoning on a few losing trades often reveals what the strategy is missing or getting wrong.
***
## Common Patterns
This is the most common divergence. Common causes:
* **Lookahead bias** — historical data sources may contain data that wasn't actually available at that timestamp
* **Slippage** — backtests execute at the historical price; live trades execute at the real bid/ask, which is worse
* **Regime change** — the backtest period was favorable; live conditions are different
* **Overfitting** — the strategy was implicitly tuned to work on that specific period
Ask your agent in chat: *"Why do you think my live results differ from the backtest?"*
Healthy for trend-following strategies. A 35% win rate with a 3:1 win/loss ratio is profitable. Check the profit factor — if it's above 1.5 alongside a low win rate, the strategy has a genuine edge.
Often indicates cutting winners too early. The agent may be taking small profits while allowing losses to run. Look at the average winning vs. losing trade size in the trade log.
The strategy may have been fitted (even implicitly) to the market regime at the start of the test window. Try running the same strategy on a different time window to check robustness.
# What Your Agent Knows
Source: https://docs.shekel.xyz/chat/capabilities
Full breakdown of every data source available to your agent in chat
When you send a message, your agent fetches fresh data from all of the following sources before responding. Every answer is grounded in real numbers.
## Live Account & Positions
Your agent has a real-time view of your Hyperliquid account:
* **Account value** — total portfolio value including unrealized P\&L
* **Margin used** — how much of your capital is actively committed
* **Withdrawable balance** — free margin available to deploy
* **Open positions** — every current position with:
* Coin, direction (long/short), and size
* Entry price and current mark price
* Unrealized P\&L in USD and as a percentage
* Leverage
* Estimated liquidation price
**Example questions:**
* *"What's my total account value right now?"*
* *"What positions are you holding?"*
* *"How far am I from liquidation on my SOL long?"*
* *"How much margin do I have left to deploy?"*
***
## Performance & P\&L
Your agent has access to aggregated performance statistics across your trading history:
* **Total trades** executed
* **Win rate** — percentage of profitable trades
* **Total P\&L** — cumulative dollar return
* **7-day P\&L** — performance over the past week
* **30-day P\&L** — performance over the past month
* **Per-token breakdown** — win rate, total P\&L, and trade count for each coin in your whitelist
**Example questions:**
* *"How am I performing this month?"*
* *"What's my win rate over the last 30 days?"*
* *"Which token has made me the most money?"*
* *"Am I profitable overall?"*
***
## Trade & Decision History
Your agent has the last 30 trading decisions stored in its context, including:
* The **token** analyzed
* The **action** taken (LONG, SHORT, CLOSE, or WAIT)
* The full **reasoning** — what data the agent saw and why it acted
* Whether the decision was **executed** or skipped, and why it was skipped if not
* The **timestamp** of the decision
This lets you audit exactly what the agent was thinking at any point.
**Example questions:**
* *"Walk me through your last 5 trades."*
* *"Why did you go long on SOL yesterday?"*
* *"What was your reasoning on the BTC short last week?"*
* *"How many times have you waited vs. traded this month?"*
* *"Why did you skip the ETH trade on Monday?"*
***
## Strategy & Configuration
Your agent knows its own configuration completely:
* The full **strategy prompt** you wrote
* Your **important notes** (hard constraints)
* Current **risk parameters** (max positions, position size range, drawdown limits)
* **Token whitelist**
* **AI model** and **run schedule**
* **Data sources** enabled
This lets you ask the agent to reflect on whether its settings make sense for current market conditions.
**Example questions:**
* *"What's your current strategy?"*
* *"Do you think my max drawdown limit is appropriate?"*
* *"Is my whitelist still the right set of tokens?"*
* *"Should I tighten my position size limits?"*
***
## Strategy Memory
Between runs, your agent maintains an ongoing **strategy memory** — a running self-analysis note it updates over time. This includes observations about what's working, market regime notes, and self-corrections.
The agent references this memory in chat to give you context on how its thinking has evolved.
**Example questions:**
* *"What has your experience been with this strategy so far?"*
* *"Have you noticed any patterns in your wins and losses?"*
* *"What would you change about how you've been trading?"*
***
## Backtest History
Your agent has access to your last 5 completed backtests, including:
* Backtest name and date range
* Tokens tested and model used
* **Total return %**
* **Sharpe ratio**
* **Win rate**
* **Max drawdown**
* **Profit factor**
* Run duration and interval
This enables powerful comparisons between simulated and live performance.
**Example questions:**
* *"Compare my live results to my last backtest."*
* *"Based on my last 3 backtests, what's working?"*
* *"Why is my live win rate lower than the backtest showed?"*
* *"Which model performed best in my backtests?"*
* *"What did the backtest predict my Sharpe ratio would be?"*
***
## What Happens When You Ask
Every chat message triggers a fresh data fetch in parallel:
1. Agent config pulled from the database
2. Live portfolio and positions fetched from Hyperliquid
3. Performance metrics aggregated from trade history
4. Last 30 decisions loaded from logs
5. Strategy memory loaded
6. Last 5 backtest reports loaded
All of this happens before the AI model sees your message. The response you get is always grounded in current data, not a cached snapshot.
# Connect via MCP (Claude, ChatGPT, Cursor…)
Source: https://docs.shekel.xyz/chat/mcp
Talk to your Shekel agent from any AI surface that speaks the Model Context Protocol
You can talk to your Shekel agent from any AI client that supports the **Model Context Protocol (MCP)** — Claude Desktop, ChatGPT, Cursor, Goose, and more. Your agent becomes a tool your favorite LLM can call directly: check positions, review backtests, adjust risk, trigger runs — in plain language, without opening the dashboard.
## Connect (Claude Desktop)
Claude Desktop → **Settings → Connectors → Add custom connector**.
```
https://shekel-v3-mcp.vercel.app/mcp
```
Click **Connect** — Claude opens your browser to the Shekel consent screen on **app.shekel.xyz**. Sign in if you're not already, then click **Approve**.
Back in Claude, ask *"What is my Shekel agent up to?"*
The same flow works in **ChatGPT** (custom MCP), **Cursor**, **Goose**, and any other OAuth-capable MCP client.
## What your AI surface can do
* **Read** — agent state, recent trades, performance, backtest history, reflections, decision history, live HL state, and unread notifications.
* **Act (with your approval)** — run backtests, change agent settings, pause/resume, or trigger a manual run. These execute directly; your AI client shows its own *"Allow this tool?"* prompt as the approval step.
* **Cross-surface sync** — actions and notifications stay in sync with the web app: what you do from Claude shows up there, and vice-versa.
## What it cannot do (hard security boundary)
These are **first-party-only** — your AI surface's token is categorically blocked from them:
* Create a new agent (do that in the app first)
* Move or withdraw funds, bridge, or close positions
* Export or rotate API keys, or manage your wallet
Only the Shekel app and the mobile app — signed in with your account key — can perform fund/key/wallet actions.
## Pricing
* **Chatting with your AI is free** — that conversation runs on your own Claude/ChatGPT, not on Shekel.
* **Most read tools are free** — agent status, trades, performance, backtest history, reflections, notifications, decision history, basic HL state.
* **Premium market-data tools** carry a small per-call credit fee (they pull proprietary/paid data): max pain (50), liquidations (20), open-interest history (15), ETF-flow sentiment (5). Fear & Greed and basic HL state stay free. If your balance is too low, the tool tells you to top up instead of returning data.
* **Compute-metered actions** (backtests, manual runs, your live agent) bill against your Shekel credit balance at the normal rate.
* **BYOK discount** applies no matter where you trigger a run (including from Claude) — *if* you've added your own LLM key on the Settings page. It's opt-in; connecting over MCP does **not** apply it automatically.
## Managing connections
Go to **Settings → MCP Connections** to see every external AI surface you've authorized, and revoke any with one click. Revocation is immediate.
# Agent Chat
Source: https://docs.shekel.xyz/chat/overview
Your direct line to your AI fund manager — with full access to your portfolio, history, and performance
Every Shekel agent has a built-in chat interface — a direct conversation with your AI fund manager. Tap the **chat bubble** in the bottom-right of the dashboard to open it.
This isn't a generic chatbot. Your agent speaks in first person and has live access to everything about your account before responding to any message.
Account value, margin, open positions, unrealized P\&L
Win rate, total P\&L, 7d/30d breakdowns, per-token stats
Last 30 trading decisions with full reasoning
Current strategy, risk limits, whitelist, run schedule
Last 5 completed backtests with metrics
The agent's ongoing self-analysis and notes from prior runs
## Opening the Chat
Tap the **floating chat bubble** in the bottom-right corner of the dashboard. The bubble shows your agent's avatar initial.
The first time you open chat, you'll see **suggested prompts** — tap any to get started, or type your own question.
## What the Agent Will and Won't Do
**Will do:**
* Answer questions about your account, positions, and P\&L using real data
* Walk through its reasoning on recent trading decisions
* Analyze your strategy and suggest improvements
* Compare your live performance to your backtest expectations
* Propose concrete changes to your settings (see [Setting Change Proposals](/chat/setting-proposals))
**Will not do:**
* Make up trades, prices, or performance numbers
* Reference data it hasn't been given
* Execute trades directly from chat (those go through the normal run cycle or Manual Trade)
The agent only references data it receives in its context. If it says it doesn't know something, it genuinely doesn't have that data available.
## How to Switch Chat Models
Tap any model pill in the **chat header** to switch the model powering your conversation. The switch takes effect immediately on your next message.
| Model | Cost | Best For |
| ------------- | ---------- | ----------------------------------------------- |
| Grok Fast | 15 cr/msg | Quick lookups, simple questions |
| Grok 4.3 | 30 cr/msg | Strategy analysis, deeper questions |
| Claude Sonnet | 45 cr/msg | Nuanced review, complex reasoning |
| Claude Opus | 120 cr/msg | Deep portfolio analysis, major strategy reviews |
Your selection is saved across sessions. Start cheap for quick questions; step up when you want a serious review.
# Setting Change Proposals
Source: https://docs.shekel.xyz/chat/setting-proposals
Let your agent propose its own configuration changes — you approve or dismiss
Your agent can propose changes to its own configuration from within a conversation. If you ask it to review your strategy, risk settings, or token whitelist — or if it notices something worth surfacing based on your performance data — it may respond with a **formal proposal card** alongside its reply.
## How It Works
You ask a question. The agent reasons about it. If it believes a specific setting change is warranted, it returns both a conversational reply and a structured proposal.
The proposal card shows:
* **Which setting** it wants to change
* **The proposed new value**
* **Its reasoning** — drawn from your performance data, backtest history, or market analysis
You tap **Apply** or **Dismiss**. That's it.
The agent cannot change its own settings without your explicit approval. A proposal with no response from you changes nothing.
## Applying a Proposal
Tap **Apply** on the proposal card. The change takes effect immediately and is active on the **next run cycle**.
Changes are applied through the same update path as manual edits — the agent's live configuration is updated in the backend.
## Dismissing a Proposal
Tap **Dismiss** to reject the suggestion. The setting stays as-is. You can tell the agent you disagree and ask it to reason further, or ask for an alternative.
## What Can Be Proposed
The agent can propose changes to any of the following:
| Setting | Example Proposal |
| --------------------- | ----------------------------------------------------------------------------------- |
| Strategy prompt | "I'd like to add a rule about avoiding trades when funding rates exceed 0.1%" |
| Important notes | "Add a hard rule to close all positions on Fridays before 4pm UTC" |
| Token whitelist | "Remove WIF — I've had 0 wins on it across 12 trades. Add HYPE instead." |
| Run schedule | "Switch from 1h to 4h — the 1h schedule is generating too many WAIT decisions" |
| Max drawdown % | "Increase from 10% to 15% — the 10% limit has been triggering on normal volatility" |
| Max daily loss % | "Tighten from 5% to 3% based on your average daily volatility" |
| Max open positions | "Reduce from 5 to 3 — you currently hold 3.1 positions on average" |
| Position size min/max | "Increase min to 10% — your 5% positions have lower win rate than your larger ones" |
## Example Conversation
**You:** Review my current risk settings and tell me if anything needs adjusting.
**Agent:** Looking at your last 30 decisions and performance data:
Your max drawdown is set to 10%. Over the past month, your strategy has naturally pulled back 8–9% during normal market fluctuations three separate times, causing automatic pauses. Each of those pauses interrupted setups that subsequently recovered and would have been profitable.
Your actual strategy volatility profile suggests a 15% drawdown limit would give the agent room to operate without unnecessary interruptions while still protecting against genuine adverse moves.
*\[Proposal Card]*\
**Setting:** Max Drawdown %\
**Current:** 10%\
**Proposed:** 15%\
**Reasoning:** Three pauses over 30 days triggered by normal volatility, not actual drawdown events. Average peak pullback over the period was 8.3%.
\[**Apply**] \[**Dismiss**]
***
**You:** That makes sense. Apply it.
*(Tap Apply — takes effect on next run)*
***
## Tips for Eliciting Proposals
You don't need to ask for a proposal explicitly. Ask the agent to **review** something and it will decide whether a change is warranted:
* *"Review my current risk settings."*
* *"Is my strategy still appropriate for the current market?"*
* *"Look at my win rate by token — should I change my whitelist?"*
* *"Based on my last 5 backtests, what should I adjust?"*
* *"Do you think my run schedule is right for this strategy?"*
# Credits
Source: https://docs.shekel.xyz/credits
How Shekel's credit system works
Credits are Shekel's unit of usage. Every agent run and chat message costs credits. You start with free credits and can earn more by verifying your phone or staking SHEKEL.
Credits live in **one shared pool per account**, not per agent. Top up once and every agent you own draws from the same balance. Sign in with your wallet under **Settings → Account** to create (or find) your account — it automatically links the agents already on your device so they all share the pool.
## Earning Credits
| Source | Amount | How |
| ------------------- | ------------ | ---------------------------------------------------------- |
| Download the app | **200 cr** | Automatic on first open |
| Verify phone number | **1,000 cr** | Account → Verify Phone Number |
| Stake SHEKEL tokens | **Ongoing** | Proportional to your stake — see [Staking](/token/staking) |
| Purchase | **Variable** | Buy Credits in the app |
## Credit Costs
### Live Agent
Each time your agent runs and calls the AI model, it costs credits. The cost per run depends on:
* **AI model** — Opus models cost more than Flash models
* **Whitelist size** — more tokens = more data in the prompt = more tokens processed
* **Data sources enabled** — each additional source adds context
Higher-frequency schedules (every 15 min) multiply the per-run cost by how often the agent runs. A 15-min schedule runs \~96x per day vs. \~6x for a 4h schedule.
### Chat Messages
Each chat message costs credits based on the model:
| Model | Cost per message |
| ------------- | ---------------- |
| Grok Fast | 15 cr |
| Grok 4.3 | 30 cr |
| Claude Sonnet | 45 cr |
| Claude Opus | 120 cr |
### Backtests
The credit estimate shown before running a backtest is a conservative pre-reservation based on expected token usage. Actual cost is settled after the run from real token counts, and **any over-reservation is refunded automatically**.
Factors that increase backtest credit cost:
* More tokens in your whitelist
* Longer date range
* More data sources enabled
* Higher-cost AI model
To minimize backtest cost: use a lighter model (DeepSeek Flash, Llama 3.3), narrow your whitelist, shorten the window, or disable unused data sources.
### BYOK — Bring Your Own Key (60% off)
If you have your own API key from a supported provider (**REI Labs, Anthropic, OpenAI**), plug it in under **Settings → Inference Provider**. With BYOK active, your credit cost drops by **60%** — you still pay the platform layer (data sources, infrastructure, surge capacity) but skip the inference markup, since you're covering that directly with your provider.
The discount applies to backtests **and** live runs, and follows you everywhere you trigger a run — including from an MCP client like Claude. It's opt-in via Settings; it is **not** applied automatically.
### MCP / external AI surfaces
Talking to your agent from Claude/ChatGPT over [MCP](/chat/mcp) is mostly free, with a few metered tools:
* **Chatting is free** — that conversation runs on your own Claude/ChatGPT, not on Shekel.
* **Most read tools are free** — agent status, trades, performance, backtest history, reflections, notifications, decision history, basic HL state.
* **Premium market-data tools** cost a small per-call fee: max pain (50), liquidations (20), open-interest history (15), ETF-flow sentiment (5). Fear & Greed and basic HL state stay free.
* **Backtests, manual runs, and your live agent** bill at the normal credit rate (with the BYOK discount if enabled).
## Checking Your Balance
Go to **Account** → Credits balance is shown at the top of the screen.
The balance is also shown in the left nav panel (tap the Shekel logo to open it).
## Running Out of Credits
Your live agent will **pause automatically** if your balance reaches zero. It will resume once credits are added. You'll receive a notification when the agent pauses for this reason.
Open positions are not closed when the agent pauses due to depleted credits — they remain active on Hyperliquid and continue to be affected by market movement.
## Buy Credits
Tap **Buy Credits** in the left nav, or go to **Account → Buy Credits**. Credits settle on Base network and are available in your account within seconds.
# Quick Start
Source: https://docs.shekel.xyz/getting-started
From download to live agent in under 10 minutes
Open the web app at **[app.shekel.xyz](https://app.shekel.xyz)** — it runs in any desktop or mobile browser, no install required.
Prefer a native app? The Shekel **Android** app is also available — grab the latest APK from [shekel.xyz](https://shekel.xyz) and enable **Install from unknown sources** if prompted. (iOS is coming soon.)
**On the web app:** click **Sign in** and connect your wallet — you sign one free message (no transaction, no gas) to create your account. A brand-new wallet that passes a light reputation check gets a welcome credit bonus.
**On mobile:** sign in with email or Google and receive **200 free credits** automatically on first open.
Go to **Account → Verify Phone Number**.
Enter your number, receive a code by SMS, and enter it in the app. Phone verification awards **1,000 bonus credits**.
Go to **Account → Connect Wallet** to link an EVM-compatible wallet (Phantom, MetaMask, Coinbase, or any WalletConnect wallet).
This is required only if you want to stake SHEKEL tokens for ongoing credit rewards. It is not required to run an agent.
Tap **Launch Agent** in the app.
* Write your [strategy prompt](/agent/strategy) (or use the Quick Launch default to get started)
* Set your [risk parameters](/agent/settings)
* Choose your [AI model](/agent/models)
* Tap **Launch**
Launching **creates a brand-new Hyperliquid account dedicated to this agent**. You don't need a Hyperliquid account beforehand, and you don't create any API keys yourself — Shekel generates the account and its trade-only trading key for you, as part of the launch.
You cannot attach an existing Hyperliquid account to an agent. Each agent trades from its own Hyperliquid account, created at launch. This is what lets the agent trade autonomously without you signing every order.
Your new agent has its own **deposit address**, shown on the dashboard.
1. In the app, copy the agent's **Deposit Address (Arbitrum · USDC)**
2. Send **USDC on Arbitrum** to that address
3. Shekel auto-bridges it into the agent's Hyperliquid account (usually \~60 seconds)
4. The minimum recommended starting balance is **\$100 USDC**
Your agent starts trading on its first scheduled interval once the deposit confirms.
On a block explorer, your deposit will look like it arrives and immediately leaves the deposit address — that's the automatic bridge into Hyperliquid, not a withdrawal. See [Where your deposit goes](/privacy#where-your-deposit-goes).
You can run backtests without funding anything — a funded account is only needed to trade live.
The account is yours. You can withdraw to any Arbitrum address from **Account → Withdraw** at any time, and you can export the account's private key (**Account → Retrieve Private Key**, protected by a step-up security check) to take sole control of it outside Shekel.
## What Happens Next
Once launched, your agent runs on the schedule you set. After each run you'll see a decision card on the home screen showing what the agent did and why.
The **chat bubble** (bottom-right of the dashboard) is your direct line to your agent. Ask it what it's thinking, how you're performing, or to review your strategy. See [Agent Chat](/chat/overview) for everything it can do.
## Before You Go Live
We strongly recommend running at least one backtest against your strategy before deploying real capital. See [Backtesting](/backtesting/overview) to simulate your strategy against historical data first.
# What is Shekel?
Source: https://docs.shekel.xyz/introduction
AI-powered crypto trading agents on Hyperliquid
Shekel lets you deploy an AI trading agent that monitors the crypto market and executes trades on your behalf on [Hyperliquid](https://app.hyperliquid.xyz) — the highest-performance decentralized perpetuals exchange.
You write a plain-English strategy. The agent reads live market data, runs it through an AI model of your choice, and places trades automatically. Launching an agent **creates a dedicated Hyperliquid account for it** — you fund that account, and you can withdraw from it or export its private key at any time. You stay in control: set risk limits, choose which tokens to trade, and pause or stop at any time.
Set up and deploy your agent in under 10 minutes.
The strategy prompt is everything. Learn what works.
Your agent has live access to your portfolio, performance, and history — ask it anything.
Simulate any strategy against historical data before going live.
## How It Works
A plain-English prompt describes how you want the agent to think — what signals to weight, how aggressive to be, which market conditions to avoid.
Before every decision, the agent assembles a full market context: prices, order book depth, funding rates, technical indicators, sentiment, whale flows, and any custom data you provide.
The context is passed to your chosen AI model (Claude, Grok, DeepSeek, or others). The model reasons through your strategy and outputs a structured decision: LONG, SHORT, CLOSE, or WAIT — with full reasoning.
If the decision is actionable, Shekel places the order on your agent's Hyperliquid account using that agent's **trade-only** trading key — it can open and close positions, but cannot withdraw.
## Key Features
* **AI fund manager** — multiple frontier models available; swap at any time
* **Agent chat** — your agent has full context and can answer questions, analyze your performance, and propose strategy changes
* **Backtest engine** — simulate any strategy against historical Hyperliquid data, with LLM-driven decision making
* **Custom data endpoints** — inject any external signal, on-chain metric, or proprietary indicator into your agent's context
* **SHEKEL token** — stake SHEKEL on Base to earn passive daily credits
* **Your account, your keys** — each agent trades from its own Hyperliquid account, created at launch; withdraw to any Arbitrum address at any time, or export the account's private key to take sole control of it
All AI inference runs through [Venice AI](https://venice.ai), providing private, uncensored model access. Your strategy, prompts, and trade data are never used to train AI models.
# Privacy & Security
Source: https://docs.shekel.xyz/privacy
How Shekel protects your funds, strategy, and data
## Your Funds
Every agent trades from **its own Hyperliquid account**, created for you when you launch it. You fund that account by sending USDC to the agent's deposit address; Shekel bridges it into Hyperliquid automatically. You cannot attach a pre-existing Hyperliquid account to an agent.
### Why Shekel creates the account
Three reasons, and they're worth understanding:
1. **One-click launch.** Creating a Hyperliquid account, funding it, and wiring up trading access is a multi-step, error-prone process. Shekel does all of it atomically when you launch — your agent is trade-ready the moment its deposit confirms.
2. **The agent can be structurally sandboxed.** Because Shekel provisions the account, it hands the AI a *trade-only* key from day one (details below). An account you brought yourself couldn't be locked down this way without handing Shekel its owner key — which would be strictly worse for you.
3. **Honest economics.** Launching and holding an agent is free because Shekel earns a small builder fee on each fill — the standard Hyperliquid mechanism, applied per-trade and visible on-chain. No deposit fees, no withdrawal fees, no cut of your balance. Shekel only earns when your agent actually trades.
### Where your deposit goes
Your deposit takes an automated journey, and **every hop lands at your own agent's address**:
1. You send USDC to your agent's deposit address.
2. Within about a minute, Shekel's bridge sweeps it onward automatically — cross-chain if needed, then into Hyperliquid's official bridge contract.
3. The USDC arrives in your agent's Hyperliquid account, where it shows on your dashboard as withdrawable balance.
If you watch the deposit address on a block explorer, you'll see funds arrive and then leave again almost immediately. **That's the automatic bridge, not a withdrawal** — follow the transaction and it ends at your agent's own Hyperliquid account. You can verify independently anytime by searching your agent's wallet address on a Hyperliquid explorer such as hypurrscan.io.
### The two-key model
Each agent has two separate keys:
* **Trading key (trade-only)** — what the agent uses to place and cancel orders. It **cannot** withdraw funds. This is the key the AI's decisions flow through, so an agent can never move money out, no matter what it decides.
* **Account key** — the Hyperliquid account's owner key. Shekel holds it encrypted and uses it only for actions you initiate or authorize: bridging in your deposits, withdrawals you request in the app, and the one-time Hyperliquid approvals an agent needs before it can trade.
## You Can Take Control at Any Time
You are never locked in. Shekel's custody is custody-on-demand — two exit hatches are always open:
* **Withdraw** — send USDC to any Arbitrum address from **Account → Withdraw**. The AI cannot block, delay, or intercept a withdrawal you request.
* **Export the account key** — **Settings → Export Wallet** hands you the account's private key after a step-up security check (a wallet signature or SMS code). With it you control the account directly on Hyperliquid, independent of Shekel, permanently.
## Key Encryption
Both keys are encrypted with AES-256 before being stored, and the encryption key is held separately from the database.
## Private AI Inference
All LLM inference runs through [Venice AI](https://venice.ai), which provides private, uncensored model access with a strict no-training policy:
* Your strategy prompt is never used to train any AI model
* Your trading decisions and reasoning are never used for model training
* Venice does not log or retain your prompts beyond the duration of the API call
## Your Strategy Is Private
Your strategy prompt, important notes, token whitelist, and risk parameters are stored encrypted in the Shekel database. Shekel does not share or sell your trading strategy data.
## Wallet Connection (Staking Only)
Connecting a wallet in the app is optional and only required for SHEKEL token staking. Wallet connection uses standard EVM signing — Shekel never asks for your seed phrase or private key.
The wallet verification signature (SIWE — Sign In With Ethereum) is a gasless, off-chain message that proves you own the wallet. It does not authorize any transfer or smart contract interaction.
## What Shekel Can and Cannot Do
| | Shekel Can | Shekel Cannot |
| -------- | ------------------------------------- | ----------------------------------------- |
| Trading | Place and cancel orders | Withdraw funds |
| Data | Read your portfolio and trade history | Access wallet private keys |
| Strategy | Store and apply your strategy | Share it with third parties |
| Tokens | Stake/unstake via on-chain contract | Move tokens without your wallet signature |
# SHEKEL Token & Staking
Source: https://docs.shekel.xyz/token/staking
Stake SHEKEL on Base to earn ongoing passive credit rewards
The SHEKEL token is Shekel's native token on Base network. Staking SHEKEL earns you a daily allocation of credits — proportional to your share of the total staked supply.
## Token Details
| | |
| ---------------- | ---------------------------------------------------------------------- |
| **Token** | SHEKEL |
| **Chain** | Base (chainId 8453) |
| **Contract** | `0x5F6a682A58854C7fBE228712aEEFfcCDe0008Ac0` |
| **Available on** | Uniswap (Base), [app.shekel.xyz/tokens](https://app.shekel.xyz/tokens) |
## How Daily Credits Work
A fixed pool of credits is distributed every 24 hours to all stakers, proportional to stake.
```
Your daily credits = (your staked SHEKEL / total staked SHEKEL) × daily pool
```
The daily pool size is displayed on the Token Dashboard in the app. As more SHEKEL is staked, the per-token credit rate changes — staking earlier locks in a larger share.
Tap the **⚡ Daily credits** row on the Token Dashboard to see a full explanation of the formula and your projected allocation.
## How to Stake
Go to **Account → Connect Wallet** to link an EVM-compatible wallet (Phantom, MetaMask, Coinbase, or any WalletConnect wallet).
Sign a message to link your connected wallet to your Shekel agent account. This is a gasless signature — it doesn't authorize any transfer. Required to receive staking credit rewards.
Buy SHEKEL on [Uniswap (Base)](https://app.uniswap.org) or [app.shekel.xyz/tokens](https://app.shekel.xyz/tokens). Make sure you have a small amount of ETH on Base for gas.
Go to **SHEKEL Token** in the app. Enter the amount to stake and tap **Stake**.
If this is your first time staking, you'll see two wallet prompts: first to approve the token spend, then to stake. This is normal.
## Unstaking
Enter the amount to unstake and tap **Unstake**. Unstaking begins a **cooldown period** — the duration is shown inline with the unstake input.
Unstaking is not immediate. Your SHEKEL enters a cooldown queue and cannot be traded or moved during this period.
Once the cooldown completes, your SHEKEL appears as a **claimable tranche** in the Pending Unstakes section. Tap **Claim** to receive your tokens back to your wallet.
## Rewards
Accumulated SHEKEL staking rewards are shown in the **Rewards** section of the Token Dashboard. Tap **Claim** to collect them to your wallet at any time.
Rewards are in SHEKEL tokens. The APR shown on the dashboard is annualized and based on current staking pool size and reward rate.
## APR
Staking APR is displayed on the Token Dashboard and updated in real time. APR varies based on:
* Total SHEKEL staked (larger stake = lower APR per token, same total pool)
* Current reward stream status (active vs. inactive)
The APR is displayed as inactive if the current reward distribution period has ended and a new one hasn't started.
# Troubleshooting
Source: https://docs.shekel.xyz/troubleshooting
Common issues and how to fix them
**Check these in order:**
1. **Deposit confirmed** — Go to Account and confirm your Hyperliquid deposit shows as confirmed. It can take a few minutes after your Hyperliquid account shows the USDC balance.
2. **Agent is active** — On the dashboard, confirm the status pill shows LIVE (not PAUSED or DISCONNECTED).
3. **Credits available** — Go to Account and check your credit balance. The agent pauses automatically when credits reach zero.
4. **Next run countdown** — The dashboard shows when the agent will next run. If the countdown is there, it's working — it just hasn't fired yet.
Higher-frequency schedules and larger token whitelists use significantly more credits.
**To reduce credit consumption:**
* Switch from a 15-min or 30-min schedule to 1h or 4h
* Reduce your whitelist to 3–5 tokens
* Disable data sources not referenced in your strategy
* Switch to a lighter model (DeepSeek Flash, Llama 3.3)
Go to **Buy Credits** (left nav or Account screen) to top up, or go to **Token Dashboard** to stake SHEKEL for ongoing passive credit rewards.
If the agent's decision was to trade but the order wasn't placed:
1. Check your Hyperliquid account has sufficient margin for the position size
2. Open the trade log on the dashboard — every skipped trade has a reason logged ("insufficient margin", "position limit reached", etc.)
3. The agent may have decided to WAIT — WAIT decisions are logged with full reasoning. Open the decision details to read why.
1. Make sure you have a stable internet connection
2. Try force-closing and reopening the app
3. If the error persists, the backtest engine may be temporarily unavailable. Check again in a few minutes.
Backtests run in the cloud — you can close the app and return later. Active runs appear on the dashboard.
**For live agents:**
* Confirm the URL is `https://` (not `http://`)
* Test the URL directly in a browser — it should return valid JSON
* Confirm the endpoint responds in under 5 seconds
* Check the URL resolves to a public IP (not localhost or a private range)
**For backtests:**
* Verify your response includes the `data` array with `time` fields in milliseconds
* Confirm timestamps are aligned to 4h UTC boundaries (00:00, 04:00, 08:00, 12:00, 16:00, 20:00)
* If you've updated historical data, clear the cache at `.cache/custom/` to force a fresh fetch
* Check that `start_ms` and `end_ms` parameters are handled correctly — the engine passes them as query strings
See [Custom Data Endpoint](/agent/custom-data) for the full API contract.
If you see stale data after reinstalling:
Go to **Android Settings → Apps → Shekel → Clear Data**, then reopen the app.
This clears the local cache only. Your agent and its Hyperliquid account live on your Shekel account — sign back in and everything is restored.
1. Make sure you're on the correct network — SHEKEL staking is on **Base** (chainId 8453)
2. Try a different wallet app (MetaMask, Phantom, or Coinbase Wallet all work)
3. Ensure your wallet app is up to date
4. Try disconnecting and reconnecting from **Account → Connect Wallet**
This is expected behavior. If your portfolio dropped to or below your Max Drawdown threshold, the agent paused automatically.
1. Review your open positions — they remain active and may need to be managed manually
2. If the drawdown was due to normal market volatility rather than a strategy failure, consider increasing your Max Drawdown % in Modify Agent
3. Tap **Resume** on the dashboard when you're ready to restart
Your agent in chat can help you analyze whether the pause was warranted: *"You paused for drawdown. Walk me through what happened."*
## Still Need Help?
Join the community and ask in #support
[support@shekel.xyz](mailto:support@shekel.xyz)