@bitget-ai/getagent-skill 0.2.1

package/skills/getagent/examples/btc-ema-cross-demo/src/main.py

@@ -0,0 +1,88 @@
+"""Entry point for the BTC EMA Crossover Demo Playbook.
+
+For backtest_support: full playbooks, the platform injects
+runtime.evaluation_mode="historical" on /api/v1/playbook/run. We only handle
+that path here; live cron is not configured for this demo.
+"""
+import math
+from typing import Any
+
+from getagent import backtest, data, runtime
+
+
+def _sanitize(value: Any) -> Any:
+    if isinstance(value, float) and not math.isfinite(value):
+        return None
+    return value
+
+
+def _sanitize_metrics(metrics: dict[str, Any]) -> dict[str, Any]:
+    return {key: _sanitize(val) for key, val in metrics.items()}
+
+
+def run() -> None:
+    cfg = runtime.manifest.get("strategy_config", {}) or {}
+    symbols = cfg.get("trading_symbols") or ["BTCUSDT"]
+    symbol = symbols[0]
+
+    bars = data.crypto.futures.kline(
+        symbol=symbol,
+        interval="1h",
+        limit=1000,
+    )
+    replay_frame = backtest.prepare_frame(bars, datetime_index="date")
+
+    if replay_frame.empty:
+        runtime.emit_signal(
+            action="watch",
+            symbol=symbol,
+            confidence=0.0,
+            metrics={"rows": 0},
+            meta={"reason": "no historical bars returned"},
+        )
+        return
+
+    instrument_key = f"{symbol}.BINANCE"
+    result = backtest.run(
+        ohlcv_data={instrument_key: replay_frame},
+        spec=runtime.backtest_spec,
+    )
+
+    chart_path = backtest.generate_chart(result)
+    summary = result.summary or {}
+    net_pnl_raw = summary.get("net_pnl", 0)
+    try:
+        net_pnl = float(net_pnl_raw or 0)
+    except (TypeError, ValueError):
+        net_pnl = 0.0
+
+    action = "long" if net_pnl > 0 else "watch"
+    metrics = _sanitize_metrics(
+        {
+            "total_return_pct": result.total_return_pct,
+            "net_pnl": net_pnl,
+            "starting_balance": summary.get("starting_balance"),
+            "sharpe_ratio": result.sharpe_ratio,
+            "max_drawdown_pct": result.max_drawdown_pct,
+            "win_rate": result.win_rate,
+            "total_trades": result.total_trades,
+            "profit_factor": result.profit_factor,
+            "rows": len(replay_frame),
+        }
+    )
+
+    runtime.emit_signal(
+        action=action,
+        symbol=symbol,
+        confidence=_sanitize(result.win_rate) or 0.0,
+        metrics=metrics,
+        meta={
+            "chart_path": chart_path,
+            "fast_period": cfg.get("fast_period"),
+            "slow_period": cfg.get("slow_period"),
+        },
+    )
+
+
+if __name__ == "__main__":
+    run()

package/skills/getagent/examples/btc-ema-cross-demo/src/strategy.py

