senpi-onboard

Senpi エージェントのオンボーディング

Senpi 取引プラットフォームに AI エージェントをオンボーディングします。このフローを完了すると、エージェントは Senpi アカウントと API キーを取得し、ポートフォリオ管理、トレーダーの発見、戦略の作成、Hyperliquid での注文執行に使用できる MCP サーバーへの接続が確立されます。

前提条件： シェル／コード実行へのアクセスと Node.js（npx に必要）。

デフォルト

• SENPI_MCP_ENDPOINT：https://mcp.prod.senpi.ai（{{SENPI_MCP_ENDPOINT}} が置換されていないプレースホルダーのままの場合に使用）
• REFERRAL_CODE：空／任意（{{REFERRAL_CODE}} が置換されていないプレースホルダーのままの場合に使用）

Arena の意図に関する必須ゲート： ユーザーのメッセージに「arena」、「agents arena」、「competition」、「prize pool」、「qualify」、「qualification」、「weekly cycle」、「weekly competition」のいずれかが含まれる場合、回答を作成する前に read_senpi_guide(uri="senpi://guides/arena") を呼び出してください。Arena に関する質問には、ウェブ検索やリーダーボードのデータを使用しないでください。完全なルーティングルールについては、references/post-onboarding.md を参照してください。

---

オンボーディングのフロー

すべての手順を順番どおりに実行してください。手順を省略しないでください。

開始前：状態の初期化

state lifecycle に従って、ルーティングと遷移が明確に定義されるよう、state.json が存在することを確認してください。存在しない場合は、初期状態を FRESH として作成してください。

if [ ! -f ~/.config/senpi/state.json ]; then
  mkdir -p ~/.config/senpi
  cat > ~/.config/senpi/state.json << 'STATEEOF'
{
  "version": "1.0.0",
  "state": "FRESH",
  "error": null,
  "onboarding": {
    "step": "IDENTITY",
    "startedAt": null,
    "completedAt": null,
    "identityType": null,
    "subject": null,
    "walletGenerated": false,
    "existingAccount": false
  },
  "account": {},
  "wallet": { "funded": false },
  "firstTrade": { "completed": false, "skipped": false },
  "mcp": { "configured": false }
}
STATEEOF
fi

その後、ステップ 0 に進んでください。

ONBOARDING への遷移： ステップ 0 を実行する前に、状態が FRESH の場合は、ステートマシンと再開時の動作が正常に機能するよう state.json を更新してください。state を ONBOARDING に設定し、onboarding.startedAt を現在の ISO 8601 UTC 時刻に設定し、onboarding.step は IDENTITY のままにしてください。他のフィールドを保持できるよう、読み取り・変更・書き込み（マージ）を使用してください。

node -e "
  const fs = require('fs');
  const p = require('os').homedir() + '/.config/senpi/state.json';
  const s = JSON.parse(fs.readFileSync(p, 'utf8'));
  if (s.state === 'FRESH') {
    s.state = 'ONBOARDING';
    s.onboarding = s.onboarding || {};
    s.onboarding.startedAt = new Date().toISOString();
    s.onboarding.step = s.onboarding.step || 'IDENTITY';
    fs.writeFileSync(p, JSON.stringify(s, null, 2));
  }
"

状態がすでに ONBOARDING の場合は、onboarding.step を読み取り、ステップ 0 からではなく、そのステップから再開してください（references/state-management.md を参照）。

ステップ 0：mcporter の確認（OpenClaw のみ）

mcporter CLI が利用可能か確認してください。

if command -v mcporter &> /dev/null; then
  MCPORTER_AVAILABLE=true
else
  MCPORTER_AVAILABLE=false
fi

利用できず、OpenClaw を使用している場合は、インストールしてください。

npm i -g mcporter
mcporter --version

インストール後、MCPORTER_AVAILABLE=true を設定して続行してください。

---

ステップ 1：本人情報の収集

次の 3 つの選択肢をすべてユーザーに提示し、選択を待ってください。

