--- name: coinversa-pulse-essentials description: "Use Coinversa Pulse well and safely: confirm the account and key scope, pick between the builder_, hip4_ and list_ tool families, keep result sets small, and handle sign-in, permission and revoked-key errors. Use when the user connects Coinversa Pulse, asks what it can answer, or when any Pulse call fails or returns too much data." --- # Use Coinversa Pulse Pulse is a read-analytics connector over Hyperliquid trader activity, HIP-4 outcome markets and an asset registry. This skill covers how to aim a question at the right tool family, keep results usable, and recover when a call is blocked. The per-tool behaviour of each analysis lives in the sibling skills; use this one first to orient. ## 1. Confirm the account and scope before the first call The connector acts on behalf of the signed-in Coinversa account and the key chosen during authorisation. Before a substantive query, state which account the session is using if the user has more than one, and whether the key is on a plan that covers the question. Access is governed by the plan attached to the key, so a permission refusal usually means the plan, not a bug. Say so plainly and suggest checking the key or plan in the developer portal rather than retrying in a loop. ## 2. Choose the right tool family Map the question to a family before calling anything: - **`builder_*`**: questions about builders, traders and their behaviour over time: profiles, journeys, lifecycle stages, orders, fills, cohorts, retention, leaderboards, overlap between builders. - **`hip4_*`**: questions about HIP-4 outcome (prediction) markets: outcome lists and summaries, trades, daily volume, participants, settlements, and cross-product links to perps. - **`list_asset` / `list_assets`**: the cross-market asset registry. Use it to resolve a symbol or identifier to its canonical form before querying another family, and to check what an asset is before assuming it is a perp or an outcome. Start with the registry when the user names an asset ambiguously. Do not run a broad `list_assets` sweep to answer a single-asset question; it floods context and rarely adds signal. ## 3. Keep result sets small Analytics endpoints return large lists by default. Ask for a bounded window (a time range, a top-N, a single outcome or single trader) and state the window in your answer. Where a tool supports paging or limits, use them and fetch further pages only when the first page cannot answer the question. Summarise and quote the few rows that matter instead of pasting tables. If a result is truncated, say how many rows you saw and what was left out. ## 4. Resolve identifiers first, then query Traders, builders and outcomes are referenced by identifiers. If the user gives a name, a partial address or a question title, resolve it with the matching list or search-style tool (`hip4_outcomes`, `builder_traders`, `list_assets`) before deep queries. Confirm the resolved identifier back to the user when more than one candidate matches; do not pick silently. ## 5. Handle errors and blocked calls - **401 Unauthorized / sign-in prompt**: the authorisation expired or the key behind it was revoked. Tell the user to reconnect through the Coinversa sign-in page. Do not retry with the same credentials. - **Revoked key**: revoking a key disconnects every agent using it. The fix is a fresh authorisation, not a retry. - **Plan or permission refusal**: the tool exists but the key's plan does not cover it. Report which capability was blocked and stop that line of enquiry; do not work around it with other tools to reach the same data. - **Empty result**: say so. An empty list often means the filter or window was too narrow, not that nothing happened. Widen once, then report. - **Rate limit or timeout**: back off, reduce the window, and report partial results honestly. ## 6. Know what this connector does not do No write tools are exposed in this list. The connector does not place orders, move funds, change alerts or alter any account. If a user asks for an action, say that Pulse is analytics only and do not imply a trade or change has happened or can happen through it. ## Common patterns and traps - **Confusing a perp with an outcome.** The same underlying asset can appear in both families. Check the registry first, then query the matching family, and say which market you are reporting on. - **Unbounded pulls.** Asking for "all trades" floods the context and gives a worse answer than a scoped window. Narrow first. - **Trusting an unresolved name.** A partial match returned as the answer is a common error. Confirm the identifier. - **Retry loops on auth.** Repeating a 401 wastes time and can look like abuse. Stop and direct the user to reconnect. - **Treating analytics as advice.** Trader behaviour, leaderboard rank and outcome volume describe activity; they do not establish skill, intent or a recommendation. Say so when the user draws conclusions. - **Stale context.** A connection made earlier may have been revoked. If calls suddenly fail after working, suspect the key before the query. ## Output ``` Account / key: Tool family used: Window and limits: