Skip to content

docs(perps): align health and radar access #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ericjuta merged 1 commit into from
Sep 11, 2026
Merged

docs(perps): align health and radar access #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/perps-mcp/features.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@ Start with `host-tools --brief` and `host-tools schema <toolName>` 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\"}'` |
Expand All @@ -25,6 +27,28 @@ Start with `host-tools --brief` and `host-tools schema <toolName>` 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 <table> LIMIT 10"` |

<Note>
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.
</Note>

## 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:
Expand Down
6 changes: 1 addition & 5 deletions packages/contracts/__tests__/contracts.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,6 @@ import {
GinaReadToolCatalogJsonSchema,
PRODUCTION_MCP_URL,
READ_SCOPE,
RELEASE_VERSION,
SOURCE_COMMIT,
catalogSha,
getGinaReadToolAnnotations,
getGinaReadToolFamily,
Expand Down Expand Up @@ -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))
Expand Down
2 changes: 1 addition & 1 deletion packages/contracts/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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";
2 changes: 1 addition & 1 deletion plugins/ask-gina/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading