Authenticate Wallet

1---2name: authenticate-wallet3description: Sign in to the wallet. Use when you or the user want to log in, sign in, connect, or set up the wallet, or when any wallet operation fails with authentication or "not signed in" errors. This skill is a prerequisite before sending, trading, or funding.4user-invocable: true5disable-model-invocation: false6allowed-tools: ["Bash(npx awal@2.0.3 status*)", "Bash(npx awal@2.0.3 auth *)", "Bash(npx awal@2.0.3 balance*)", "Bash(npx awal@2.0.3 address*)", "Bash(npx awal@2.0.3 show*)"]7---8 9# Authenticating with the Payments Wallet10 11When the wallet is not signed in (detected via `npx awal status` or when wallet operations fail with authentication errors), use the `npx awal` CLI to authenticate.12 13If you have access to email, you can authenticate the wallet yourself, otherwise you'll need to ask your human to give you an email address and to tell you the OTP code they receive.14 15## Authentication Flow16 17Authentication uses a two-step email OTP process:18 19### Step 1: Initiate login20 21```bash22npx awal@2.0.3 auth login <email>23```24 25This sends a 6-digit verification code to the email and outputs a `flowId`.26 27### Step 2: Verify OTP28 29```bash30npx awal@2.0.3 auth verify <flowId> <otp>31```32 33Use the `flowId` from step 1 and the 6-digit code from the user's email to complete authentication. If you have the ability to access the user's email, you can read the OTP code, or you can ask your human for the code.34 35## Input Validation36 37Before constructing the command, validate all user-provided values to prevent shell injection:38 39- **email**: Must match a standard email format (`^[^\s;|&`]+@[^\s;|&`]+$`). Reject if it contains spaces, semicolons, pipes, backticks, or other shell metacharacters.40- **flowId**: Must be alphanumeric (`^[a-zA-Z0-9_-]+$`).41- **otp**: Must be exactly 6 digits (`^\d{6}$`).42 43Do not pass unvalidated user input into the command.44 45## Checking Authentication Status46 47```bash48npx awal@2.0.3 status49```50 51Displays wallet server health and authentication status including wallet address.52 53## Example Session54 55```bash56# Check current status57npx awal@2.0.3 status58 59# Start login (sends OTP to email)60npx awal@2.0.3 auth login user@example.com61# Output: flowId: abc123...62 63# After user receives code, verify64npx awal@2.0.3 auth verify abc123 12345665 66# Confirm authentication67npx awal@2.0.3 status68```69 70## Available CLI Commands71 72| Command                                      | Purpose                                |73| -------------------------------------------- | -------------------------------------- |74| `npx awal@2.0.3 status`                     | Check server health and auth status    |75| `npx awal@2.0.3 auth login <email>`         | Send OTP code to email, returns flowId |76| `npx awal@2.0.3 auth verify <flowId> <otp>` | Complete authentication with OTP code  |77| `npx awal@2.0.3 balance`                    | Get USDC wallet balance                |78| `npx awal@2.0.3 address`                    | Get wallet address                     |79| `npx awal@2.0.3 show`                       | Open the wallet companion window       |80 81## JSON Output82 83All commands support `--json` for machine-readable output:84 85```bash86npx awal@2.0.3 status --json87npx awal@2.0.3 auth login user@example.com --json88npx awal@2.0.3 auth verify <flowId> <otp> --json89```