> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webacy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webacy SDK CLI Reference

> Use the webacy CLI to call every ThreatClient and TradingClient method from your terminal, pipe JSON into scripts, and automate security checks in CI.

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

```bash theme={null}
npm install -g @webacy-xyz/cli
```

Verify the install:

```bash theme={null}
webacy --version
```

<Tip>
  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.
</Tip>

## Authentication

Set your API key via environment variable (recommended) or the `--api-key` flag:

<CodeGroup>
  ```bash env var theme={null}
  export WEBACY_API_KEY=your-api-key
  webacy addresses analyze 0x... --chain eth
  ```

  ```bash flag theme={null}
  webacy --api-key your-api-key addresses analyze 0x... --chain eth
  ```
</CodeGroup>

Without a key, commands fail fast before making any HTTP request:

```text theme={null}
AuthenticationError: API key is required. Provide --api-key or set WEBACY_API_KEY.
```

<Warning>
  Never commit your API key to version control. Prefer `WEBACY_API_KEY` in a shell profile or a secrets manager for CI.
</Warning>

## Command structure

Every command follows the same shape:

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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):

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
webacy usage current --pretty
```

### Stream trending tokens and flag high-risk ones

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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`:

```bash theme={null}
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](/sdk/error-handling) for the full list and how to recover from each.

## Next steps

<CardGroup cols={2}>
  <Card title="SDK Installation" icon="download" href="/sdk/installation">
    Use the SDK directly in your TypeScript code
  </Card>

  <Card title="ThreatClient" icon="shield" href="/sdk/threat-client">
    Full method reference for threat analysis
  </Card>

  <Card title="TradingClient" icon="chart-line" href="/sdk/trading-client">
    Full method reference for trading analysis
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/sdk/error-handling">
    Typed errors and recovery strategies
  </Card>
</CardGroup>