my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Clawd Agents Perps
#2
#3	The perp nerve center for Clawd agents — and now the home of Clawd Perps Core OI Signal.
#4
#5	This workspace is where the repo stops sounding like infrastructure and starts reading like an active trading machine: Phoenix prices through Rise, OI signal regimes scored in real time, Vulcan command surfaces mapped into agent-safe plans, and operator-facing payloads that tell you what is armed, what is blocked, and what still needs human approval.
#6
#7	It does not replace the upstream repos under `Perps/`. It metabolizes them.
#8
#9	---
#10
#11	## Clawd Perps Core OI Signal
#12
#13	OI alone is not the signal. The real signal is:
#14
#15	```text
#16	OI delta
#17	+ mark price delta
#18	+ funding pressure
#19	+ long/short skew
#20	+ orderbook liquidity
#21	+ spread widening
#22	+ mark/index basis
#23	+ account/risk health
#24	= Clawd Core OI Signal
#25	```
#26
#27	### Signal Regimes
#28
#29	\| Regime \| Condition \|
#30	\| --- \| --- \|
#31	\| `LONG_CONTINUATION` \| price ↑ + OI ↑ + funding sane + spread tight \|
#32	\| `SHORT_CONTINUATION` \| price ↓ + OI ↑ + funding sane + spread tight \|
#33	\| `SHORTS_CLOSING` \| price ↑ + OI ↓ (do not chase) \|
#34	\| `LONGS_CLOSING` \| price ↓ + OI ↓ (wait) \|
#35	\| `CROWDED_LONG_RISK` \| OI ↑ hard + funding very positive + skew long + thinning bids \|
#36	\| `CROWDED_SHORT_RISK` \| OI ↑ hard + funding very negative + skew short + thinning asks \|
#37	\| `NEUTRAL` \| no directional signal \|
#38	\| `DATA_INVALID` \| any gate failed \|
#39
#40	### Execution Gates
#41
#42	The signal will not pass `executable: true` if any of these fail:
#43
#44	```text
#45	OI missing
#46	data stale (> 15s)
#47	spread too wide (default > 25 bps)
#48	depth too thin (default < $25,000)
#49	funding overheated (default > 0.25%)
#50	mark/index basis extreme (default > 150 bps)
#51	```
#52
#53	### Quick Demo
#54
#55	```bash
#56	# One-shot OI signal (mock — no RPC needed)
#57	node perps/clawd-agents-perps/dist/cli.js signal oi SOL-PERP --mock
#58
#59	# Live Phoenix read
#60	node perps/clawd-agents-perps/dist/cli.js signal oi SOL-PERP --rpc-url "$CLAWD_RPC_URL"
#61
#62	# Watch loop (5s interval)
#63	node perps/clawd-agents-perps/dist/cli.js signal watch SOL-PERP --interval 5s --mode paper --mock
#64
#65	# Risk gate check before entering
#66	node perps/clawd-agents-perps/dist/cli.js signal risk-gate SOL-PERP --notional 500 --side long --mock
#67	```
#68
#69	Sample output:
#70
#71	```json
#72	{
#73	"symbol": "SOL-PERP",
#74	"regime": "LONG_CONTINUATION",
#75	"side": "long",
#76	"score": 61.4,
#77	"confidence": 0.61,
#78	"market": {
#79	"markPrice": 184.22,
#80	"openInterestUsd": 18340291,
#81	"openInterestDeltaPct": 4.8,
#82	"priceDeltaPct": 1.1,
#83	"fundingRate": 0.00022,
#84	"spreadBps": 6.3
#85	},
#86	"gates": {
#87	"dataFresh": true,
#88	"oiPresent": true,
#89	"spreadOk": true,
#90	"fundingOk": true,
#91	"liquidityOk": true,
#92	"riskOk": true,
#93	"executable": true
#94	},
#95	"action": {
#96	"mode": "paper",
#97	"suggestedRoute": "phoenix",
#98	"maxNotionalUsdc": 610
#99	}
#100	}
#101	```
#102
#103	### MCP Tools
#104
#105	```ts
#106	// Returns the full ClawdOiCoreSignal
#107	clawd_perps_oi_signal({ symbol: "SOL-PERP", lookback: "5m", mode: "paper" })
#108
#109	// Returns a pass/fail gate for a specific notional + side
#110	clawd_perps_oi_risk_gate({ symbol: "SOL-PERP", notionalUsdc: 500, side: "long" })
#111	```
#112
#113	### OODA Loop Integration
#114
#115	```text
#116	Phoenix reads the tape.
#117	RPC verifies the chain.
#118	Percolator guards the invariants.
#119	Clawd scores the crowd.
#120	Imperial/Phoenix routes only after the shell says risk is clean.
#121	```
#122
#123	This is the Observe layer of the perps OODA loop — OI as a live agent-grade risk signal, not just a chart metric.
#124
#125	---
#126
#127	## Mission
#128
#129	- pull live Phoenix perp reads through the Rise SDK
#130	- compute structured OI signals with regime classification and gate checks
#131	- map Vulcan CLI and MCP surfaces into compatible agent routes
#132	- expose a market-maker runtime for observe, paper, and gated live previews
#133	- provide Telegram and frontend entrypoints that feel operational
#134	- keep secrets, signing, and irreversible actions out of the wrong layer
#135
#136	## Mental Model
#137
#138	1. Observe the market cleanly.
#139	2. Score the crowd. Pass the gates.
#140	3. Describe execution paths clearly.
#141	4. Refuse unsafe live behavior unless the runtime is explicitly armed.
#142
#143	---
#144
#145	## Layout
#146
#147	\| File \| Role \|
#148	\| --- \| --- \|
#149	\| `src/signals/oi-core.ts` \| Core OI signal — regime classifier, scorer, gate checks, `buildClawdOiCoreSignal` \|
#150	\| `src/adapters/phoenix-rise.ts` \| Phoenix Rise HTTP adapter — mark price, OI, funding, orderbook, mock support \|
#151	\| `src/adapters/perp-account-oi.ts` \| Raw Solana RPC account decoder for on-chain program OI reads \|
#152	\| `src/mcp/tools/clawd_perps_oi_signal.ts` \| MCP tool wrappers — `clawd_perps_oi_signal`, `clawd_perps_oi_risk_gate` \|
#153	\| `src/cli.ts` \| CLI entry — `signal oi`, `signal watch`, `signal risk-gate`, plus all existing commands \|
#154	\| `src/adapters/phoenixRise.ts` \| Rise-powered Phoenix read plane (markets, tickers, positions, health) \|
#155	\| `src/adapters/vulcan.ts` \| Vulcan execution-plan generator for paper routes and CLI-compatible live paths \|
#156	\| `src/marketMaker.ts` \| Clawd runtime for observe, paper, and live-preview orchestration \|
#157	\| `src/telegram.ts` \| Operator command surface (health, markets, positions, route previews) \|
#158	\| `src/frontend.ts` \| Dashboard/status payload builder \|
#159	\| `src/config.ts` \| Env parsing, trading-mode resolution, preflight gating \|
#160	\| `src/onchainMarketMaker.ts` \| Safe bridge to Phoenix on-chain market-maker reference workspace \|
#161	\| `src/twammAutomation.ts` \| Gated bridge for TWAMM build/test/crank automation \|
#162
#163	---
#164
#165	## CLI Reference
#166
#167	```bash
#168	# Build
#169	npm --prefix perps/clawd-agents-perps run build
#170
#171	# OI Signal — core commands
#172	node perps/clawd-agents-perps/dist/cli.js signal oi SOL-PERP --mock
#173	node perps/clawd-agents-perps/dist/cli.js signal oi SOL-PERP --rpc-url "$CLAWD_RPC_URL"
#174	node perps/clawd-agents-perps/dist/cli.js signal watch SOL-PERP --interval 5s --mode paper
#175	node perps/clawd-agents-perps/dist/cli.js signal risk-gate SOL-PERP --notional 500 --side long
#176
#177	# Runtime / market-maker
#178	node perps/clawd-agents-perps/dist/cli.js status
#179	node perps/clawd-agents-perps/dist/cli.js frontend
#180	node perps/clawd-agents-perps/dist/cli.js telegram "/perps"
#181
#182	# Imperial
#183	node perps/clawd-agents-perps/dist/cli.js imperial-scan --symbols SOL,BTC,ETH --size 100
#184	node perps/clawd-agents-perps/dist/cli.js imperial-cycle SOL --size 100
#185
#186	# Paper trades
#187	node perps/clawd-agents-perps/dist/cli.js paper-long SOL --notional 100
#188	node perps/clawd-agents-perps/dist/cli.js paper-short SOL --notional 100
#189
#190	# On-chain market maker (gated — requires CLAWD_ONCHAIN_MM_LIVE=true)
#191	node perps/clawd-agents-perps/dist/cli.js onchain-mm plan --market <pubkey> --ticker SOL-USD
#192	node perps/clawd-agents-perps/dist/cli.js onchain-mm run --market <pubkey> --yes
#193
#194	# TWAMM (gated — requires CLAWD_TWAMM_LIVE=true)
#195	node perps/clawd-agents-perps/dist/cli.js twamm crank-plan --token-a <mint> --token-b <mint>
#196	node perps/clawd-agents-perps/dist/cli.js twamm crank --token-a <mint> --token-b <mint> --yes
#197
#198	# Via clawd-perps package
#199	clawd-perps perps signal oi SOL-PERP --mode paper
#200	clawd-perps perps signal watch SOL-PERP --interval 5s --mode paper
#201	clawd-perps perps agent status
#202	```
#203
#204	### Signal CLI Options
#205
#206	\| Option \| Default \| Description \|
#207	\| --- \| --- \| --- \|
#208	\| `--mock` \| false \| Use hardcoded mock tick (no RPC/HTTP needed) \|
#209	\| `--mode` \| `paper` \| `observe`, `paper`, `dry-run`, `confirm-each`, `auto-execute` \|
#210	\| `--rpc-url` \| env \| Solana RPC URL \|
#211	\| `--api-url` \| env \| Phoenix Rise API base URL \|
#212	\| `--interval` \| `5s` \| Watch loop interval (supports `ms`, `s`, `m`) \|
#213	\| `--max-spread-bps` \| `25` \| Max spread before `spreadOk: false` \|
#214	\| `--max-funding-abs` \| `0.0025` \| Max absolute funding rate before `fundingOk: false` \|
#215	\| `--min-depth-usd` \| `25000` \| Min book depth before `liquidityOk: false` \|
#216	\| `--notional` \| `500` \| USDC notional for risk-gate check \|
#217	\| `--side` \| `long` \| Direction for risk-gate check \|
#218
#219	---
#220
#221	## Safety Posture
#222
#223	- `paper` / `observe` are the default signal modes — they never submit orders
#224	- Live execution requires `LIVE_TRADING=true`, `OPERATOR_CONFIRMED=true`, `PERPS_SIM_ONLY=false`
#225	- Imperial order submission additionally requires `IMPERIAL_LIVE=true`
#226	- On-chain MM requires `CLAWD_ONCHAIN_MM_LIVE=true` + `OPERATOR_CONFIRMED=true` + `--yes`
#227	- TWAMM crank requires `CLAWD_TWAMM_LIVE=true` + `OPERATOR_CONFIRMED=true` + `--yes`
#228	- No private keys in source — signing belongs in wallet/runtime integration
#229
#230	---
#231
#232	## Reading Order
#233
#234	1. `src/config.ts` — env flags and preflight gates
#235	2. `src/signals/oi-core.ts` — OI signal engine
#236	3. `src/adapters/phoenix-rise.ts` — live market data adapter
#237	4. `src/adapters/perp-account-oi.ts` — on-chain account OI reader
#238	5. `src/mcp/tools/clawd_perps_oi_signal.ts` — MCP tool surface
#239	6. `src/marketMaker.ts` — runtime orchestration
#240	7. `src/adapters/vulcan.ts` — execution planning
#241	8. `src/frontend.ts` — dashboard payloads
#242	9. `src/telegram.ts` — operator command surface
#243

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public