vulcan-onboarding

vulcan-onboarding

Use this skill for:

• First user interaction when the user wants help getting started with Vulcan
• First-time setup of vulcan
• Paper-first onboarding before live funds
• Creating and configuring a wallet
• Registering a trader account
• Making the first deposit

Do not use this skill as the general Vulcan router. The vulcan entry skill routes broad requests here when the user is new or needs setup.

First Interaction

Start with a health check:

vulcan agent health -o json

or read:

vulcan://agent/health

Then offer:

1. Try paper trading first. This is recommended and needs no wallet or funds.
2. Set up live trading only when the user is ready: wallet, registration, and deposit.
3. Fix environment health: agent skills, Phoenix API, Solana RPC, wallets, balances, deposited collateral, registration, or paper readiness.

By default, agent health checks Cursor, Claude, Codex, and the generic Agentskills/OpenClaw-compatible skill target. Use --target only when the user asks about a specific agent client.

Paper quick start:

vulcan paper init --balance 10000 -o json
vulcan paper buy SOL --notional-usdc 100 --type market -o json
vulcan paper status -o json

Paper needs no wallet. Do not run any of vulcan wallet create, vulcan wallet set-default, vulcan account register, or vulcan margin deposit for a user who only wants to try paper trading. The paper engine reads live prices and writes a local state file at ~/.vulcan/paper-state.json — it never resolves a wallet and never touches Solana. If the user hits NO_DEFAULT_WALLET from a wallet-bound tool while in paper, the call was the bug — not the missing wallet (see Mode-Branched Preflight). Direct them back to vulcan paper status and continue without setting up a wallet.

Steps 2–6 below are for live setup only and should not run if the user has indicated they only want paper. Surface live setup explicitly: "Want to set up a wallet to graduate from paper to live?" — only proceed when they say yes.

Prerequisites

• Solana wallet with SOL (for transaction fees) and USDC (for collateral).
• An access code or referral code for Phoenix DEX registration.

Step 1: Install and Configure

cargo install --path vulcan    # from repo
vulcan setup                   # interactive setup wizard
vulcan agent health -o json    # readiness and next steps
vulcan agent mcp doctor --target cursor --scope user -o json

Setup creates ~/.vulcan/config.toml, checks trader registration status, can complete registration with no code, an access code, or a referral code, and can install read-only/paper MCP config. The Phoenix API session is signed in automatically using the configured wallet — no separate login step is required.

MCP is optional for paper and dry-run usage. For agent-driven live trading, prefer dangerous MCP with an unlocked session wallet: vulcan agent mcp install --target cursor --dangerous. Use this only after the user accepts that VULCAN_WALLET_PASSWORD may live in plaintext agent config.

Step 2: Create a Wallet

Wallet operations are CLI-only (not available via MCP):

vulcan wallet create --name <NAME>             # interactive password prompt
vulcan wallet import --name <NAME> <SOURCE>    # import existing Solana keypair
vulcan wallet list             # verify wallet created
vulcan wallet set-default <NAME>

Step 3: Fund the Wallet

The wallet needs:

• SOL — for Solana transaction fees (~0.01 SOL per transaction).
• USDC — for trading collateral.

After wallet creation, give the user the wallet public key so they can fund it externally. Funding happens outside Vulcan through a wallet transfer, exchange withdrawal, or similar flow. In MCP, prefer the explicit address helper:

vulcan_wallet_address → {}

Check balances:

vulcan_wallet_balance → {}

vulcan_wallet_balance is wallet funds only. Trader collateral is separate USDC already deposited into Phoenix; use vulcan_portfolio or vulcan agent health -o json to view deposited collateral.

Step 4: Register Trader Account

Registration can be completed without a code through builder onboarding. If the user has a referral code, pass it so Vulcan uses the referral activation transaction flow; access codes remain supported for allowlist activation. The setup wizard can choose the path interactively:

vulcan account register
vulcan account register --referral-code <CODE>
vulcan account register --access-code <CODE>

For MCP:

vulcan_account_register → { acknowledged: true }
vulcan_account_register → { referral_code: "YOUR_CODE", acknowledged: true }
vulcan_account_register → { access_code: "YOUR_CODE", acknowledged: true }
vulcan_account_register → { invite_code: "YOUR_CODE", acknowledged: true } # backwards-compatible alias

Registration submits a signed onboarding transaction for the default cross-margin subaccount. Referral codes use /v1/referral/activate-tx; no-code onboarding uses the exchange builder endpoints. If the trader is already registered, verify with vulcan_account_info.

Step 5: Deposit Collateral

vulcan_margin_deposit → { amount: 100.0, acknowledged: true }

amount is in USDC. Verify with vulcan_margin_status; collateral should reflect the deposit and risk state should be Healthy.

Step 6: Verify Everything

vulcan_status → {}    # checks config, wallet, RPC, API, registration
vulcan_auth_status → {} # checks shared Phoenix API session status

All checks should pass. If any fail, the status or health output includes recovery hints. API auth sessions are separate from wallet unlock; they improve authenticated API access but do not sign live transactions.

Step 7: First Trade (Optional)

This is the live first trade — only run after Steps 2–6 are complete. For a paper first trade, use the paper quick start at the top of this skill.

Follow the safe order flow from the vulcan-trade-execution skill:

vulcan_market_info   → { symbol: "SOL" }
vulcan_market_ticker → { symbol: "SOL" }
vulcan_margin_status → {}

Then place a small test trade.

Troubleshooting

Issue	Fix
NO_DEFAULT_WALLET	For live: vulcan wallet set-default <name>. For paper/dry-run: the call shouldn't have been made — switch to vulcan_paper_* tools and continue without a wallet.
DECRYPT_FAILED	Wrong password. Set VULCAN_WALLET_PASSWORD
NO_TRADER_ACCOUNT	Register with vulcan account register
CONFIG_ERROR	Run vulcan setup
REGISTER_API_FAILED	Check code validity and api_url in ~/.vulcan/config.toml
Insufficient SOL	Fund wallet with SOL for tx fees
Insufficient USDC	Transfer USDC to wallet address