Skip to Content
WaaP for AgentsAgent Patterns

Agent Patterns

How the WaaP CLI works under the hood and patterns for building robust agents.

How It Works

  1. Login — email + password → JWT (no cookies, no browser)
  2. Keyshare — fetched from the keyshare-manager and AES-GCM decrypted with userKey
  3. Signing — 2-party ECDSA (WASM + policy-engine over HTTP)

2FA: Newly created accounts start with Authorization Method set to Disabled. To manage 2FA: waap-cli 2fa status/enable/disable. To bypass 2FA programmatically, pass --permission-token.

Risk Levels

The policy engine assigns a risk level to every signing request. When the highest risk level meets or exceeds the wallet’s Min Risk for 2FA threshold (default: HighWarn), 2FA authorization is required before the signature is released.

LevelWhat it means
OkNo known risk — transaction proceeds without friction
LowWarnMinor risk detected — warning shown but no 2FA
HighWarnSignificant risk — triggers 2FA if Min Risk for 2FA is set to HighWarn (default)
HighWarnButGracefullyRoutine high-risk (e.g., daily spend limit exceeded) — triggers 2FA
BlockExtreme risk — transaction blocked by policy engine

2FA Flow

When the policy engine determines that 2FA is required (i.e., highest_risk >= min_risk_for_2fa):

  1. Policy engine returns WaitForAuthz during signing.
  2. CLI opens a WebSocket connection to /listen-authz/{method}/{payloadId}/{jwt}.
  3. For email: a verification link is sent — CLI waits for the user to click it.
  4. For phone: an OTP is sent via SMS — CLI prompts for the code via stdin.
  5. For wallet: a message is signed on the external hardware wallet.
  6. Timeout: 5 minutes — CLI exits with an error if no authorization is received.

Session Storage

  • Session is saved at ~/.waap-cli/session.json with 0600 permissions (owner read/write only).
  • Contains: token, jwt, userKey, and optionally userId.
  • waap-cli logout deletes this file.

RPC

For eth_getBalance, send-tx, and sign-tx, RPC can be passed with --rpc option flag.

If --rpc is omitted, the CLI auto-resolves a free public RPC:

  1. Fetches the chain list from chainid.network/chains.json.
  2. Caches the result for 24 hours at ~/.waap-cli/chains.json.
  3. Prefers publicnode.com RPCs, then falls back to tatum.io.

Override with --rpc <url> for production reliability — free public RPCs may be rate-limited or unreliable.

CLI CommandsGas Tank