1. 選択肢 A -- Telegram ユーザー ID：スキルが USER.md から Telegram の本人情報を自動的に読み取ります。
2. 選択肢 B -- ユーザーが指定するウォレット：0x で始まり、16 進数文字が正確に 42 文字である必要があります。続行する前に検証してください。
3. 選択肢 C -- エージェントが生成するウォレット（どちらも持っていない場合のみ）。

選択肢 A：Telegram ユーザー ID の収集

ユーザーが選択肢 A を選んだ場合、まず ${OPENCLAW_WORKSPACE_DIR}/USER.md からの読み取りを試みてください。

USER_MD="${OPENCLAW_WORKSPACE_DIR}/USER.md"
if [ -f "$USER_MD" ]; then
  TELEGRAM_USER_ID=$(awk '/^## Telegram/{f=1; next} f && /^## /{f=0} f && /- Chat ID:/{print $NF; exit}' "$USER_MD")
  TELEGRAM_USERNAME=$(awk '/^## Telegram/{f=1; next} f && /^## /{f=0} f && /- Username:/{print $NF; exit}' "$USER_MD")
  TELEGRAM_USERNAME="${TELEGRAM_USERNAME#@}" # normalize for API userName field
fi

TELEGRAM_USER_ID（数字のみ、空でない）と TELEGRAM_USERNAME（空でない）の両方が見つかった場合は、ユーザーに確認せず変数を自動的に設定してください。

IDENTITY_TYPE="TELEGRAM"
IDENTITY_VALUE="$TELEGRAM_USER_ID"

USER.md が見つからない場合、またはいずれかのフィールドが存在しないか無効な場合は、手動での確認に切り替えてください。ユーザー向けの手順と検証ルールについては、references/telegram-identity.md を参照してください。手動で確認する場合は、ユーザーの入力から TELEGRAM_USERNAME も設定し、API で使用する前に TELEGRAM_USERNAME="${TELEGRAM_USERNAME#@}" を実行して正規化してください。

選択肢 B：変数の設定

IDENTITY_TYPE="WALLET"
IDENTITY_VALUE="0x..."  # 0x-prefixed wallet address

オプション C：EVM ウォレットを生成する

ユーザーがウォレットも Telegram も持っていないことを確認した場合にのみ使用します。実行する前にユーザーに伝えてください。

同梱のスクリプトを実行してウォレットを生成します。

# Try npx first, then local install fallbacks
WALLET_DATA=$(npx -y -p ethers@6 node scripts/generate_wallet.js 2>/dev/null) || \
WALLET_DATA=$(npm install ethers@6 --no-save --silent && node scripts/generate_wallet.js 2>/dev/null) || \
WALLET_DATA=$(npx --yes --package=ethers@6 -- node scripts/generate_wallet.js)

スクリプトが scripts/generate_wallet.js にない場合は、インラインで生成します。

