Skip to main content
The @webacy-xyz/cli package ships a webacy binary that exposes every ThreatClient and TradingClient method as a subcommand. Use it to script security checks, pipe JSON into other tools, or run one-off analyses without writing TypeScript.

​
Installation

npm install -g @webacy-xyz/cli
Verify the install: 
webacy --version
The CLI is a thin wrapper around the SDK. Every subcommand maps 1:1 to an SDK method, so behavior, validation, and errors match exactly.

​
Authentication

Set your API key via environment variable (recommended) or the --api-key flag: 
export WEBACY_API_KEY=your-api-key
webacy addresses analyze 0x... --chain eth
Without a key, commands fail fast before making any HTTP request: 
AuthenticationError: API key is required. Provide --api-key or set WEBACY_API_KEY.
Never commit your API key to version control. Prefer WEBACY_API_KEY in a shell profile or a secrets manager for CI.

​
Command structure

Every command follows the same shape: 
webacy [global options] <group> <subcommand> [positional args] [local options]
  • <group> — a resource namespace (addresses, contracts, tokens, …)
  • <subcommand> — a method on that resource (analyze, check-sanctioned, trending, …)
  • Positional args — typically an address, transaction hash, or token address
  • Local options — method-specific flags (e.g. --depth, --limit, --refresh-cache)
Drill into help at any level: 
webacy --help                          # list all groups
webacy addresses --help                # list subcommands for a group
webacy addresses analyze --help        # flags + usage for a single subcommand

​
Global options

FlagDescription
--api-key <key>API key (falls back to WEBACY_API_KEY)
--base-url <url>Override the API base URL (e.g. staging)
--chain <chain>Default blockchain — applies to any command that accepts a chain
--timeout <ms>Request timeout in milliseconds
--debug [level]Log SDK activity: requests, responses, errors, or all
--pretty / --no-prettyForce pretty or compact JSON (auto-detects TTY by default)
Global flags can appear before or after the subcommand: 
webacy --chain eth addresses analyze 0x...
webacy addresses analyze 0x... --chain eth --pretty
--chain only accepts production chains (eth, sol, base, bsc, pol, arb, opt, ton, sui, stellar, btc, sei). An invalid value is rejected before any request is made.

​
Output

  • stdout — the SDK response as JSON (pretty when the terminal is interactive, compact when piped; --pretty / --no-pretty override)
  • stderr — errors and debug logs
  • exit code — 0 on success, 1 on any error (pipes that close early exit 0 — safe for | head)
This makes the CLI safe to pipe, redirect, and branch on in shell scripts: 
# Extract just the risk score
webacy addresses analyze 0x... --chain eth | jq .overallRisk

# Save a full holder analysis to disk
webacy holder-analysis get <token> --chain sol --pretty > analysis.json

# Fail a CI job if a contract exceeds a risk threshold
SCORE=$(webacy contracts analyze "$CONTRACT" --chain eth | jq -r '.score')
if [ "$SCORE" -gt 70 ]; then
  echo "Contract risk too high: $SCORE"
  exit 1
fi

​
Batch and JSON inputs

Any command that takes a list or request body accepts either a literal value, @./path/to/file.json, or @~/path/to/file.json (tilde expands to your home directory): 
# Comma-separated list
webacy batch addresses 0xabc,0xdef,0x123 --chain eth

# JSON array from a file
echo '["0xabc", "0xdef"]' > addrs.json
webacy batch addresses @addrs.json --chain eth

# JSON body for transaction scans
webacy scan transaction 0xSigner... @./tx-request.json

# Tilde expansion
webacy scan transaction 0xSigner... @~/requests/tx.json
File inputs are capped at 16 MiB and must point at a regular file (directories, FIFOs, and /dev/stdin are rejected).

​
Input validation

Validation happens locally before any HTTP request:
  • --chain — rejected by the parser if not a supported production chain.
  • --modules (addresses analyze) — each entry must be a valid RiskModule value; unknown values surface a ValidationError listing the full allowed set.
  • --tags (rwa list) — each entry must be one of standard, yield, rwa, gold, bridged, vault.
  • Numeric flags (--depth, --limit, --timeout, etc.) — must be integers; 3.9 or 10abc are rejected (no silent truncation).
  • Addresses — validated against chain-specific formats (0x for EVM, base58 for Solana, etc.) before dispatch.
