Webacy SDK CLI Reference

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

webacy --api-key your-api-key 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

Flag	Description
`--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-pretty`	Force 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

Group	Subcommands	`--chain` semantics
`addresses`	`analyze`, `check-sanctioned`, `check-poisoning`, `quick-profile`¹, `summary`	optional (uses `defaultChain` if set)
`contracts`	`analyze`, `source-code`, `taxes`, `analyze-solidity`, `code-analysis`, `audits`, `by-symbol`	optional (`by-symbol` is chain-agnostic)
`url`	`check`, `add`	chain-agnostic
`wallets`	`transactions`, `approvals`	optional
`ledger`	`scan-transaction`, `scan-eip712`	chain ID lives in the JSON body; global `--chain` is ignored
`account-trace`	`trace`	optional
`usage`	`current`, `history`, `plans`, `max-rps`	chain-agnostic
`transactions`	`analyze`²	optional
`scan`	`transaction`, `eip712`, `start-risk-scan`, `risk-scan-status`	chain ID lives in the JSON body for `transaction`/`eip712`
`batch`	`addresses`, `contracts`, `transactions`	required
`rwa`	`list`, `get`	optional
`vaults`	`list`, `list-cursor`, `get`, `list-events`, `list-events-for-address`	required 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

Group	Subcommands	`--chain` semantics
`holder-analysis`	`get`	optional
`trading-lite`	`analyze`	Solana only (default when omitted)
`tokens`	`pools`, `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

Getting Started

Guides & Walkthroughs

Risk Ratings, Scoring, and Documentation

SDK

Integrations

Essentials

Glossary

Webacy SDK CLI Reference

Installation

Authentication

Command structure

Global options

Output

Batch and JSON inputs

Input validation

Command reference

Threat

Trading

Examples

Investigate a suspicious address

Vet a new Solana token

Check current API quota

Debugging

Error handling

Next steps

SDK Installation

ThreatClient

TradingClient

Error Handling

​Installation

​Authentication

​Command structure

​Global options

​Output

​Batch and JSON inputs

​Input validation

​Command reference

​Threat

​Trading

​Examples

​Investigate a suspicious address

​Vet a new Solana token

​Check current API quota

​Stream trending tokens and flag high-risk ones

​Debugging

​Error handling

​Next steps

SDK Installation

ThreatClient

TradingClient

Error Handling

Installation

Authentication

Command structure

Global options

Output

Batch and JSON inputs

Input validation

Command reference

Threat

Trading

Examples

Investigate a suspicious address

Vet a new Solana token

Check current API quota

Stream trending tokens and flag high-risk ones

Debugging

Error handling

Next steps