diff --git a/docs/perps-mcp/features.mdx b/docs/perps-mcp/features.mdx index 7337ee3..59b03e0 100644 --- a/docs/perps-mcp/features.mdx +++ b/docs/perps-mcp/features.mdx @@ -12,7 +12,9 @@ Start with `host-tools --brief` and `host-tools schema ` before using | Feature | What It Does | Example Prompts | Direct Command | | --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Account State** | View account, margin, positions, open orders, and portfolio | `"show my perps positions"` `"what open orders do I have?"` | `host-tools getHyperliquidPositions` | +| **Account Health** | Snapshot authenticated account exposure and margin | `"check my perps account health"` | `host-tools perps.accountHealth includeExitEstimates=true` | | **Markets** | List canonical Hyperliquid markets and asset metadata | `"show Hyperliquid markets"` `"what is BTC funding?"` | `host-tools getHyperliquidMarkets` | +| **Market Radar** | Rank markets by activity and compare retained samples | `"radar for active perp markets"` | `host-tools perps.marketRadar limit=10` | | **Prices** | Fetch one or many live perps prices | `"BTC perps price"` `"price BTC ETH SOL"` | `host-tools getHyperliquidPrice '{\"asset\":\"BTC\"}'` | | **HIP-3 Discovery** | Search HIP-3 markets and list builder-deployed DEXes | `"search HIP-3 markets for CL"` `"list HIP-3 DEXes"` | `host-tools perps.hip3.search query=CL` | | **HIP-3 Prices** | Read venue-scoped HIP-3 prices | `"price CL on xyz"` | `host-tools perps.hip3.price '{\"dex\":\"xyz\",\"coin\":\"CL\"}'` | @@ -25,6 +27,28 @@ Start with `host-tools --brief` and `host-tools schema ` before using | **Data Fetching** | Fetch trades, candles, and order books into sandbox tables | `"fetch BTC candles into SQL"` | `host-tools fetchHyperliquidCandles '{\"coin\":\"BTC\",\"interval\":\"1h\"}'` | | **SQL Analysis** | Query fetched perps data with DuckDB/SQLite-style workflows | `"query large BTC trades"` | `sql query "SELECT * FROM LIMIT 10"` | + + Account health and market radar require a separately authorized [Perps MCP + connection](/perps-mcp/client-setup) with `tools:execute`. They are not read tools in the Ask Gina + listed plugin. + + +## Account health + +`perps.accountHealth` requires an authenticated account. It defaults to canonical Hyperliquid. Pass `providerContext` with `{"providerId":"hip3:xyz"}` for an enabled HIP-3 venue. + +The response includes at most 64 positions. Set `includeExitEstimates=true` for indicative exit estimates on at most eight positions, not fill guarantees. The tool does not assign a health score or calculate historical performance. + +## Market radar + +`perps.marketRadar` accepts `limit` from 1 to 50, defaulting to 10, and an optional `dex`, such as `dex=xyz`. Omit `dex` for canonical Hyperliquid. + +Eligible markets rank by descending 24-hour traded volume, then open interest, then absolute 24-hour price change, with coin name breaking ties. This measures activity and exposure, not liquidity, depth, or executable size. Excluded-market details are capped at 100. + +Rank, volume, open-interest, and mark-price deltas compare with a shared sample for that venue, not the caller's previous request. Samples rotate no more often than every five minutes and expire after seven days. Rows without a prior entry are marked `firstSeen`. + +Radar returns the complete JSON response inline or in an artifact. It does not automatically extract the rows into SQL tables. + ## Discovery Flow Use this sequence when you are unsure which tool to call: diff --git a/packages/contracts/__tests__/contracts.test.ts b/packages/contracts/__tests__/contracts.test.ts index 5d89203..085440b 100644 --- a/packages/contracts/__tests__/contracts.test.ts +++ b/packages/contracts/__tests__/contracts.test.ts @@ -11,8 +11,6 @@ import { GinaReadToolCatalogJsonSchema, PRODUCTION_MCP_URL, READ_SCOPE, - RELEASE_VERSION, - SOURCE_COMMIT, catalogSha, getGinaReadToolAnnotations, getGinaReadToolFamily, @@ -201,13 +199,11 @@ describe("@askgina/contracts", () => { }), ); - it.effect("pins endpoints, scopes, and source compatibility", () => + it.effect("publishes endpoints and scopes with a computed catalog digest", () => Effect.gen(function* () { assert.strictEqual(PRODUCTION_MCP_URL, "https://askgina.ai/ai/gina/mcp"); assert.strictEqual(READ_SCOPE, "tools:read"); assert.strictEqual(EXECUTE_SCOPE, "tools:execute"); - assert.strictEqual(RELEASE_VERSION, "0.1.0"); - assert.strictEqual(SOURCE_COMMIT, "51d99dde59e17080255fdb4ae8e59a63355a8b5e"); const computedCatalogSha = createHash("sha256") .update(yield* Schema.encodeEffect(GinaReadToolCatalogJsonSchema)(GINA_READ_TOOL_CATALOG)) diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index a9d2b87..0ba321a 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -416,6 +416,6 @@ export const ASK_GINA_SKILL_DEFINITIONS = [ }, ] as const satisfies readonly AskGinaSkillDefinition[]; -export const SOURCE_COMMIT = "51d99dde59e17080255fdb4ae8e59a63355a8b5e"; +export const SOURCE_COMMIT = "ea8c56a0b065ea44cde89d05567999f976c61071"; export const RELEASE_VERSION = "0.1.0"; export const catalogSha = "6738637b18462cafa3f4ffb77c1503515a7f851f9ec4130fa380ada7416d3b7e"; diff --git a/plugins/ask-gina/README.md b/plugins/ask-gina/README.md index 7d32330..bbb8f51 100644 --- a/plugins/ask-gina/README.md +++ b/plugins/ask-gina/README.md @@ -61,7 +61,7 @@ Scope: `tools:read` only. This plugin does not include transaction execution or 1. Install **Ask Gina** from the Cursor / Grok Bot plugin marketplace, or load this folder as a local Cursor plugin (`~/.cursor/plugins/local/ask-gina` as a real directory, not an external symlink). 2. Open the Gina connector and choose **Connect**. Complete Ask Gina OAuth in the browser. -3. Confirm the connector shows the read tools (30 catalog tools). Skills below should appear as well. In Cursor, the four slash commands and the always-on read-only rule should appear too. +3. Confirm the connector shows the read tools (31 catalog tools). Skills below should appear as well. In Cursor, the four slash commands and the always-on read-only rule should appear too. Grok Bot loads plugins only from the Cursor marketplace. A local `~/.cursor/plugins/local` install proves the Cursor IDE loader, not Grok Bot.