How ZapBot Works

1. Receive user query + metadata.accountInfo[]
2. Build prompt context (sanitized metadata)
3. Generate model output with automatic tool calling
4. Execute tools through SDKTool wrapper
5. Handle interactive confirmations if needed
6. Return finalText + chainId + step trace



## NLP stages in detail

### 1. Tokenization & normalization

Raw input is lowercased, whitespace-normalized, and split into tokens. Shorthand like `"half my ETH"` or `"max USDC"` is expanded to resolvable quantities before entity extraction.

### 2. Intent classification

The engine identifies the primary action class:

| Class | Trigger words |
|---|---|
| Swap | swap, exchange, trade, convert |
| Bridge | bridge, move, transfer cross-chain, send to |
| Zap | zap, deposit into, LP, provide liquidity |
| Query | balance, price, show, what is, how much |
| Schedule | every, recurring, daily, at midnight |

### 3. Entity extraction

Entities extracted per intent:

| Entity | Resolved via |
|---|---|
| Token symbol | on-chain registry + alias list |
| Token address | direct match or ENS resolution |
| Amount | numeric parse + `max`/`half`/`all` expansion |
| Source chain | chain name → chain ID mapping |
| Destination chain | same as above |
| Wallet address | `0x...` detection or session-scoped default |

### 4. Ambiguity resolution

When entities are ambiguous the engine applies a priority order:

1. Explicit session metadata (wallet, connected chain)
2. Prior turn context (stable `sessionId`)
3. Statistical defaults (e.g. native ETH before WETH on mainnet)
4. Clarifying question to user if still unresolved

## Example flow

For: `Swap 100 USDC to WETH on Arbitrum`

```text
1. TokenAddressTool -> resolve symbols
2. BalanceTool -> verify funds
3. ZapCallDataGeneratorTool -> build and cache session route
4. PerformZapTool -> waits for confirmation, then executes
5. Return execution summary + explorer-style link

await sdk.ask({
  userQuery: "...",
  metadata: {
    accountInfo: [{ blockchain: "evm", chain: "1", user_account: "0xabc..." }],
  },
  onStep: (step) => {
    console.log(step.toolName ?? step.type);
  },
});