@@ -0,0 +1,118 @@
+from decimal import Decimal
+from typing import Optional
+
+from nautilus_trader.config import StrategyConfig
+from nautilus_trader.model.data import Bar, BarType
+from nautilus_trader.model.enums import OrderSide, TimeInForce
+from nautilus_trader.model.identifiers import InstrumentId
+from nautilus_trader.model.instruments import Instrument
+from nautilus_trader.model.objects import Quantity
+from nautilus_trader.trading.strategy import Strategy
+
+
+class EmaCrossStrategyConfig(StrategyConfig):
+    instrument_id: Optional[InstrumentId] = None
+    bar_type: Optional[BarType] = None
+    instrument_ids: tuple[InstrumentId, ...] = ()
+    bar_types: tuple[BarType, ...] = ()
+    trade_size: str = "0.01"
+    fast_period: int = 12
+    slow_period: int = 26
+
+
+class EmaCrossStrategy(Strategy):
+    def __init__(self, config: EmaCrossStrategyConfig) -> None:
+        super().__init__(config)
+        self.cfg = config
+        self._closes: list[float] = []
+        self._fast_ema: Optional[float] = None
+        self._slow_ema: Optional[float] = None
+        self._prev_diff: Optional[float] = None
+        self._position: str = "NONE"
+        self._instrument: Optional[Instrument] = None
+
+    def on_start(self) -> None:
+        bar_type = self.cfg.bar_type or (
+            self.cfg.bar_types[0] if self.cfg.bar_types else None
+        )
+        instrument_id = self.cfg.instrument_id or (
+            self.cfg.instrument_ids[0] if self.cfg.instrument_ids else None
+        )
+        if bar_type is None or instrument_id is None:
+            raise RuntimeError("bar_type and instrument_id must be set")
+        self._instrument = self.cache.instrument(instrument_id)
+        self.subscribe_bars(bar_type)
+
+    def on_bar(self, bar: Bar) -> None:
+        close = float(bar.close)
+        self._closes.append(close)
+
+        # Need enough warm-up before either EMA is meaningful.
+        warmup = max(self.cfg.slow_period, self.cfg.fast_period) + 1
+        if len(self._closes) < warmup:
+            self._fast_ema = self._update_ema(self._fast_ema, close, self.cfg.fast_period)
+            self._slow_ema = self._update_ema(self._slow_ema, close, self.cfg.slow_period)
+            return
+
+        self._fast_ema = self._update_ema(self._fast_ema, close, self.cfg.fast_period)
+        self._slow_ema = self._update_ema(self._slow_ema, close, self.cfg.slow_period)
+
+        diff = self._fast_ema - self._slow_ema  # type: ignore[operator]
+        if self._prev_diff is None:
+            self._prev_diff = diff
+            return
+
+        cross_up = self._prev_diff <= 0.0 < diff
+        cross_down = self._prev_diff >= 0.0 > diff
+        self._prev_diff = diff
+
+        instrument = self._instrument
+        if instrument is None:
+            return
+        qty = Quantity(Decimal(self.cfg.trade_size), instrument.size_precision)
+
+        if self._position == "NONE":
+            if cross_up:
+                self._submit(instrument.id, OrderSide.BUY, qty)
+                self._position = "LONG"
+            elif cross_down:
+                self._submit(instrument.id, OrderSide.SELL, qty)
+                self._position = "SHORT"
+            return
+
+        if self._position == "LONG" and cross_down:
+            self._close_open(instrument.id, OrderSide.SELL)
+            self._position = "NONE"
+        elif self._position == "SHORT" and cross_up:
+            self._close_open(instrument.id, OrderSide.BUY)
+            self._position = "NONE"
+
+    @staticmethod
+    def _update_ema(prev: Optional[float], value: float, period: int) -> float:
+        if prev is None:
+            return value
+        alpha = 2.0 / (period + 1)
+        return alpha * value + (1.0 - alpha) * prev
+
+    def _submit(
+        self,
+        instrument_id: InstrumentId,
+        side: OrderSide,
+        quantity: Quantity,
+    ) -> None:
+        order = self.order_factory.market(
+            instrument_id=instrument_id,
+            order_side=side,
+            quantity=quantity,
+            time_in_force=TimeInForce.GTC,
+        )
+        self.submit_order(order)
+
+    def _close_open(self, instrument_id: InstrumentId, side: OrderSide) -> None:
+        for position in self.cache.positions_open(instrument_id=instrument_id):
+            self._submit(instrument_id, side, position.quantity)
+
+    def on_stop(self) -> None:
+        if self._instrument is not None:
+            self.cancel_all_orders(self._instrument.id)
+            self.close_all_positions(self._instrument.id)

package/skills/getagent/references/api/enable.md

