Authenticate Wallet

Manage authentication sessions for the StarkFi CLI. StarkFi uses a remote Auth Server with Privy TEE for email-based one-time password (OTP) authentication. A valid session is required before any transactional skill can operate.

Prerequisites

• The StarkFi Auth Server (starkfi-server) must be running and accessible.
• An email address the user has access to (for receiving OTP codes).

Authentication Flow

The login process is a two-step OTP flow:

1. Initiate — auth login <email> sends an OTP code to the email.
2. Verify — auth verify <email> <code> completes authentication.

The agent CANNOT guess or auto-fill the OTP code — it must wait for the user to provide it after checking their email.

Rules

1. ALWAYS run npx starkfi@latest status first to check if the user already has an active session. If they do, skip the login flow — just inform them.
2. After auth login, you MUST wait for the user to provide their OTP code. Do NOT ask more than once; just say you're waiting.
3. After auth verify, you MUST run npx starkfi@latest status to confirm the session is active.
4. deploy is idempotent — it's safe to run multiple times. It deploys the smart account contract on-chain if not already deployed.
5. If any other skill reports Not authenticated, direct the user to this skill.

Commands

# Step 1: Send OTP to email
npx starkfi@latest auth login <email>

# Step 2: Verify OTP code
npx starkfi@latest auth verify <email> <code>

# Check session status
npx starkfi@latest status

# Display wallet address
npx starkfi@latest address

# Deploy smart account on-chain
npx starkfi@latest deploy

# End session
npx starkfi@latest auth logout

Parameters

Parameter	Type	Description	Required
email	string	User's email address	Yes
code	string	One-time password from email	Yes

Examples

User: "Log me in with user@example.com"

npx starkfi@latest status
# If not authenticated:
npx starkfi@latest auth login user@example.com
# Wait for user to provide OTP code (e.g. "123456")
npx starkfi@latest auth verify user@example.com 123456
npx starkfi@latest status

User: "What's my wallet address?"

npx starkfi@latest address

User: "Deploy my account"

npx starkfi@latest deploy

User: "Log me out"

npx starkfi@latest auth logout

Error Handling

Error	Action
Invalid OTP code	Ask the user to check their email and retry auth verify.
Session expired	Restart from auth login.
Server unreachable	Ensure starkfi-server is running at the configured URL.
Rate limit	Wait 60 seconds before retrying.
Deployment failed	Check balance — send ETH/STRK to the address, or enable gasfree mode first.
Insufficient balance	For deploy: npx starkfi@latest config set-gasfree on to bypass gas costs.

Related Skills

• All other skills depend on this skill — if any reports Not authenticated, use this.
• Use config to enable gasfree mode if the user can't afford deployment gas.