USD price feed. Pulse and guard rail trading strategies

.github/workflows/publish-pypi.yml

@@ -34,15 +34,15 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v8.1.0
       with:
         enable-cache: true
         cache-dependency-glob: "**/uv.lock"
@@ -67,15 +67,15 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.12'
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v8.1.0
       with:
         enable-cache: true
         cache-dependency-glob: "**/uv.lock"
@@ -117,7 +117,7 @@ jobs:
         test -f dist/*.tar.gz
 
     - name: Upload artifacts
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: python-package-distributions
         path: dist/
@@ -140,7 +140,7 @@ jobs:
 
     steps:
     - name: Download artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v8
       with:
         name: python-package-distributions
         path: dist/
@@ -173,7 +173,7 @@ jobs:
 
     steps:
     - name: Download artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v8
       with:
         name: python-package-distributions
         path: dist/

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+# Install: uv sync && uv run pre-commit install
+# Run all hooks: uv run pre-commit run --all-files
+
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check-fix
+        name: ruff check (fix, src/bds_agent)
+        entry: uv run ruff check --fix --unsafe-fixes src/bds_agent/
+        language: system
+        pass_filenames: false
+        files: ^src/bds_agent/

PYPI_README.md

@@ -11,6 +11,9 @@ Python package and CLI for building agents on **[Powerloom BDS](https://powerloo
 - **MCP server** — stdio-based MCP exposing BDS catalog as tools for Claude, Cursor, LangGraph, CrewAI, etc.
 - **LLM backends** — Anthropic, OpenAI-compatible, Ollama (local)
 - **On-chain verification** — optional CID verification against `ProtocolState.maxSnapshotsCid`
+- **Pulse trader** — BDS stream → Pulse signals → Uniswap V3 swaps (`bds-agent trade`; separate `.trade.env` wallet)
+- **Threshold Guard** — bracket take-profit / stop-loss on BDS USD prices (`bds-agent guard`; `--enter` swaps USDC → base; same `.trade.env`)
+- **USD prices** — `bds-agent prices at` / `prices token` against `/mpp/token/price/` and `/mpp/tokenPrices/all/`
 
 ## Installation
 
@@ -45,6 +48,14 @@ bds-agent create "alert me on Slack when any ETH/USDC swap exceeds $50k"
 
 # Start the MCP server (stdio) for AI framework integration
 bds-agent mcp
+
+# Threshold Guard: spot %% TP/SL, dip re-entry, optional idle exit (ETH mainnet example)
+bds-agent trade setup-evm --profile myguard
+bds-agent guard run --profile myguard \
+  --pool 0xE0554a476A092703abdB3Ef35c80e0D76d32939F \
+  --token 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
+  --size 5 --take-profit-pct 0.003 --stop-loss-pct 0.002 \
+  --reserve-max-minutes 30 --poll 5
 ```
 
 ## Available Commands
@@ -55,6 +66,12 @@ bds-agent mcp
 | `bds-agent signup-pay` | Wallet-funded API key (no browser) |
 | `bds-agent credits balance` | Credit balance and rate limits |
 | `bds-agent credits topup` | Top up credits via billing link or on-chain |
+| `bds-agent credits setup-evm` | Billing wallet → `profiles/<n>.evm.env` |
+| `bds-agent trade setup-evm` | Swap wallet → `profiles/<n>.trade.env` |
+| `bds-agent trade run` | Pulse trader (see `docs/TRADE.md`) |
+| `bds-agent prices at` / `prices token` | USD price feed (pool-scoped or all pools) |
+| `bds-agent guard run` | Threshold Guard bracket trading (see `docs/GUARD.md`) |
+| `bds-agent guard enter` / `guard status` / `guard reset` | USDC → base entry, guard state, or cycle reset |
 | `bds-agent run <agent.yaml>` | SSE stream → rules → sinks |
 | `bds-agent query "…"` | NL → endpoint + params (LLM) |
 | `bds-agent create "…"` | NL → `agent.yaml` (LLM + validation) |
@@ -66,9 +83,16 @@ bds-agent mcp
 
 - Python 3.12 or higher
 
+## Orchestrators
+
+Framework-neutral command index, env vars, failure modes (402, stream auth): **[SKILL.md](https://github.com/powerloom/bds-agent-py/blob/main/SKILL.md)** in the repo root.
+
 ## Documentation
 
 - [User Guide](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md)
+- [Pulse trader (`trade`)](https://github.com/powerloom/bds-agent-py/blob/main/docs/TRADE.md)
+- [Threshold Guard (`guard`)](https://github.com/powerloom/bds-agent-py/blob/main/docs/GUARD.md)
+- [USD prices (`prices`)](https://github.com/powerloom/bds-agent-py/blob/main/docs/PRICES.md)
 - [Agent YAML Schema](https://github.com/powerloom/bds-agent-py/blob/main/docs/AGENT_YAML.md)
 - [Rules Reference](https://github.com/powerloom/bds-agent-py/blob/main/docs/RULES.md)
 - [Sinks Reference](https://github.com/powerloom/bds-agent-py/blob/main/docs/SINKS.md)

README.md

@@ -14,6 +14,12 @@ Python package and CLI for building agents on **Powerloom BDS** data markets.
 
 **→ [docs/AGENT_YAML.md](docs/AGENT_YAML.md)** — `agent.yaml` schema, **`${VAR}`** interpolation, **`auth`**, optional **`verify`** (on-chain CID vs `maxSnapshotsCid`). Example: **`examples/agent.example.yaml`**.
 
+**→ [docs/TRADE.md](docs/TRADE.md)** — Pulse trader (`bds-agent trade`).
+
+**→ [docs/GUARD.md](docs/GUARD.md)** — Threshold Guard (`bds-agent guard`: spot %% TP/SL, dip re-entry, `--reserve-max-minutes`, trade log sync).
+
+**→ [docs/PRICES.md](docs/PRICES.md)** — USD Price Feed CLI (`bds-agent prices`).
+
 ## Install
 
 Install **[uv](https://docs.astral.sh/uv/)** once (standalone installer or your package manager).
@@ -47,12 +53,15 @@ When the package is published to PyPI, **`uv tool upgrade bds-agent`** upgrades
 ```bash
 cd bds-agent-py
 uv sync
+uv run pre-commit install   # optional: ruff --fix on commit (src/bds_agent/)
 uv run bds-agent --help
 uv run bds-agent --version
 ```
 
 Use **`uv run bds-agent …`** for every CLI invocation, or install with **`uv tool install .`** when you want a stable **`bds-agent`** on **`PATH`**.
 
+Pre-commit runs **`uv run ruff check --fix --unsafe-fixes src/bds_agent/`** when you change files under **`src/bds_agent/`**. Manual check: same command, or **`uv run pre-commit run --all-files`**.
+
 CLI: **[Typer](https://typer.tiangolo.com/)** + **httpx**.
 
 Environment (many are optional depending on the command):
@@ -70,7 +79,7 @@ Environment (many are optional depending on the command):
 
 Full tables and precedence: **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)** → **API endpoint catalog** and **LLM backends**.
 
-Credentials: **`~/.config/bds-agent/profiles/<profile>.json`** (plus **`active_profile`** after signup). Tempo wallet for **`credits topup`**: **`profiles/<profile>.tempo.env`**. Generic EVM key for **`signup-pay`**: **`profiles/<profile>.evm.env`**. Override with **`--profile`** / **`BDS_AGENT_PROFILE`**.
+Credentials: **`~/.config/bds-agent/profiles/<profile>.json`** (plus **`active_profile`** after signup). Tempo wallet for **`credits topup`**: **`profiles/<profile>.tempo.env`**. Billing EVM for **`signup-pay`**: **`profiles/<profile>.evm.env`**. Trading EVM for **`trade run`**: **`profiles/<profile>.trade.env`**. Override with **`--profile`** / **`BDS_AGENT_PROFILE`**.
 
 If you still have a single **`~/.config/bds-agent/tempo.env`**, move it to **`profiles/<your-profile>.tempo.env`** (or re-run **`credits setup-tempo`**). With no profile selected, the CLI may still read the legacy file as a fallback.
 
@@ -81,9 +90,17 @@ If you still have a single **`~/.config/bds-agent/tempo.env`**, move it to **`pr
 | `bds-agent signup` | Device-auth flow; saves API key locally |
 | `bds-agent signup-pay` | Wallet-funded API key (no browser); see **`docs/USER_GUIDE.md`** |
 | `bds-agent credits balance` | Credit balance and rate limits |
+| `bds-agent credits usage` | Recent credit ledger rows (`route_template`, `http_method`, `request_path`, `client_source`) |
+| `bds-agent credits usage summary` | Daily totals and per-endpoint usage (`--days`) |
+| `bds-agent credits usage by-endpoint` | Endpoint-only rollup (`--days`, `--limit`) |
 | `bds-agent credits setup-evm` | Save generic EVM key for pay-signup / on-chain (non-Tempo) |
 | `bds-agent credits topup` | Billing link when checkout exists; dev `--amount` + `--dev-secret` on staging |
 | `bds-agent run <agent.yaml>` | SSE stream → rules → sinks (see `docs/AGENT_YAML.md`) |
+| `bds-agent trade setup-evm` | Save trading wallet to `profiles/<n>.trade.env` (swaps only) |
+| `bds-agent trade run` | Pulse trader: BDS stream → Uniswap V3 multi-pool (USD price gate); see `docs/TRADE.md` |
+| `bds-agent prices at` / `prices token` | USD spot per pool or all pools (`/mpp/token/price/`, `/mpp/tokenPrices/all/`) |
+| `bds-agent guard run` | Threshold Guard: spot %% bands or explicit USD thresholds; see `docs/GUARD.md` |
+| `bds-agent guard enter` / `guard status` / `guard reset` | One-shot USDC → base; `.guard.json` + `guard_exit_reason`; reset cycle for next leg |
 | `bds-agent query "…"` | NL → endpoint + params (LLM); optional **`--execute`** to call BDS — see **`docs/USER_GUIDE.md`** |
 | `bds-agent create "…"` | NL → **`agent.yaml`** (LLM + validation); **`--output`** / **`-o`** optional — see **`docs/USER_GUIDE.md`** |
 | `bds-agent llm status` / `setup` / `ping` | Configure and test LLM backends (`~/.config/bds-agent/llm.json`) |