Each failure prints a typed ValidationError + recovery hint and exits 1.

​
Command reference

​
Threat

GroupSubcommands--chain semantics
addressesanalyze, check-sanctioned, check-poisoning, quick-profile¹, summaryoptional (uses defaultChain if set)
contractsanalyze, source-code, taxes, analyze-solidity, code-analysis, audits, by-symboloptional (by-symbol is chain-agnostic)
urlcheck, addchain-agnostic
walletstransactions, approvalsoptional
ledgerscan-transaction, scan-eip712chain ID lives in the JSON body; global --chain is ignored
account-tracetraceoptional
usagecurrent, history, plans, max-rpschain-agnostic
transactionsanalyze²optional
scantransaction, eip712, start-risk-scan, risk-scan-statuschain ID lives in the JSON body for transaction/eip712
batchaddresses, contracts, transactionsrequired
rwalist, getoptional
vaultslist, list-cursor, get, list-events, list-events-for-addressrequired on get and list-events-for-address
¹ addresses quick-profile supports eth, base, bsc, pol, opt, arb, sol only. ² transactions analyze supports eth, base, bsc, pol, opt, arb, sol, stellar only.

​
Trading

GroupSubcommands--chain semantics
holder-analysisgetoptional
trading-liteanalyzeSolana only (default when omitted)
tokenspools, trending, trending-pools, get³, pool-ohlcv³required on get and pool-ohlcv
³ tokens get and tokens pool-ohlcv support eth, base, bsc, pol, opt, arb, sol only. When the global --chain value falls outside a command’s supported subset, the CLI throws a ValidationError locally with the allowed values — no HTTP round-trip. Each subcommand exposes the same options as the corresponding SDK method — run webacy <group> <subcommand> --help to see them.

​
Examples

​
Investigate a suspicious address

webacy --chain eth --pretty addresses analyze 0xSuspect
webacy --chain eth --pretty wallets approvals 0xSuspect
webacy --chain eth --pretty account-trace trace 0xSuspect --depth 2

​
Vet a new Solana token

webacy --chain sol trading-lite analyze <token>
webacy --chain sol tokens pools <token> --pretty
webacy --chain sol holder-analysis get <token> | jq '.sniper_analysis'

​
Check current API quota

webacy usage current --pretty

webacy tokens trending --chain sol --limit 20 \
  | jq '.tokens[] | select(.risk.overallRisk > 50) | {symbol, risk: .risk.overallRisk}'

​
Debugging

Use --debug to see what the SDK is sending and receiving without changing your code: 
webacy --debug all addresses analyze 0x... --chain eth
# [Webacy SDK] HTTP request: GET /addresses/0x...?chain=eth
# [Webacy SDK] HTTP response 200: { ... }
Granular levels: --debug requests, --debug responses, --debug errors. Point at a non-production environment for testing: 
webacy --base-url https://api-development.webacy.com addresses analyze 0x... --chain eth

​
Error handling

The CLI surfaces the SDK’s typed errors with recovery hints on stderr, then exits with code 1: 
webacy addresses analyze not-an-address --chain eth
# ValidationError: Invalid Ethereum address: "not-an-address"...
# Hint: Check your input parameters. Ensure address formats match the specified blockchain.
Common error types:
  • AuthenticationError — missing or invalid API key
  • ValidationError — malformed input (address, chain, required field)
  • RateLimitError — you’ve exceeded your plan’s rate limit
  • NotFoundError — resource doesn’t exist on the given chain
  • NetworkError — timeout or connectivity issue
See Error Handling for the full list and how to recover from each.

​
Next steps

SDK Installation

Use the SDK directly in your TypeScript code

ThreatClient

Full method reference for threat analysis

TradingClient

Full method reference for trading analysis

Error Handling

Typed errors and recovery strategies