@bitget-ai/getagent-skill 0.2.1

package/skills/getagent/references/sdk/trade/spot.md

@@ -0,0 +1,165 @@
+# Trade Spot Reference
+
+Spot query, place, cancel, and modify flows.
+
+These signatures are written against the `getagent.trade` public contract.
+Runner-managed identity kwargs (`user_id`, `channel`, `trace_id`) are
+intentionally omitted from the author-facing signatures below.
+
+## Contents
+- [`trade.spot.pending_orders`](#tradespotpending-orders)
+- [`trade.spot.fills`](#tradespotfills)
+- [`trade.spot.place_order`](#tradespotplace-order)
+- [`trade.spot.market_buy`](#tradespotmarket-buy)
+- [`trade.spot.market_sell`](#tradespotmarket-sell)
+- [`trade.spot.limit_order`](#tradespotlimit-order)
+- [`trade.spot.cancel_order`](#tradespotcancel-order)
+- [`trade.spot.modify_limit_order`](#tradespotmodify-limit-order)
+
+## Method reference
+
+### `trade.spot.pending_orders`
+
+```python
+trade.spot.pending_orders(symbol="", limit=None)
+```
+
+Summary: List live (unfilled) spot orders, optionally filtered by ``symbol``.
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `symbol` | `no` | `str` | `""` |
+| `limit` | `no` | `int | None` | `None` |
+
+Returns: `SpotPendingOrdersResult`
+
+---
+
+### `trade.spot.fills`
+
+```python
+trade.spot.fills(symbol="", order_id="", limit=None)
+```
+
+Summary: List recent spot trade fills, optionally scoped to one order.
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `symbol` | `no` | `str` | `""` |
+| `order_id` | `no` | `str` | `""` |
+| `limit` | `no` | `int | None` | `None` |
+
+Returns: `SpotFillsResult`
+
+---
+
+### `trade.spot.place_order`
+
+```python
+trade.spot.place_order(symbol, side, order_type, qty, price="", time_in_force='GTC')
+```
+
+Summary: Place a spot order with an explicit base-asset ``qty``.
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `symbol` | `yes` | `str` | - |
+| `side` | `yes` | `SideLiteral` | - |
+| `order_type` | `yes` | `OrderTypeLiteral` | - |
+| `qty` | `yes` | `Any` | - |
+| `price` | `no` | `Any` | `""` |
+| `time_in_force` | `no` | `TimeInForceLiteral` | `GTC` |
+
+Returns: `OrderPlacedResult`
+
+---
+
+### `trade.spot.market_buy`
+
+```python
+trade.spot.market_buy(symbol, qty)
+```
+
+Summary: Spot market buy with base-asset ``qty`` (shorthand for place_order).
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `symbol` | `yes` | `str` | - |
+| `qty` | `yes` | `Any` | - |
+
+Returns: `OrderPlacedResult`
+
+---
+
+### `trade.spot.market_sell`
+
+```python
+trade.spot.market_sell(symbol, qty)
+```
+
+Summary: Spot market sell with base-asset ``qty`` (shorthand for place_order).
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `symbol` | `yes` | `str` | - |
+| `qty` | `yes` | `Any` | - |
+
+Returns: `OrderPlacedResult`
+
+---
+
+### `trade.spot.limit_order`
+
+```python
+trade.spot.limit_order(symbol, side, qty, price, time_in_force='GTC')
+```
+
+Summary: Spot limit order (shorthand for place_order with order_type='limit').
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `symbol` | `yes` | `str` | - |
+| `side` | `yes` | `SideLiteral` | - |
+| `qty` | `yes` | `Any` | - |
+| `price` | `yes` | `Any` | - |
+| `time_in_force` | `no` | `TimeInForceLiteral` | `GTC` |
+
+Returns: `OrderPlacedResult`
+
+---
+
+### `trade.spot.cancel_order`
+
+```python
+trade.spot.cancel_order(symbol, order_id)
+```
+
+Summary: Cancel a live spot order by ``order_id``.
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `symbol` | `yes` | `str` | - |
+| `order_id` | `yes` | `str` | - |
+
+Returns: `OrderPlacedResult`
+
+---
+
+### `trade.spot.modify_limit_order`
+
+```python
+trade.spot.modify_limit_order(symbol, order_id, price, qty)
+```
+
+Summary: Modify a live spot limit order's ``price`` and ``qty`` atomically.
+
+| Param | Required | Type | Default |
+|---|---|---|---|
+| `symbol` | `yes` | `str` | - |
+| `order_id` | `yes` | `str` | - |
+| `price` | `yes` | `Any` | - |
+| `qty` | `yes` | `Any` | - |
+
+Returns: `OrderPlacedResult`
+
+---

package/skills/getagent/references/sdk.md

@@ -0,0 +1,198 @@
+# GetAgent SDK
+
+This is the stable authoring entrypoint for the Python SDK surface available to
+Playbook code. Use this file before writing `src/main.py`.
+
+This folder separates:
+
+- `sdk/` — Python modules imported by Playbook code
+- `api/` — HTTP control plane used to upload, publish, run, and manage Playbooks
+
+## Read order
+
+1. Start with `[package-schema.md](package-schema.md)` to understand the package
+  contract.
+2. Read the relevant SDK section below:
+  - market data → `[sdk/data/playbook-supported.md](sdk/data/playbook-supported.md)`
+    - replay / charting → `[sdk/backtest/catalog.md](sdk/backtest/catalog.md)`
+  - trading → `[sdk/trade/patterns.md](sdk/trade/patterns.md)`
+  - runtime protocol / signal output → `[sdk/runtime/catalog.md](sdk/runtime/catalog.md)`
+  - bounded LLM/live-only logic → `[sdk/llm/catalog.md](sdk/llm/catalog.md)`
+3. Read `[backtest-engine.md](backtest-engine.md)` for replay and metrics rules.
+4. Read `[sandbox-runtime.md](sandbox-runtime.md)` for execution limits and
+  blocked imports.
+
+## Quick start
+
+```python
+from getagent import backtest, data, runtime
+
+bars = data.crypto.futures.kline(symbol="BTCUSDT", interval="1h", exchange="binance")
+taker_volume = data.crypto.futures.taker_volume(symbol="BTCUSDT", period="1h")
+replay_frame = backtest.build_feature_frame(
+    bars,
+    base_datetime_index="date",
+    features=[
+        backtest.FeatureSource(
+            data=taker_volume,
+            datetime_index="timestamp",
+            include_columns=("buy_vol", "sell_vol"),
+            rename_columns={
+                "buy_vol": "taker_buy_volume",
+                "sell_vol": "taker_sell_volume",
+            },
+        )
+    ],
+)
+result = backtest.run(
+    ohlcv_data={"BTCUSDT.BINANCE": replay_frame},
+    spec=runtime.backtest_spec,
+)
+summary = result.summary
+# Author code emits raw account-level numbers; the platform rewrites
+# total_return_pct / max_drawdown_pct to per-strategy basis
+# (net_pnl / margin_budget) before persisting them.
+runtime.emit_signal(
+    action="long" if float(summary.get("net_pnl", 0) or 0) > 0 else "hold",
+    symbol="BTCUSDT",
+    confidence=result.win_rate,
+    metrics={
+        "total_return_pct": result.total_return_pct,
+        "net_pnl": float(summary.get("net_pnl", 0) or 0),
+        "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,
+    },
+)
+```
+
+## Modules
+
+Use this file and the linked catalogs as the SDK source of truth. Do not invent
+modules, namespaces, methods, endpoint ids, or keyword arguments by combining
+plausible names. If the needed capability is absent from the listed surfaces,
+report missing SDK coverage instead of importing a direct client or guessing a
+fallback.
+
+Authoritative public surfaces:
+
+- DataSDK: `getagent.data` generated endpoint methods listed under
+  `sdk/data/`
+- TradeSDK: `getagent.trade` namespaces and helpers listed under `sdk/trade/`
+- BacktestSDK: `getagent.backtest` helpers listed in `sdk/backtest/catalog.md`
+- RuntimeSDK: `getagent.runtime` context and signal helpers listed in
+  `sdk/runtime/catalog.md`
+- LLMSDK: `getagent.llm` bounded `chat` / `complete` surface listed in
+  `sdk/llm/catalog.md`
+
+### `getagent.data`
+
+The only supported market data module.
+
+Read order:
+
+1. `[sdk/data/playbook-supported.md](sdk/data/playbook-supported.md)` —
+  full Playbook-callable `getagent.data` endpoint surface
+2. `[sdk/data/catalog.md](sdk/data/catalog.md)` — full domain index
+3. domain files under `[sdk/data/](sdk/data/catalog.md)` — exact signatures,
+  defaults, enums, and parameter notes
+
+Hard rules:
+
+- Never import direct clients such as `ccxt`, `httpx`, `requests`,
+`yfinance`, or `akshare`
+- Convert `OBBject` responses with `data.to_dataframe()`, `data.to_dict()`, or
+`data.to_records()`
+- When several endpoints need to land in one replay frame, normalize them first
+and join them through `backtest.prepare_frame()` / `backtest.build_feature_frame()`
+- Treat all generated `getagent.data` endpoints as callable from Playbooks; for
+backtests, verify the response fields and time axis match the replay contract
+before declaring required fields in `backtest.yaml`
+
+### `getagent.trade`
+
+The managed trading surface. Playbook code must import `getagent.trade`, not
+`trade_sdk`.
+
+Read order:
+
+1. `[sdk/trade/patterns.md](sdk/trade/patterns.md)` — safe execution flows
+2. `[sdk/trade/catalog.md](sdk/trade/catalog.md)` — namespace index
+3. namespace files under `[sdk/trade/](sdk/trade/catalog.md)` — exact method
+  signatures and parameters
+
+Hard rules:
+
+- Never hardcode runner-managed identity such as `user_id`, `base_url`, or
+`channel`
+- Always size quote or margin budgets via `trade.helpers.compute_qty(...)`
+- For contract opens, derive TP/SL via `trade.helpers.resolve_contract_tpsl(...)`
+- Do not pass percentage override kwargs to `resolve_contract_tpsl(...)`; compute
+concrete `tp_trigger_price` / `sl_trigger_price` values first
+- For cancel / close / modify flows, follow `PRE-CHECK -> EXECUTE -> POST-CHECK`
+- Always check envelopes with `trade.is_success(result)`
+
+### `getagent.backtest`
+
+Backtest and charting helpers for replayable strategies.
+
+Read `[sdk/backtest/catalog.md](sdk/backtest/catalog.md)` for the concrete
+author-facing API surface, result shape, and basic examples.
+
+- `backtest.run(...)`
+- `backtest.prepare_frame(...)`
+- `backtest.FeatureSource(...)`
+- `backtest.build_feature_frame(...)`
+- `backtest.generate_chart(...)`
+
+Read `[backtest-engine.md](backtest-engine.md)` for Nautilus spec shape, replay
+assumptions, and diagnostics.
+
+Extra replay columns declared in `backtest.yaml` are preserved and can be read
+through strategy feature-frame injection. Use the feature-frame helpers above to
+align arbitrary `getagent.data` endpoints onto your base bar series before
+calling `backtest.run(...)`; see the backtest docs above.
+
+### `getagent.runtime`
+
+Managed runtime protocol for Playbooks.
+
+Read `[sdk/runtime/catalog.md](sdk/runtime/catalog.md)` for the concrete context
+surface, signal output contract, and examples.
+
+- context:
+  - `runtime.manifest`
+  - `runtime.backtest_spec`
+  - `runtime.run_id`
+- output:
+  - `runtime.emit_signal(...)`
+  - `runtime.get_emitted_signals()`
+
+Use `runtime` for runner-injected context and signal output. Do not expect a
+built-in planner, memory loop, or general agent runtime from this module.
+
+### `getagent.llm`
+
+Managed bounded model access for live-only Playbooks.
+
+Read `[sdk/llm/catalog.md](sdk/llm/catalog.md)` for the concrete call surface,
+runtime limits, typed errors, and examples.
+
+- Available only when `manifest.yaml` sets `runtime_profile: llm_bounded`
+- `llm.is_available()` reflects whether the runner injected bounded LLM access
+- `llm.complete(...)` and `llm.chat(...)` run against one runner-managed model
+- Call count, prompt size, output tokens, and timeout are all capped by the
+deployment runtime
+- Tool calls, free model switching, and arbitrary HTTP clients are not exposed
+
+Use `getagent.llm` only for unreplayable/live-only logic. Historical backtest
+still requires `runtime_profile: deterministic`.
+
+## See also
+
+- `[sandbox-runtime.md](sandbox-runtime.md)` — runtime contract
+- `[package-schema.md](package-schema.md)` — package structure and manifest
+- `[api/index.md](api/index.md)` — HTTP control plane, not Python imports