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,51 @@ 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>`. Stop: `DELETE /agent/<wallet>` (⚠️ leaves an open position
+  unmanaged — offer KILL instead if a position is open). Kill (close + stop): `POST /agent/<wallet>/kill`.
+- **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 +130,13 @@ 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 (live modes) |
+| **Change agent mode** | `POST https://og.nexustradinglabs.com/agent/:wallet/bankr/mode` | walletSig (live flip) |
+| **Agent status** | `GET https://og.nexustradinglabs.com/agent/:wallet` | public read |
+| **Deactivate agent** | `DELETE https://og.nexustradinglabs.com/agent/:wallet` | — |
+| **Kill agent (close + stop)** | `POST https://og.nexustradinglabs.com/agent/:wallet/kill` | — |
+| **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 +153,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,133 @@
+# 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
+- **PAPER** activation needs nothing but the wallet address — it's simulated, no key.
+- **ASSISTED / AUTONOMOUS** (live) need `walletSig` from
+  `sign_message('nexus-trading-key-v1')` (the existing skill step) — that signature
+  IS the auth and derives 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.
+
+## 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
+
+| 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}}` |
+| "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"}` |
+| "Set it back to paper" | `POST /agent/{addr}/bankr/mode` `{mode:"PAPER"}` |
+| "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…}}` (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` |
+| "Fund my agent $50" | `POST /deposit/prepare` `{wallet, amount:50, accountId}` → sign+submit, then suggest capital (below) |
+| "Stop my agent" | `DELETE /agent/{addr}` (⚠️ warn: leaves an open position unmanaged — offer KILL) |
+| "Kill it / close everything" | `POST /agent/{addr}/kill` |
+| "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 `GET /balance?wallet=&sig=`. 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.**