nexus-trading-labs: add autonomous agent control

nexus-trading-labs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nexus
-description: Non-custodial perpetual DEX on Arbitrum. Use when user says buy, sell, trade, long, short, open position, close position, flip trade, set leverage, deposit USDC, withdraw funds, check balance, view positions, cancel order, copy a thesis, publish trade on-chain, check leaderboard, top traders, Rep Score, market intel, crypto news, funding rate, thesis, analyst feed, who's winning on Nexus.
+description: Non-custodial perpetual DEX on Arbitrum with an autonomous trading agent. Use when user says buy, sell, trade, long, short, open position, close position, flip trade, set leverage, deposit USDC, withdraw funds, check balance, view positions, cancel order, copy a thesis, publish trade on-chain, check leaderboard, top traders, Rep Score, market intel, crypto news, funding rate, thesis, analyst feed, who's winning on Nexus, deploy an agent, run a trading bot, autonomous agent, paper trade, activate my agent, go live, autonomous mode, pause agent, kill agent, agent status, how's my agent, fund my agent, top agents.
 metadata:
   {
     "clawdbot":
@@ -40,6 +40,8 @@ Step 3 — sign_message({ message: "nexus-trading-key-v1" }) → save as walletS
 - NEVER ask the user to run terminal commands, install packages, or sign messages manually
 - NEVER use the Orderly CLI (`@orderly.network/cli`)
 - NEVER re-call `sign_message` before every request — one signature per session is enough
+- NEVER deploy an agent in a live mode (`AUTONOMOUS`) without an explicit user "go live" confirmation — it trades real funds
+- NEVER default an agent deploy to a live mode — default to `PAPER` (simulated) unless the user clearly asks to go live
 
 ---
 
@@ -63,6 +65,56 @@ To attach SL/TP after fill: `POST /set-sl-tp` (see references/trading.md — nev
 
 ---
 
+## Autonomous Agent
+
+Deploy a bot that trades a funding + OI-divergence confluence signal 24/7 within the
+user's risk limits. The key is **order-only — it can trade but NEVER withdraw.**
+Default to **PAPER** (simulated, zero risk). Going **AUTONOMOUS** (live) ALWAYS needs
+explicit user confirmation.
+
+```
+POST https://og.nexustradinglabs.com/agent/<walletAddress>/bankr/activate
+{
+  "mode": "PAPER",                 // PAPER | ASSISTED | AUTONOMOUS  (default PAPER)
+  "config": {
+    "signalMode": "CONFLUENCE",    // CONFLUENCE(default) | FUNDING_ONLY | OI_ONLY | MOMENTUM* | MEAN_REVERSION*  (*=PRO)
+    "symbols": ["PERP_BTC_USDC"],
+    "capitalPerTrade": 30, "leverage": 5,
+    "tpPercent": 1.5, "slPercent": 0.75, "maxHoldHours": 4,
+    "maxTradesPerDay": 10, "maxDailyLossUsdc": 5,
+    "fundingThreshold": 0.01,      // % — signal sensitivity
+    "oiChangeThreshold": 0,        // % min OI move to count
+    "priceChangeThreshold": 0.5    // % move for MOMENTUM / MEAN_REVERSION
+  },
+  "walletSig": "<required for ASSISTED/AUTONOMOUS>",
+  "confirm": "GO LIVE"             // REQUIRED only when mode is AUTONOMOUS
+}
+```
+
+- **PAPER** needs no walletSig (simulated). **ASSISTED / AUTONOMOUS** derive the
+  order-only key from `walletSig` — pass the session signature.
+- **Strategy:** the user picks `signalMode`. `MOMENTUM` / `MEAN_REVERSION` require
+  **Nexus PRO** — if the user isn't PRO, say so and default to `CONFLUENCE`. The free
+  strategies are `CONFLUENCE`, `FUNDING_ONLY`, `OI_ONLY`. All thresholds are user-tunable.
+- AUTONOMOUS without `confirm:"GO LIVE"` → `409 confirm_required`. Confirm with the
+  user FIRST, then resend with `confirm:"GO LIVE"`.
+- Change mode later: `POST /agent/<wallet>/bankr/mode { "mode", "walletSig", "confirm"? }`
+- Pause new entries: mode → `ASSISTED` (still manages an open position). Back to sim: mode → `PAPER`.
+- Status: `GET /agent/<wallet>` (public read). Stop: `DELETE /agent/<wallet>` (⚠️ leaves an open position
+  unmanaged — offer KILL instead if a position is open). Kill (close + stop): `POST /agent/<wallet>/kill`.
+- **⚠️ AUTH — every agent MUTATION requires `walletSig`** (`sign_message('nexus-trading-key-v1')`): activate
+  (ALL modes, incl. PAPER), mode change, config update, deactivate, and kill. These are account-control
+  actions — the server ecrecovers the sig and rejects (`401 walletSig_required`) unless it resolves to the
+  agent's own wallet. Pass `walletSig` in the JSON body (NEVER a query string). Only `GET /agent/<wallet>` is
+  public. Reuse the session signature you already hold — no need to re-sign per call.
+- **Capital guardrail:** keep `capitalPerTrade` ≤ ~60% of free collateral, or live entries
+  margin-reject (Orderly -1101). Read balance first and suggest a safe size.
+- Always tell the user: the agent's key is **order-only — it cannot withdraw funds.**
+
+See references/agent.md for the full intent map, status formatting, and safety rules.
+
+---
+
 ## Quick Reference
 
 ⚠️ **ALWAYS use the full URL: `https://og.nexustradinglabs.com`**
@@ -83,6 +135,14 @@ To attach SL/TP after fill: `POST /set-sl-tp` (see references/trading.md — nev
 | Settle PnL | `POST https://og.nexustradinglabs.com/settle-pnl` | walletSig |
 | Register wallet | `POST https://og.nexustradinglabs.com/proxy/bankr-register` | Bankr API key |
 | Publish thesis on-chain | `POST https://og.nexustradinglabs.com/proxy/thesis-register` | Bankr API key |
+| **Deploy / arm agent** | `POST https://og.nexustradinglabs.com/agent/:wallet/bankr/activate` | walletSig (all modes) |
+| **Change agent mode** | `POST https://og.nexustradinglabs.com/agent/:wallet/bankr/mode` | walletSig |
+| **Update agent config** | `PUT https://og.nexustradinglabs.com/agent/:wallet/config` | walletSig |
+| **Agent status** | `GET https://og.nexustradinglabs.com/agent/:wallet` | public read |
+| **Deactivate agent** | `DELETE https://og.nexustradinglabs.com/agent/:wallet` | walletSig (in body) |
+| **Kill agent (close + stop)** | `POST https://og.nexustradinglabs.com/agent/:wallet/kill` | walletSig (in body) |
+| **Top agents** | `GET https://og.nexustradinglabs.com/agents/leaderboard` | public |
+| **Agent ledger (proof)** | `GET https://og.nexustradinglabs.com/agents/ledger` | public |
 | Mark price | `GET https://og.nexustradinglabs.com/mark-price?symbol=BTC` | public |
 | Funding rate | `GET https://og.nexustradinglabs.com/funding-rate?symbol=BTC` | public |
 | 24h stats | `GET https://og.nexustradinglabs.com/24h-stats?symbol=BTC` | public |
@@ -99,6 +159,7 @@ To attach SL/TP after fill: `POST /set-sl-tp` (see references/trading.md — nev
 
 - **references/trading.md** — full trade flow, registration, SL/TP, close, cancel, order-status, order-history, positions, leverage
 - **references/deposit-withdraw.md** — deposit USDC, withdraw, settle PnL, balance
+- **references/agent.md** — deploy/arm/fund/kill the autonomous agent, mode flips (PAPER/ASSISTED/AUTONOMOUS), status formatting, safety gates
 - **references/feed-leaderboard.md** — public feed, thesis copy flow, on-chain registry, Rep Score, leaderboard build, notifications, comments
 - **references/market-data.md** — mark price, funding rate, 24h stats, error codes, retry logic, rate limits, testnet
 - **references/intel.md** — market intelligence: pull live OI, funding rates, regime signals from Orderly public API

nexus-trading-labs/references/agent.md

@@ -0,0 +1,140 @@
+# Bankr Skill — Agent Module (drop-in)
+
+> Add this to the Nexus Bankr skill. It lets a user deploy, fund, control, and kill
+> a non-custodial autonomous trading agent by chat. LIVE on `https://og.nexustradinglabs.com`.
+> All endpoints shipped + smoke-tested (2026-06-02). Companion to `bankr-agent-spec.md`.
+
+## What it is (tell the user)
+"Nexus can run an autonomous trading bot on your account. It hunts funding-rate +
+open-interest edges 24/7 inside hard limits you set. It uses an **order-only key —
+it can trade but never withdraw your funds.** Starts in risk-free PAPER mode; you
+flip it live when you trust it."
+
+## Auth model
+- **Every mutation requires `walletSig`** from `sign_message('nexus-trading-key-v1')` — including PAPER.
+  Agent control (activate, mode, config, deactivate, kill) changes account state, so the server ecrecovers
+  the signature and requires it to resolve to the agent's own wallet; otherwise `401 walletSig_required`.
+  Pass it in the JSON body, never a query string. Only `GET /agent/{addr}` is public (read-only).
+- **ASSISTED / AUTONOMOUS** (live) use that same `walletSig` to ALSO derive the order-only key. The wallet
+  must already be registered (`/proxy/bankr-register`); if not, register first then retry.
+- **AUTONOMOUS** also needs `confirm: "GO LIVE"` — ALWAYS get an explicit yes from the user before sending it.
+- The signature is deterministic; reuse the session sig you already hold rather than re-prompting per call.
+
+## Config — the full control surface (all of this is user-set)
+
+Pass any of these in the `config` object on `activate`; omitted fields use the
+default. Everything is tunable later via the same call or `/bankr/mode`.
+
+**Strategy — `signalMode`** (how funding + OI combine):
+| Mode | Behavior | Tier |
+|---|---|---|
+| `CONFLUENCE` *(default)* | funding extreme **AND** OI-divergence must agree — strictest, best trades | free |
+| `FUNDING_ONLY` | fade funding extremes only | free |
+| `OI_ONLY` | OI-divergence only | free |
+| `MOMENTUM` | trade **with** a price move > threshold (trend-follow) | **PRO** |
+| `MEAN_REVERSION` | **fade** a price move > threshold (buy dip / sell rip) | **PRO** |
+
+> `MOMENTUM` / `MEAN_REVERSION` require **Nexus PRO**. If the user isn't PRO, tell
+> them those are PRO strategies and default to `CONFLUENCE`. Don't push a PRO mode
+> as if it's free.
+
+**Signal sensitivity:** `fundingThreshold` (%, default 0.01), `oiChangeThreshold`
+(% min OI move to count, default 0), `priceChangeThreshold` (% move for
+MOMENTUM/MEAN_REVERSION, default 0.5).
+
+**Market regime filter — `respectRegime`** (boolean, default `false`, opt-in): when
+`true`, the agent skips NEW entries that fight a strong market tape — it won't go
+**LONG in a broad RISK-OFF** regime or **SHORT in a broad RISK-ON** regime. It never
+flips direction or touches an open position; it only suppresses a fresh entry. Good
+for users who don't want to fade a strong trend. Set via config, e.g.
+`{respectRegime:true}`. Suggest testing in PAPER first.
+> Example: "only trade with the market, skip counter-trend entries" → `{respectRegime:true}`.
+
+**Risk & execution:** `symbols` (watchlist, e.g. `["PERP_BTC_USDC","PERP_ETH_USDC"]`),
+`leverage`, `capitalPerTrade` (margin per trade), `tpPercent`, `slPercent`,
+`maxHoldHours`, `maxTradesPerDay`, `maxDailyLossUsdc`.
+
+**Example prompts → config:**
+- "run my agent in mean-reversion mode on ETH, $40/trade at 3x" →
+  `{signalMode:"MEAN_REVERSION", symbols:["PERP_ETH_USDC"], capitalPerTrade:40, leverage:3}` *(PRO)*
+- "deploy paper, confluence, BTC + SOL, tighter funding threshold 0.02%" →
+  `{signalMode:"CONFLUENCE", symbols:["PERP_BTC_USDC","PERP_SOL_USDC"], fundingThreshold:0.02}`
+- "make it funding-only and cap me at 5 trades a day" →
+  `{signalMode:"FUNDING_ONLY", maxTradesPerDay:5}`
+- "switch my agent to momentum" → PRO check first, else CONFLUENCE.
+- "only trade with the regime" → `{respectRegime:true}`.
+
+## Strategy presets (one-line deploys)
+
+Curated configs the user can name directly. Apply the preset's `config` on
+`activate`/`mode`, keeping the user's chosen mode (default PAPER — presets do NOT set
+mode). PRO presets need Nexus PRO (PRO-check first; else suggest a free preset).
+Scale `capitalPerTrade` down if free collateral is low (capital guardrail below).
+
+| Preset | `config` | Tier |
+|---|---|---|
+| **Funding Harvester** *(conservative)* | `{signalMode:"CONFLUENCE", symbols:["PERP_BTC_USDC"], leverage:3, capitalPerTrade:30, tpPercent:1.2, slPercent:0.6, maxHoldHours:6, maxTradesPerDay:6, maxDailyLossUsdc:10, fundingThreshold:0.015}` | free |
+| **Blue-Chip Confluence** *(balanced)* | `{signalMode:"CONFLUENCE", symbols:["PERP_BTC_USDC","PERP_ETH_USDC"], leverage:5, capitalPerTrade:40, tpPercent:1.5, slPercent:0.75, maxHoldHours:4, maxTradesPerDay:8, maxDailyLossUsdc:12}` | free |
+| **OI Divergence Hunter** *(balanced)* | `{signalMode:"OI_ONLY", symbols:["PERP_BTC_USDC","PERP_ETH_USDC"], leverage:5, capitalPerTrade:40, tpPercent:1.5, slPercent:0.8, maxHoldHours:4, maxTradesPerDay:8, maxDailyLossUsdc:12, oiChangeThreshold:0.5}` | free |
+| **Funding Scalper** *(aggressive)* | `{signalMode:"FUNDING_ONLY", symbols:["PERP_BTC_USDC","PERP_ETH_USDC","PERP_SOL_USDC"], leverage:8, capitalPerTrade:30, tpPercent:0.8, slPercent:0.5, maxHoldHours:2, maxTradesPerDay:14, maxDailyLossUsdc:12, fundingThreshold:0.008}` | free |
+| **Momentum Rider** *(PRO · trend)* | `{signalMode:"MOMENTUM", symbols:["PERP_BTC_USDC","PERP_ETH_USDC","PERP_SOL_USDC"], leverage:8, capitalPerTrade:40, tpPercent:2, slPercent:1, maxHoldHours:4, maxTradesPerDay:10, maxDailyLossUsdc:15, priceChangeThreshold:0.6}` | **PRO** |
+| **Mean Reversion Fade** *(PRO · fade)* | `{signalMode:"MEAN_REVERSION", symbols:["PERP_BTC_USDC","PERP_ETH_USDC"], leverage:6, capitalPerTrade:30, tpPercent:1.5, slPercent:1, maxHoldHours:3, maxTradesPerDay:10, maxDailyLossUsdc:12, priceChangeThreshold:0.7}` | **PRO** |
+
+> "deploy the Funding Scalper preset in paper" → `activate {mode:"PAPER", config:{…Funding Scalper…}}`.
+> "load Mean Reversion Fade and go live" → PRO-check → confirm GO LIVE → `mode {mode:"AUTONOMOUS", confirm:"GO LIVE", walletSig, …}` after applying the preset config. Combine a preset with `respectRegime:true` for a trend-aware version.
+
+## Intents → calls
+
+**⚠️ AUTH: every agent MUTATION below requires `walletSig` = `sign_message('nexus-trading-key-v1')` in the
+JSON body** — including PAPER activate/mode and config changes. The server ecrecovers it and rejects
+(`401 walletSig_required`) unless it resolves to the agent's own wallet. NEVER pass it in a query string. Only
+`GET /agent/{addr}` is public. Reuse the session signature you already hold.
+
+| User says | Call |
+|---|---|
+| "Deploy my agent (paper) on BTC, $30/trade 5x" | `POST /agent/{addr}/bankr/activate` `{mode:"PAPER", config:{symbols:["PERP_BTC_USDC"],capitalPerTrade:30,leverage:5}, walletSig}` |
+| "Arm it in assisted mode" | `POST /agent/{addr}/bankr/activate` `{mode:"ASSISTED", walletSig}` |
+| "Make it live / go autonomous" | confirm first → `POST /agent/{addr}/bankr/mode` `{mode:"AUTONOMOUS", confirm:"GO LIVE", walletSig}` |
+| "Pause my agent" | `POST /agent/{addr}/bankr/mode` `{mode:"ASSISTED", walletSig}` |
+| "Set it back to paper" | `POST /agent/{addr}/bankr/mode` `{mode:"PAPER", walletSig}` |
+| "Change to $20/trade at 3x" | `POST /agent/{addr}/bankr/activate` `{mode:<current>, config:{capitalPerTrade:20,leverage:3}, walletSig}` |
+| "Deploy the Blue-Chip Confluence preset (paper)" | `POST /agent/{addr}/bankr/activate` `{mode:"PAPER", config:{…preset…}, walletSig}` (see Strategy presets) |
+| "Turn on the market regime filter" | `POST /agent/{addr}/bankr/activate` `{mode:<current>, config:{respectRegime:true}, walletSig}` |
+| "How's my agent?" | `GET /agent/{addr}` → format `state` (public read, no sig) |
+| "Fund my agent $50" | `POST /deposit/prepare` `{wallet, amount:50, accountId}` → sign+submit, then suggest capital (below) |
+| "Stop my agent" | `DELETE /agent/{addr}` `{walletSig}` (⚠️ warn: leaves an open position unmanaged — offer KILL) |
+| "Kill it / close everything" | `POST /agent/{addr}/kill` `{walletSig}` |
+| "Top Nexus agents" | `GET /agents/leaderboard` |
+| "Is the record real?" | `GET /agents/ledger` (SHA-256 root + on-chain anchor) |
+
+## Capital guardrail (avoid Orderly −1101 "margin insufficient")
+`capitalPerTrade` is the margin per trade. Keep a buffer below free collateral:
+```
+suggestedCapital = floor(freeCollateral * 0.6)
+```
+Read balance via `POST /balance` `{walletAddress, walletSig}` (never put the signature in a query string — it's
+a replayable credential that can leak into logs/proxies). Never set `capitalPerTrade` above
+~60% of free collateral, or live entries will margin-reject. State it:
+"With $52 free, I'd run ~$30/trade so margin keeps a buffer."
+
+## Status formatter (from `GET /agent/{addr}` → `state`)
+```
+🟢 {mode} · {active ? "ON" : "OFF"}
+{current_position ? "in {dir} {symbol} @ {entry}, {pnl_percent}%" : "flat — waiting on a confluence signal"}
+{trades_today}/{maxTradesPerDay} trades today · daily P&L {daily_pnl}
+```
+
+## Response copy
+- **Activated (paper):** "✅ Agent deployed in PAPER on {symbols} — ${cap}/trade, {lev}x,
+  TP +{tp}% / SL −{sl}%. Simulated, zero risk. Say 'go live' when you're convinced."
+- **Before live:** "⚠️ This trades real funds within your limits. The key is order-only —
+  it can never withdraw. Reply GO LIVE to confirm." → then send `confirm:"GO LIVE"`.
+- **Killed:** "🛑 Agent killed — position closed, key removed, deactivated. Re-deploy anytime."
+
+## Safety rules (non-negotiable)
+1. Never send `mode:"AUTONOMOUS"` without an explicit user "go live".
+2. Default every deploy to PAPER unless the user clearly asks for live.
+3. KILL always works and needs no confirmation — it's the safety verb.
+4. If `DELETE` (stop) is requested while a position is open, warn it leaves the
+   position unmanaged and offer KILL instead.
+5. Always remind: the agent's key is **order-only — it cannot withdraw funds.**

nexus-trading-labs/references/deposit-withdraw.md

@@ -4,6 +4,16 @@
 
 All collateral lives in the Orderly Network vault on Arbitrum — non-custodial, withdraw anytime.
 
+**⚠️ State the destination clearly when depositing.** A deposit goes into the user's **Nexus
+trading balance** (perpetual collateral — spendable immediately, withdrawable on demand, NO lockup).
+This is NOT a yield or managed vault. Always confirm it back, e.g.:
+
+> "Depositing 14.58 USDC into your **Nexus trading balance** (perp collateral on Arbitrum —
+> withdraw anytime, no lockup). This is not a yield/managed vault."
+
+This preempts confusion with OmniVault (a separate managed-fund product with a redemption window —
+see the OmniVault section below). The skill can ONLY deposit to the trading balance.
+
 ### Automated path (recommended)
 
 ```
@@ -112,7 +122,16 @@ Returns `{ ok: true, hint: "Wait ~5s then retry withdrawal with free_collateral
 
 ---
 
-## OmniVault
+## OmniVault — different product, NOT reachable via the skill
+
+OmniVault is Orderly's **managed-fund** product, distinct from the trading balance:
+
+- **Trading balance** (what this skill deposits to): perp collateral, withdraw on demand, no lockup.
+- **OmniVault**: a managed fund with a **redemption/withdrawal window** (funds are not instantly
+  liquid — the manager unwinds positions first).
 
-Not currently supported via the skill. Direct users to https://app.orderly.network/vaults to deposit directly.
+External brokers cannot deposit into OmniVault, so the skill **cannot** route funds there — every
+skill deposit goes to the trading balance. If a user specifically wants OmniVault or a community
+vault, direct them to the web app: https://app.orderly.network/vaults (or the Vaults page at
+https://trade.nexustradinglabs.com). Do NOT imply the skill can manage vault deposits/redemptions.