senpi-entrypoint

name	senpi-entrypoint
description	Onboard AI agents into the Senpi trading platform on Hyperliquid. Walks through account creation, API key setup, MCP server configuration, skill discovery, and first-trade guidance. Includes a mandatory skill update check that surfaces new or updated skills after onboarding. Use when user says "set up Senpi", "get started with Senpi", "connect to Senpi", "install Senpi", "onboard to Senpi", or when an agent needs to start trading on Hyperliquid via Senpi.
license	Apache-2.0
compatibility	Node.js, shell, Python 3, OpenClaw (optional — Step 5 cron)
metadata	{"author":"Senpi","version":"1.2.2","platform":"senpi","exchange":"hyperliquid"}

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.

If any npx command fails, consult 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 (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.

---

Initial check: Skip only Step 1 if already authenticated

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

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:

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. 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:

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:

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:

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

Example:

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 (§ "Step 5 Agent Behaviour").

Run this step after Step 4 completes. It registers a daily OpenClaw cron job that runs the skill update checker in an isolated session with no delivery; the agent runs the script and exits with no reply. Results are queued for the next session startup.

Locate the script

SENPI_ENTRYPOINT_SCRIPTS=$(node -e "
  const path = require('path'), os = require('os'), fs = require('fs');
  const p = path.join(os.homedir(), '.agents', 'skills', 'senpi-entrypoint', 'scripts');
  console.log(fs.existsSync(path.join(p, 'check-skill-updates.py')) ? p : '');
" 2>/dev/null)

If SENPI_ENTRYPOINT_SCRIPTS is empty the skill was not installed globally (npx skills add ... -g) — skip this step silently. If openclaw is not available in PATH, skip this step silently.

Install OpenClaw cron (idempotent)

if [ -n "$SENPI_ENTRYPOINT_SCRIPTS" ] && command -v openclaw >/dev/null 2>&1; then
  openclaw cron remove "senpi-skill-update-check" 2>/dev/null || true
  SCRIPT_PATH="$SENPI_ENTRYPOINT_SCRIPTS/check-skill-updates.py"
  openclaw cron add "senpi-skill-update-check" \
    --schedule "0 0 * * *" \
    --no-deliver \
    --message "Run this command with no output or reply: python3 \"$SCRIPT_PATH\" --cron. Then exit. Do not deliver or announce anything."
fi

The job is stored in $OPENCLAW_STATE_DIR/cron/jobs.json (default: ~/.openclaw/cron/jobs.json if OPENCLAW_STATE_DIR is unset). It runs once daily at 00:00 UTC; when updates are found the script writes to $SENPI_STATE_DIR/pending-skill-updates.json (default: ~/.config/senpi/pending-skill-updates.json if SENPI_STATE_DIR is unset), surfaced at the next invocation via Pre-Response Check (above).

---

Turning skill update notifications on or off

If the user asks to turn notifications off or back on, follow the procedure in references/skill-update-checker.md.

---

Responding to Questions

Mandatory Response Contract (Execution NOT Optional)

For any summary or Q&A response, follow references/about-senpi.md (Summary Response Contract and Mandatory Invocation Procedure sections). Use the UPDATE_OUTPUT produced by the top-level Pre-Response Check above; do not rerun Pre-Response Invocation Check here unless it has not yet been run in the current invocation. Do not consider the response complete until those procedures are satisfied.

"What is Senpi?" / "Summarize Senpi" / "Summarize skills and capabilities" / "How do I install skills?" / "What's new?"

This is explicit-ask only — do not auto-insert this summary into normal onboarding steps.

When asked, load and follow references/about-senpi.md (Summary Response Contract section) for order, depth, and command behavior.

"What skills should I install?" / "What should I use for [goal]?"

Consult references/skill-recommendations.md for the goal-to-skill mapping, budget guidance, and install commands.

---

Reference Files

File	Purpose
scripts/check-skill-updates.py	Daily background checker (run via cron with --cron). Reads Vercel skills CLI lock file, compares GitHub tree SHAs, writes version bumps / new skills to pending file
references/skill-update-checker.md	Startup output handling + turn notifications on/off + cron management
references/skill-recommendations.md	Goal-to-skill mapping table, budget guidance, install commands
references/about-senpi.md	Senpi summary source: what Senpi is, capabilities, full bullet catalog, user-friendly install flow, and what's-new guidance
references/error-handling.md	Recovery steps for npx command failures