WALLET_DATA=$(npx -y -p ethers@6 node -e "
  const { ethers } = require('ethers');
  const w = ethers.Wallet.createRandom();
  console.log(JSON.stringify({
    address: w.address,
    privateKey: w.privateKey,
    mnemonic: w.mnemonic.phrase
  }));
")

失敗してもユーザーに尋ねず、フォールバックを黙って試してください。すべての方法が失敗した場合にのみ報告してください。ウォレット生成の失敗処理については、references/error-handling.md を参照してください。

WALLET_DATA JSON を解析して、address、privateKey、mnemonic を抽出します。アドレスが空でも null でもないことを検証してください。無効な場合は停止し、エラー処理のリファレンスを参照してください。

ウォレットを直ちに保存します（続行する前に）。解析した値を使用してください。

mkdir -p ~/.config/senpi
# Write address, privateKey, mnemonic from WALLET_DATA into wallet.json
chmod 600 ~/.config/senpi/wallet.json

ファイルには、address、privateKey、mnemonic、generatedAt（ISO 8601 UTC）、および "generatedBy": "senpi-onboard" を含める必要があります。

重要：

• 秘密鍵やニーモニックをログに記録したり、表示したりしないでください。
• wallet.json が書き込まれ、権限が設定されるまで続行しないでください。

解析したアドレスを使用して、ID 変数を設定します。

WALLET_GENERATED=true
IDENTITY_TYPE="WALLET"
IDENTITY_VALUE="<address from WALLET_DATA>"

ウォレットが生成され、アクセス制限付きの権限で ~/.config/senpi/wallet.json に保存されたことをユーザーに通知してください。このファイルをすぐにバックアップするよう指示してください。

続行前に確認

ステップ 2 の前に、以下が設定されていることを確認してください。

• IDENTITY_TYPE — "WALLET" または "TELEGRAM"
• IDENTITY_VALUE — ウォレットアドレス（0x を含む）または Telegram の数値ユーザー ID（数字のみ）
• WALLET_GENERATED — オプション C を使用した場合は true、それ以外は未設定
• TELEGRAM_USERNAME — IDENTITY_TYPE="TELEGRAM" の場合は必須かつ空でないこと（それ以外は未設定）

再開に備えて進行状況を保存します： ~/.config/senpi/state.json を更新し、onboarding.step を REFERRAL に設定します。使用可能な場合は、現在の変数から onboarding.identityType、onboarding.subject、onboarding.walletGenerated も設定してください。他のフィールドを保持できるよう、読み取り・変更・書き込みの手順を使用してください。

---

ステップ 2：リファラルコードを設定する

REFERRAL_CODE="{{REFERRAL_CODE}}"

空で、ユーザーが提供していない場合は問題ありません。これは任意です。ユーザーがリファラルコードを持っていると言わない限り、尋ねないでください。

再開に備えて進行状況を保存します： ~/.config/senpi/state.json を更新し、onboarding.step を API_CALL に設定します。読み取り・変更・書き込みの手順を使用してください。

---

ステップ 3：オンボーディング API を呼び出す

CreateAgentStubAccount GraphQL ミューテーションを実行します。これは公開エンドポイントであり、認証は不要です。

if [ "$IDENTITY_TYPE" = "TELEGRAM" ] && [ -z "${TELEGRAM_USERNAME:-}" ]; then
  echo "TELEGRAM_USERNAME must be set when IDENTITY_TYPE=TELEGRAM" >&2
  exit 1
fi

RESPONSE=$(curl -s -X POST https://moxie-backend.prod.senpi.ai/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateAgentStubAccount($input: CreateAgentStubAccountInput!) { CreateAgentStubAccount(input: $input) { user { id privyId userName name referralCode referrerId } apiKey apiKeyExpiresIn apiKeyTokenType referralCode agentWalletAddress } }",
    "variables": {
      "input": {
        "from": "'"${IDENTITY_TYPE}"'",
        "subject": "'"${IDENTITY_VALUE}"'",
        '"$([ "$IDENTITY_TYPE" = "TELEGRAM" ] && echo "\"userName\": \"${TELEGRAM_USERNAME}\",")"'
        "referralCode": "'"${REFERRAL_CODE}"'",
        "apiKeyName": "agent-'"$(date +%s)"'"
      }
    }
  }')

TELEGRAM ID の場合の注意： 入力に追加の "userName" フィールドを含め、正規化した TELEGRAM_USERNAME（USER.md またはユーザー入力から取得した、先頭に @ のない Telegram ユーザー名）を設定してください。

再開に備えて進行状況を保存します： ~/.config/senpi/state.json を更新し、onboarding.step を PARSE に設定します。読み取り・変更・書き込みの手順を使用してください。

---

ステップ 4：レスポンスを解析する

まずエラーを確認します。response.errors が存在し、エントリーがある場合は、errors[0].message を抽出してください。エラー表と手動フォールバックのフローについては、references/error-handling.md を参照してください。

エラーがない場合は、JSON レスポンスを解析して以下を抽出します。

• data.CreateAgentStubAccount.apiKey から API_KEY
• data.CreateAgentStubAccount.user.id から USER_ID
• data.CreateAgentStubAccount.referralCode から USER_REFERRAL_CODE
• data.CreateAgentStubAccount.agentWalletAddress から AGENT_WALLET_ADDRESS

続行する前に、API キーが空でも null でも undefined でもないことを確認してください。

再開に備えて進行状況を保存します： ~/.config/senpi/state.json を更新し、onboarding.step を CREDENTIALS に設定します。読み取り・変更・書き込みの手順を使用してください。

---

ステップ 5：認証情報を保存する

mkdir -p ~/.config/senpi
cat > ~/.config/senpi/credentials.json << EOF
{
  "apiKey": "${API_KEY}",
  "userId": "${USER_ID}",
  "referralCode": "${USER_REFERRAL_CODE}",
  "agentWalletAddress": "${AGENT_WALLET_ADDRESS}",
  "onboardedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "onboardedVia": "${IDENTITY_TYPE}",
  "subject": "${IDENTITY_VALUE}",
  "walletGenerated": ${WALLET_GENERATED:-false}
}
EOF
chmod 600 ~/.config/senpi/credentials.json

重要： 生の API キーをログに記録したり、表示したりしないでください。キーの値を出力せずに、認証情報が保存されたことを確認してください。

ウォレットを生成した場合（オプション C）、~/.config/senpi/wallet.json が引き続き存在することを確認してください。見つからない場合は、オンボーディングを停止してユーザーに警告してください。

再開に備えて進行状況を保存します： ~/.config/senpi/state.json を更新し、onboarding.step を MCP_CONFIG に設定します。読み取り・変更・書き込みの手順を使用してください。

---

ステップ 6：MCP サーバーの設定

エージェントのプラットフォームを検出し、それに応じて設定します。各プラットフォームの設定コマンドの全一覧については、references/platform-config.md を参照してください。

• OpenClaw（mcporter を利用可能） -> mcporter config add senpi ...
• Claude Code（claude CLI を利用可能） -> claude mcp add senpi ...
• 汎用 -> .mcp.json 設定ファイルを作成／マージします

SENPI_MCP_ENDPOINT（デフォルト：https://mcp.prod.senpi.ai）と、ステップ 4 の API_KEY を使用します。

再開に備えて進捗を保存： ステップ 7 で state: UNFUNDED と onboarding.step: COMPLETE を含む最終状態を書き込むため、ここで個別にステップを更新する必要はありません。

---

ステップ 7：確認と完了

状態を UNFUNDED に更新します。現在の状態にある onboarding.startedAt（FRESH → ONBOARDING の遷移時に設定）を保持し、上書きしないでください。

ONBOARDING_STARTED_AT=$(node -e "
  try {
    const fs = require('fs');
    const p = require('os').homedir() + '/.config/senpi/state.json';
    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
    const v = j.onboarding && j.onboarding.startedAt;
    console.log(v ? JSON.stringify(v) : 'null');
  } catch (e) { console.log('null'); }
")
cat > ~/.config/senpi/state.json << EOF
{
  "version": "1.0.0",
  "state": "UNFUNDED",
  "error": null,
  "onboarding": {
    "step": "COMPLETE",
    "startedAt": ${ONBOARDING_STARTED_AT},
    "completedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
    "identityType": "${IDENTITY_TYPE}",
    "subject": "${IDENTITY_VALUE}",
    "walletGenerated": ${WALLET_GENERATED:-false}
  },
  "account": {
    "userId": "${USER_ID}",
    "referralCode": "${USER_REFERRAL_CODE}",
    "agentWalletAddress": "${AGENT_WALLET_ADDRESS}"
  },
  "wallet": {
    "address": "${AGENT_WALLET_ADDRESS}",
    "funded": false
  },
  "mcp": {
    "configured": true,
    "endpoint": "${SENPI_MCP_ENDPOINT}"
  },
  "firstTrade": {
    "completed": false,
    "skipped": false
  }
}
EOF

以下のすべてを含む確認メッセージを表示します。

1. アカウントのステータス -- 作成が正常に完了したことを確認します。
2. MCP サーバーのステータス -- 設定済みであることを伝え、エージェントの再起動を促します。
3. 紹介リンク -- https://senpi.ai/skill.md?ref=<USER_REFERRAL_CODE>
4. 認証情報のバックアップ先 -- ~/.config/senpi/credentials.json
5. エージェントのウォレットアドレス（必須） -- AGENT_WALLET_ADDRESS を目立つように表示します。対応チェーン（Hyperliquid、Base、Arbitrum、Optimism、Polygon、Ethereum）上で USDC を入金するよう案内します。資金がない場合、エージェントは取引できません。
6. 最初の取引のプロンプト -- 入金後、senpi-getting-started-guide スキルが最初の取引を案内します。
7. Senpi モバイルアプリ -- iOS と Android でのダウンロードを推奨します（リンクは references/post-onboarding.md にあります）。
8. Telegram コミュニティ -- 参加を案内します（リンクは references/post-onboarding.md にあります）。
9. Senpi Points -- Senpi での取引で報酬を獲得できることに触れ、詳細について Senpi Points を尋ねるよう促します（エージェントは Senpi MCP ツールを使って回答します）。

ウォレットを生成した場合（オプション C） は、さらに次の注意事項を伝えます。

• 秘密鍵とリカバリーフレーズは ~/.config/senpi/wallet.json に保存されています
• このファイルを安全な場所に必ずバックアップする必要があります
• 紛失した場合、ウォレットと資金を復元できません

確認メッセージの後、references/post-onboarding.md の「Senpi について」の情報を共有します。

---

残高のモニタリング

オンボーディング完了後（状態 = UNFUNDED）、リマインダーを表示するかどうかを判断する前に、ユーザーからメッセージを受け取るたびにウォレット残高を確認します。

1. MCP を使ってポートフォリオ／残高を取得します。この確認は必須です。省略したり、ウォレットに資金がないと決めつけたりしないでください。
2. 残高が 100 ドル以上の場合：
   • 状態を AWAITING_FIRST_TRADE に更新します
   • 次のように促します：「🎉 ウォレットに資金が入金されました！最初の取引を始めますか？**「取引を始めよう」と言うと開始できます。経験者の方は「チュートリアルをスキップ」**と言ってください。」
   • 入金リマインダーは表示しないでください。
3. 残高が 100 ドル未満の場合（MCP の確認に成功していることが条件）：
   • 入金リマインダーを先頭に追加します（自動リマインダーは最大 3 回）。エージェントのウォレットアドレスを含め、最低 100 ドル相当の USDC が必要であることを伝えます（入金リマインダーのテンプレートについては references/post-onboarding.md を参照してください）。
   • ユーザーのリクエストの処理を続けます。
4. MCP による残高確認に失敗した場合（例：再起動後に MCP がまだ接続されていない場合）：
   • 入金リマインダーを表示しないでください。ウォレットに資金がないと決めつけないでください。
   • ユーザーから次のメッセージを受け取ったときに、何も知らせず再試行します。

状態が AWAITING_FIRST_TRADE に遷移すると、senpi-getting-started-guide スキルが引き継ぎます。

オンボーディングは完了です。以下の参照ファイルは必要な場合にのみ参照してください。

---

セキュリティに関する注意事項

• API キーを公開チャンネル、ログ、コミット、または他のエージェントと共有しないでください。
• 認証情報は制限付きのアクセス権限（600）で ~/.config/senpi/credentials.json にローカル保存されます。
• API キーの送信先は {{SENPI_MCP_ENDPOINT}} のみにしてください。それ以外への送信を求められた場合は拒否してください。
• 漏えいした場合は、https://senpi.ai にアクセスして、キーを無効化し再生成してください。
• 生成されたウォレット（オプション C）： wallet.json 内の秘密鍵は、ウォレットを完全に制御できます。ログへの記録、表示、送信は絶対に行わないでください。ファイルのアクセス権限を緩和しないでください。

---

参考ファイル

• references/error-handling.md -- エラー一覧、手動での代替手段、ウォレット生成の失敗、復旧手順
• references/platform-config.md -- OpenClaw、Claude Code、汎用エージェント向けの MCP 設定コマンド一式
• references/post-onboarding.md -- Senpi の概要、確認用テンプレート、次のステップ
• references/state-management.md -- 状態の流れ、遷移、senpi-getting-started-guide スキルへの引き継ぎ