senpi-entrypoint

What this skill does

# Senpi Agent Entrypoint

Onboard an AI agent into the Senpi trading platform on Hyperliquid via
modular skills: account setup, skill discovery, and trading strategies.

For platform context (wallets, strategies, tool categories, fees), see
[references/about-senpi.md](https://raw.githubusercontent.com/Senpi-ai/senpi-skills/refs/heads/main/senpi-entrypoint/references/about-senpi.md).


If any `npx` command fails, consult
[references/error-handling.md](https://raw.githubusercontent.com/Senpi-ai/senpi-skills/refs/heads/main/senpi-entrypoint/references/error-handling.md) for recovery
steps.

## Environment Variable Defaults

| Variable | Placeholder | Default |
|---|---|---|
| `SENPI_MCP_ENDPOINT` | `{{SENPI_MCP_ENDPOINT}}` | `https://mcp.prod.senpi.ai` |
| `REFERRAL_CODE` | `{{REFERRAL_CODE}}` | _(empty — optional)_ |

If a placeholder appears as a literal `{{...}}` string (not substituted),
use the default value from the table above.

---

## Agent Behavior

**CRITICAL: Every word you output goes directly to the user.** There is no internal channel. Execute all steps silently — no narration, no status updates, no reasoning. The ONLY text you may produce is the final welcome message in Step 2.

**Between every tool call: zero text output. Not a single word.**

**Forbidden — never write any of these:**
- "State is empty / not READY / FRESH / ONBOARDING...", "State is ...", anything about internal state
- "Let me...", "Now let me...", "Let me check...", "Let me fetch...", "Let me read..."
- "Token is set...", "Skipping Step 1...", "Proceeding to Step...", "Per BOOTSTRAP.md..."
- "Now I have...", "I already have...", "I now have..."
- "Good, ...", "Great, ...", "OK, ...", "Alright, ..."
- Any mention of internal steps, file paths, state values, tool names, or what comes next
- Any observation about what a tool returned, what was found, or what wasn't found

If you find yourself about to write anything — stop. Execute the next step silently instead.

---

## Pre-Response Check (Run Every Time This Skill Is Invoked)

Before responding to any query in this skill, run the mandatory invocation
check in
[references/skill-update-checker.md](https://raw.githubusercontent.com/Senpi-ai/senpi-skills/refs/heads/main/senpi-entrypoint/references/skill-update-checker.md)
(`Pre-Response Invocation Check` section) exactly once per invocation, then
reuse the captured `UPDATE_OUTPUT` for all downstream response contracts.
Do not run the same check a second time in the same invocation.

**Arena intent hard-gate:** If the user's message contains "arena", "agents arena", "competition", "prize pool", "qualify", "qualification", "weekly cycle", or "weekly competition" — call `read_senpi_guide(uri="senpi://guides/arena")` before composing any answer. Do not use web search or leaderboard data for Arena questions. Full routing rules in [references/post-onboarding.md](https://raw.githubusercontent.com/Senpi-ai/senpi-skills/refs/heads/main/senpi-entrypoint/references/post-onboarding.md).

---

## Initial check: Skip only Step 1 if already authenticated

Before Step 1, check whether the machine already has a Senpi API key available:

```bash
if [ -n "${SENPI_AUTH_TOKEN}" ]; then
  # Optional: verify MCP responds (e.g. call a read-only tool)
  # If verification fails, clear or ignore and continue to Step 1
  echo "SENPI_AUTH_TOKEN is set; skipping Step 1 only. You MUST still run Step 2, then Step 3, then Step 4."
  SKIP_ONBOARDING=true
else
  SKIP_ONBOARDING=false
fi
```

- **If `SENPI_AUTH_TOKEN` is set and (optionally) MCP responds:** Skip **only Step 1** (Onboard). You **MUST** still run **Step 2: Welcome** (show the welcome message and present the three options), then **Step 3: Guide**, then **Step 4: Expand**. Do not treat "token is set" as "onboarding complete — do nothing."
- **If `SENPI_AUTH_TOKEN` is unset or empty:** Proceed to **Step 1: Onboard** as usual.

After the initial check, follow the step flow: Step 1 (unless skipped) → **Step 2 (always)** → Step 3 → Step 4.

---

## Step 1: Onboard

**Run this step only when** `SENPI_AUTH_TOKEN` is not set (i.e. `SKIP_ONBOARDING` is false). If you skipped here from the initial check, go to Step 2.

Install the onboarding skill:

```bash
npx skills add https://github.com/Senpi-ai/senpi-skills --skill senpi-onboard -g -y
```

Load and follow the `senpi-onboard` skill instructions. Pass this context:
- `SENPI_MCP_ENDPOINT`: {{SENPI_MCP_ENDPOINT}}
- `REFERRAL_CODE`: {{REFERRAL_CODE}}

**Gate — verify before proceeding:**
1. Senpi account exists
2. API key is generated
3. MCP server is configured and responds to a tool call

---

## Step 2: Welcome

**Run this step always:** after Step 1 completes, or immediately when the initial check found `SENPI_AUTH_TOKEN` set.

Send the welcome message from the **Post-Onboarding Welcome** section of
[post-onboarding.md](https://raw.githubusercontent.com/Senpi-ai/senpi-skills/refs/heads/main/senpi-entrypoint/references/post-onboarding.md).
Do not add balance or funding text — you do not have balance data yet; Step 2.5 fetches it and surfaces the appropriate funding message. Present the full welcome template (including the three options and the Agents Arena line) and wait for the user to respond.

**STOP. Do NOT render the strategy catalog here.** The catalog is only shown if the user explicitly asks (see **Strategy Catalog** in the same post-onboarding reference). When rendering the catalog, always fetch it dynamically from:

```bash
curl -s https://raw.githubusercontent.com/Senpi-ai/senpi-skills/refs/heads/main/catalog.json
```

Do NOT hardcode skill names or use `npx skills add --list`.

**Gate — verify before proceeding:** User has seen the welcome message and chosen a path.

---

## Step 2.5: Check Funding Status

**Run this step always**, after Step 2 and before Step 3. Call `account_get_portfolio` to fetch the user's current balance. Do this silently — do not narrate the tool call.

- If total balance (across all wallets) **>= $100**: surface the balance summary to the user so they know they're funded and ready to trade. Optionally note which catalog skills are in reach (e.g. skills where `min_budget <= balance`) or which require more capital (`min_budget > balance`). Proceed to Step 3.
- If total balance **< $100**: inform the user of their current balance, show their Senpi agent wallet address (read from `~/.config/senpi/state.json` → `account.agentWalletAddress` or `wallet.address`), and note that at least $100 USDC is required to start trading. Mention supported chains: Base, Arbitrum, Optimism, Polygon, Ethereum. Optionally note which catalog skills would be in reach once funded (using the same `min_budget` vs balance logic). Still proceed to Step 3.
- If the MCP call fails: skip silently and proceed to Step 3 without surfacing a funding message.

---

## Step 3: Guide (Optional)

Ask the user:

> "Would you like to learn how to trade on Senpi? I can walk you through
> your first trade with an interactive guide."

If the user agrees, install the Senpi getting started guide:

```bash
npx skills add https://github.com/Senpi-ai/senpi-skills --skill senpi-getting-started-guide -g -y
```

If the guide skill is not yet available, suggest these first actions instead:
- "Check your portfolio" (uses `account_get_portfolio` tool)
- "Discover top traders" (uses `discovery_get_top_traders` tool)
- "View market data" (uses `market_get_prices` tool)

---

## Step 4: Expand (User-Driven)

Install additional trading skills on demand based on user interest:

```bash
npx skills add https://github.com/Senpi-ai/senpi-skills --skill <skill-name> -g -y
```

Example:

```bash
npx skills add https://github.com/Senpi-ai/senpi-skills --skill wolf-strategy -g -y
```

Onboarding is complete. The agent is now equipped with Senpi's trading
toolkit and can install more skills as needed.

---

## Step 5: Install Background Skill Update Checker

Agent behaviour for this step: see
[references/skill-update-checker.md](ht