@@ -0,0 +1,95 @@
+# Enable / Disable Playbook
+
+Subscribe or unsubscribe a user from a published Playbook.
+
+Subscribing deploys a published Playbook version for one user. It does not
+create a new strategy, a new public version, or a private package fork.
+
+## `POST /api/v1/playbook/enable`
+
+**Auth**: `ACCESS-KEY` header from the Bitget OpenAPI credential. Missing it returns 401.
+
+```json
+{
+  "version_id": "version-...",
+  "chat_id": "123456789",
+  "channel": "telegram",
+  "schedule_timezone": "Asia/Shanghai"
+}
+```
+
+Enables the published version for the current user and stores the Telegram
+`chat_id` used for signal delivery.
+
+**Important:** `chat_id` is required for Telegram delivery.
+`schedule_timezone` is optional. When omitted, the server uses the user's
+profile timezone, then `manifest.schedule.tz`, then `Asia/Shanghai`.
+
+### Success Response
+
+```json
+{
+  "instance_id": "inst-...",
+  "strategy_id": "strategy-...",
+  "version_id": "version-...",
+  "schedule_tz": "Asia/Shanghai",
+  "status": "active"
+}
+```
+
+### Subscription Semantics
+
+Subscribing means:
+
+- a `PlaybookInstance` points at the immutable published `version_id`
+- per-user `config_overrides` are stored on the deployment instance
+- a personal reminder named `playbook-instance:{instance_id}` drives execution
+- the effective schedule timezone is stored on the instance
+- future executions run with that subscriber's own trading context
+- any trade-capable behavior still respects the Playbook's published guard mode
+- published Playbooks with `runtime_profile: deterministic` can be enabled
+- published Playbooks with `runtime_profile: llm_bounded` can also be enabled when the deployment has managed Playbook LLM runtime enabled
+
+Subscription does **not** mean:
+
+- enabling automatic follow trading without the user's explicit mode choice
+- forcing a live-only strategy to pretend it has historical backtests
+- granting users permission to edit the Playbook's core logic
+- creating another Playbook strategy or version just because parameters changed
+
+## `POST /api/v1/playbook/disable`
+
+**Auth**: `ACCESS-KEY` header from the Bitget OpenAPI credential. Missing it returns 401.
+
+```json
+{
+  "instance_id": "inst-..."
+}
+```
+
+Disables one deployed subscription instance so the user stops receiving signals.
+The server also disables that instance's personal reminder.
+
+### Disable Response
+
+```json
+{
+  "instance_id": "inst-...",
+  "strategy_id": "strategy-...",
+  "version_id": "version-...",
+  "status": "disabled"
+}
+```
+
+### Auto-trading Note
+
+If a Playbook advertises automated trading support, the effective behavior still
+depends on its published metadata:
+
+- `execution_mode`
+- `follow_trade_supported`
+
+Recommended defaults:
+
+- replayable strategies can opt into `follow_trade` when follow trading is supported
+- live-only strategies should default to `signal_only`

package/skills/getagent/references/api/error-responses.md

@@ -0,0 +1,77 @@
+# Error Responses
+
+Error response format for all Playbook API endpoints.
+
+## Standard Format
+
+```json
+{
+  "detail": "Error description"
+}
+```
+
+Or with structured error list:
+
+```json
+{
+  "detail": {
+    "errors": [
+      "manifest.yaml: missing 'name'",
+      "src/main.py: blocked import 'requests' (line 3)"
+    ]
+  }
+}
+```
+
+## Authentication Contract
+
+Every authenticated Playbook endpoint on the prod OpenAPI gateway requires the following header. Missing it returns 401:
+
+- `ACCESS-KEY` — Bitget OpenAPI access key for the caller
+
+`X-User-Id`, `X-Api-Key`, and `X-Principal-Id` are **not** prod OpenAPI client credentials here. The gateway resolves the caller from `ACCESS-KEY`; do not use backend-internal identity headers in client code.
+
+If an access key is revoked or cannot resolve to an active principal, authenticated endpoints return 403.
+
+## HTTP Status Codes
+
+| Status | Meaning | Common Scenario |
+|--------|---------|-----------------|
+| 200 | Success | Normal response |
+| 401 | Unauthorized | Missing `ACCESS-KEY` header |
+| 403 | Forbidden | Access key has been revoked, principal not found / inactive, or caller is not the resource owner |
+| 404 | Not Found | draft_id or version_id does not exist |
+| 409 | Conflict | Status doesn't allow operation; user already has another active Playbook; Playbook is live-only; or the declared runtime profile is not currently executable |
+| 413 | Payload Too Large | Upload exceeds 10MB |
+| 422 | Validation Failed | Incomplete structure, missing fields, blocked imports, etc. |
+| 503 | Service Unavailable | Sandbox pool not ready |
+
+## Validation Error Details (422)
+
+The upload endpoint returns 422 for:
+
+**Structure**
+- `Missing manifest.yaml`
+- `Missing src/main.py`
+
+**Fields**
+- `manifest.yaml: missing 'name'`
+- `manifest.yaml: invalid name 'My Strategy' (must be DNS label format)`
+- `manifest.yaml: decision_mode must be one of ['agentic', 'deterministic', 'llm_assisted']`
+- `manifest.yaml: live-only playbooks cannot default to execution_mode 'follow_trade'`
+- `manifest.yaml: runtime_profile 'llm_bounded' requires backtest_support = 'none'`
+- `backtest.yaml is only allowed when manifest.yaml sets backtest_support = 'full'`
+
+**Code**
+- `src/main.py syntax error at line 5: invalid syntax`
+- `src/main.py: blocked import 'requests' (line 3)`
+- `src/main.py: disallowed import 'some_unknown_lib' (line 7)`
+
+## Handling Recommendations
+
+1. **401** — Make sure `ACCESS-KEY` is sent.
+2. **403 revoked key** — The access key was revoked server-side; mint a new one and retry.
+3. **409 publish status conflict** — Publish only a draft that has the required evidence; do not bump `manifest.version`
+4. **409 backtest/runtime conflict** — Check `backtest_support` and `runtime_profile`. If the strategy is `none` or `llm_bounded`, use paper/live evidence instead of historical backtest claims
+5. **422 validation failed** — Fix each error in the `errors` list and re-upload
+6. **503 sandbox unavailable** — Wait or contact ops

package/skills/getagent/references/api/index.md

@@ -0,0 +1,38 @@
+# Playbook API Index
+
+This folder documents the HTTP control plane for Playbook packaging,
+publication, execution, and subscription management.
+
+Prod OpenAPI base URL: `https://api.bitget.com`.
+Authenticated calls use the `ACCESS-KEY` header.
+
+Use these docs after the local package is ready. For Python imports inside
+`src/**`, read [`../sdk.md`](../sdk.md) instead.
+
+## Read order
+
+1. [`upload.md`](upload.md) — upload a packaged Playbook archive
+2. [`publish.md`](publish.md) — publish a validated Playbook
+3. [`run.md`](run.md) — trigger a manual backtest/evaluation run
+4. [`list.md`](list.md) and `detail` response docs — inspect public Playbooks
+5. [`enable.md`](enable.md) and [`my-playbooks.md`](my-playbooks.md) — manage
+   subscriptions
+6. [`error-responses.md`](error-responses.md) — common failure modes
+
+## Control-plane docs
+
+| Document | Purpose |
+|---|---|
+| [`upload.md`](upload.md) | Request format, package validation, and server-side checks |
+| [`publish.md`](publish.md) | Publish contract, evidence requirements, and 409 cases |
+| [`run.md`](run.md) | Manual run contract and runtime gating |
+| [`list.md`](list.md) | Public list surface |
+| [`enable.md`](enable.md) | Enable/disable subscription execution |
+| [`my-playbooks.md`](my-playbooks.md) | User subscription status |
+| [`error-responses.md`](error-responses.md) | Shared error shapes and examples |
+
+## Boundary
+
+- `api/` is for HTTP requests to GetAgent cloud services
+- `sdk/` is for Python code running inside the Playbook sandbox
+- Do not confuse `data.crypto.futures.kline(...)` with `/api/v1/playbook/...`

package/skills/getagent/references/api/list.md

@@ -0,0 +1,80 @@
+# List Playbooks
+
+List existing Playbooks for creator or consumer flows.
+
+## `GET /api/v1/playbook/list`
+
+**Auth**: Optional for the default published catalog, required for private states such as `draft`. Authenticated calls to the prod OpenAPI gateway use `ACCESS-KEY`.
+
+### Parameters
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | string | no | Filter by status. Default: `published`. Options: `draft`, `published`, `deprecated` |
+
+### Request Examples
+
+Endpoint is the fixed GetAgent prod OpenAPI URL. For authenticated calls, substitute `<access_key>` with the value the user provided in chat.
+
+```bash
+# List all published Playbooks (no auth)
+curl -s "https://api.bitget.com/api/v1/playbook/list"
+
+# List own drafts (auth required)
+curl -s \
+  -H "ACCESS-KEY: <access_key>" \
+  "https://api.bitget.com/api/v1/playbook/list?status=draft"
+```
+
+### Response Shape
+
+Published Playbooks should surface enough metadata for public `list / view`
+surfaces to distinguish what kind of evidence the user can trust.
+
+Recommended fields:
+
+- identity: `strategy_id`, `version_id`, `name`, `display_name`, `version`, `description`
+- public behavior: `decision_mode`, `backtest_support`, `execution_mode`
+- public evidence: `official_evidence_kind`, `official_metrics`
+- subscription hint: `follow_trade_supported`
+
+### Success Response
+
+```json
+[
+  {
+    "strategy_id": "strategy-...",
+    "version_id": "version-...",
+    "name": "btc-ema-crossover",
+    "display_name": "BTC EMA Crossover",
+    "version": "1.0.0",
+    "status": "published",
+    "description": "Trend following strategy based on EMA 12/26 crossover",
+    "trading_symbols": ["BTCUSDT"],
+    "tags": ["trend", "ema", "btc"],
+    "decision_mode": "deterministic",
+    "backtest_support": "full",
+    "execution_mode": "follow_trade",
+    "follow_trade_supported": true,
+    "official_evidence_kind": "backtest",
+    "official_metrics": {
+      "total_return_pct": 23.5,
+      "sharpe_ratio": 1.8,
+      "max_drawdown_pct": 8.4,
+      "win_rate": 0.62,
+      "total_trades": 41
+    }
+  }
+]
+```
+
+### Public Display Rules
+
+- `backtest_support: full`
+  - show official backtest summary in list / detail
+- `backtest_support: none`
+  - do not show fake Sharpe / win rate / total return
+  - show `official_evidence_kind` such as `paper` or `live`
+  - explain that the strategy is live-only because the core decision cannot be fairly replayed
+
+Returns max 100 results, ordered by creation time descending.

package/skills/getagent/references/api/my-playbooks.md

@@ -0,0 +1,41 @@
+# My Playbooks
+
+List the currently enabled Playbook deployments for the authenticated user.
+
+## `GET /api/v1/playbook/my-playbooks`
+
+**Auth**: `ACCESS-KEY` header from the Bitget OpenAPI credential. Missing it returns 401.
+
+### Success Response
+
+```json
+[
+  {
+    "instance_id": "e1f2g3-...",
+    "strategy_id": "strategy-...",
+    "version_id": "version-...",
+    "playbook_name": "btc-ema-crossover",
+    "display_name": "BTC EMA Crossover",
+    "version": "1.0.0",
+    "strategy_display_name": "BTC EMA Crossover",
+    "version_owner_id": "creator-principal-id",
+    "status": "active",
+    "execution_mode": "follow_trade",
+    "follow_trade_supported": true,
+    "channel": "telegram",
+    "chat_id": "123456789",
+    "reminder_id": "reminder-id"
+  }
+]
+```
+
+Returns the caller's active deployments. `strategy_id` is the stable strategy
+tree; `version_id` is the immutable published artifact that scheduled runs
+execute with the instance's `config_overrides`.
+
+The list should be enough for Telegram to explain what kind of behavior the
+user enabled:
+
+- signal-only
+- manual-confirm execution
+- future automation eligibility

package/skills/getagent/references/api/publish.md

@@ -0,0 +1,76 @@
+# Publish Playbook
+
+Publish a draft Playbook to make it publicly available. Publishing is the only
+step that assigns the formal public version number.
+
+## `POST /api/v1/playbook/publish`
+
+**Auth**: `ACCESS-KEY` header from the Bitget OpenAPI credential. Missing it returns 401.
+
+**Content-Type**: `application/json`
+
+### Request
+
+```json
+{
+  "draft_id": "draft-...",
+  "bump_type": "patch"
+}
+```
+
+`bump_type` is optional and defaults to `patch`. Valid values are `patch`,
+`minor`, and `major`. The server computes the final semver from the strategy's
+latest published version; clients must not edit `manifest.version` manually.
+
+### Success Response
+
+```json
+{
+  "strategy_id": "strategy-...",
+  "version_id": "version-...",
+  "version": "1.0.1",
+  "status": "published",
+  "published_at": "2026-04-09T12:00:00+00:00"
+}
+```
+
+### Permissions
+
+Only the Playbook owner can publish. Others receive 403.
+
+### Publish Contract
+
+Publishing freezes the draft artifact into an immutable version and records its
+parent version within the same strategy tree. A published Playbook should carry a
+stable public contract for:
+
+- `decision_mode`
+- `backtest_support`
+- `runtime_profile`
+- `execution_mode`
+- `follow_trade_supported`
+
+### Evidence Requirements
+
+- If `backtest_support = full`
+  - the current runtime must be able to execute it (`runtime_profile = deterministic`)
+  - the owner must first produce one successful historical evaluation run
+  - the Playbook should expose one official public backtest snapshot
+  - list / detail surfaces should use that snapshot, not an arbitrary recent run
+- If `backtest_support = none`
+  - `runtime_profile = deterministic` and `runtime_profile = llm_bounded` are both publishable
+  - `runtime_profile = llm_bounded` additionally requires deployment-side managed LLM runtime to be enabled
+  - do not publish fake Sharpe / win rate / total return claims
+  - use paper or live evidence instead
+
+Publishing a live-only Playbook is allowed. Publishing misleading historical
+performance is not.
+
+### Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 401 | Missing `ACCESS-KEY` header |
+| 403 | Not the Playbook owner, access key revoked, or principal not found / inactive |
+| 404 | draft_id not found |
+| 409 | Status is not draft; no successful historical evaluation exists for `backtest_support=full`; or runtime profile is not currently publishable |