Authentication

How It Works

StarkFi uses Privy for authentication. When you sign in with your email, a Starknet smart contract wallet (ArgentX v0.5.0) is automatically created and managed for you — no browser extension or seed phrase required.

Step 1 — Request OTP

starkfi auth login you@email.com

A one-time password (OTP) is sent to your email address.

Step 2 — Verify OTP

starkfi auth verify you@email.com 123456

Replace 123456 with the code from your email. On success, your wallet is connected and your session is saved locally.

✓ Wallet connected
  network:  mainnet
  address:  0x04a3...abcd
  walletId: wallet_abc123
  message:  New wallet created and session saved.

First time? If this is a new wallet, fund it with some ETH or STRK — or enable gasfree mode to transact without holding any gas tokens.

Check Your Status

# Show wallet address and network
starkfi address

# Full status check (auth + Fibrous API health)
starkfi status

Sign Out

starkfi auth logout

Clears your stored session. You'll need to re-authenticate to use any commands.

Session Details

Sessions are stored at ~/.local/share/starkfi/session.json (XDG-compliant).

Property	Description
Persistence	Survives terminal restarts — no need to re-login each time
Format	JWT-based with automatic expiry detection
Expiry Buffer	5-minute buffer before JWT expires to prevent mid-request failures
Auto-Cleanup	Expired sessions are automatically cleared

What the Session Contains

Field	Purpose
`userId`	Privy user identifier
`walletId`	Embedded wallet identifier
`address`	Your Starknet contract address
`publicKey`	Wallet public key for signing
`token`	JWT for authenticating API requests
`serverUrl`	Signing server endpoint
`network`	`mainnet` or `sepolia`

Authentication Flow

You (CLI)
  │
  ├─ auth login you@email.com
  │     └→ StarkFi Server (Hono) → Privy API → sends OTP email
  │
  └─ auth verify you@email.com 123456
        └→ StarkFi Server → Privy API → creates/retrieves wallet
                                          │
                                    Returns JWT + wallet info
                                          │
                              CLI saves session.json locally

Next Step

After authenticating, head to the Quick Start to make your first trade.

On this page