npm package: @narval-xyz/litewallet-cli
Description: Litewallet — wallet control plane for AI Agents
Latest version: 0.0.10

# Litewallet CLI

Litewallet CLI is a client for operating all your accounts through litewallet.

## Overview

- Configure once, then reuse stored credentials across commands
- Authenticate with granular delegated access to your accounts
- Transfer tokens, sign messages, or send any defi transaction, routed to your connected wallet
- Clear Sign approval of your transactions. See understandable intent before signing
- Watch transaction statuses or signature requests until completion

## Installation

**Requirements:** Node.js 18+

```bash
npm install -g @narval-xyz/litewallet-cli
```

Update to the latest version with `npm update -g @narval-xyz/litewallet-cli`.

## Security Notes

- `litewallet auth` generates a session private key stored in config under `auth.privateKey`
- API requests are authenticated with a granular access token & jwsd signature over the request
- Access permissions are evaluated within a TEE (enclave)
- Tokens are short-lived; when expired, refresh it with `litewallet auth rotate`

## Commands Reference

- Configuration: `litewallet config get`
- Authentication: `litewallet auth`, `litewallet auth rotate`, `litewallet auth revoke`
- Accounts: `litewallet account list`, `litewallet account switch <index>`
- Networks: `litewallet network list`
- Balance: `litewallet balance list`
- Transactions: `litewallet transfer [--dry-run]`, `litewallet send`, `litewallet fetch [--watch]`, `litewallet personal-sign`, `litewallet sign-typed-data`, `litewallet decode`
- Yield: `litewallet yield list`, `litewallet yield deposit [--dry-run]`, `litewallet yield withdraw [--dry-run]`
- Trading: `litewallet swap [--dry-run]`, `litewallet bridge [--dry-run]`, `litewallet quote`
- Token Approvals: `litewallet approve [--dry-run]`
  Use `--help` with any command for full options and examples, e.g. `litewallet approve --help`.

## Quick Start

**NOTE: config, including auth tokens & keys, are stored in plaintext in `~/.litewallet/`**

1. **Set config for your env**

   ```bash
   litewallet config reset --env sandbox
   ```

   Use `--verbose` to surface validation warnings, such as unknown keys.

2. **Authenticate**

   ```bash
   litewallet auth
   ```

   The CLI stores the resulting access token, and session key in your config.

3. **Send your first transaction**

   ```bash
   litewallet transfer usdc \
    --amount 10 \
    --to 0xB537cee86bD7Fc55dDf9fAbA548d0813fc30E668 \
    --watch
   ```

   <details>
     <summary>Example output</summary>

   ```
   Watching for transaction completion...
   Transaction completed after 10000ms:
   {
     "data": {
       "id": "lwt_019a024b-506b-7720-8e5c-2b6582a1d41c",
       "accountId": "lwac_019a0243-234e-7278-89d9-d8d93d90ae42",
       "networkId": "ETHEREUM",
       "idempotenceId": "approve-1760975081137-qaq9bl",
       "action": "eth_sendTransaction",
       "status": "completed",
       "subStatus": "mined",
       "createdAt": "2025-10-20T15:44:41.580Z",
       "transaction": {
         "chainId": "0x1",
         "from": "0x37ccf6a93eb78620f70dfd665163ac7040647d34",
         "to": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
         "value": "0x0",
         "data": "0x095ea7b300000000000000000000000087870Bca3F3fD6335C3F4ce8392D69350B4fA4E20000000000000000000000000000000000000000000000000000000001000000",
         "nonce": 35,
         "gas": "0xdc11",
         "maxFeePerGas": "0xd426549",
         "maxPriorityFeePerGas": "0xc1bb2e",
         "type": 2,
         "hash": "0x1541117f597f22b62b7ed9b0a8b9269fb435bd488cc43b22c708ffe075b49b7c",
         "r": "88732545801986374681409007107815430851895936838749698496157457826114942486857",
         "s": "26961740936934588523581281704462131659757981729028568690266240975873451655929",
         "status": "0x1",
         "gasUsed": "0xd8ee",
         "effectiveGasPrice": "0xb2cf39a",
         "cumulativeGasUsed": "0xf1b360"
       }
     }
   }
   ```

   </details>

4. **Personal sign**

   ```bash
   litewallet personal-sign --message 'hello world' --verbose | litewallet fetch --watch
   ```

   <details>
     <summary>Example output</summary>

   ```
   Sending personal sign request {
     "url": "http://provider.xyz/v1/transactions",
     "method": "POST",
     "headers": {
       "Content-Type": "application/json",
       "authorization": "Bearer lw_cd796fed5b831eed9b9c5c3d15be3764",
       "detached-jws": "eyJhbGciOiJFRERTQSIsImF0aCI6Ilc5QjdvbXh1YVppMWNnY2Uyc0VuT0IxYmpQWUdZM0t5V0cyelpMa1RPNHMiLCJjcmVhdGVkIjoxNzYxMDM2NDcxLCJodG0iOiJQT1NUIiwia2lkIjoiMHg2OGJjNjA5OGFhODE5MjBkZTkwZGQyYTFhZmJmOTY2YjZjMTk0MDhmMDk0N2QxZjk4MWVkNzgzNmFhNTQyNjRlIiwidHlwIjoiZ25hcC1iaW5kaW5nLWp3c2QiLCJ1cmkiOiJodHRwOi8vbG9jYWxob3N0OjMwMDUvdjEvbGl0ZXdhbGxldC9haWl6emkvdHJhbnNhY3Rpb25zIn0..Ja1tKJfc1ipLumDfRWZF0Xjf3dNFGkNuOCa3ug2F4wZPEq9cjMljW4eJ1oIiCauTnobaKmeDW1dcDi3N3yDkDg"
     },
     "body": "{\"idempotenceId\":\"7f2d0174-bca5-4b7e-b107-ad2db536a364\",\"request\":{\"method\":\"personal_sign\",\"params\":[\"0x68656c6c6f20776f726c64\",\"0x3AFEAf648A81aE82e79A0f26B24D46C93B31511B\"]}}"
   }
   Making POST request to http://provider.xyz/transactions
   {
     "data": {
       "id": "lwt_019a05f4-0d2a-7784-ad5a-7c31db6638a4",
       "accountId": "lwac_0199f2c5-6807-7255-90ff-1ea527a435c5",
       "idempotenceId": "7f2d0174-bca5-4b7e-b107-ad2db536a364",
       "action": "personal_sign",
       "status": "created",
       "subStatus": "signing",
       "initiatedBy": "b599434a-bd9e-4551-bcaf-b1d2d96b2a7e",
       "createdAt": "2025-10-21T08:47:51.595Z",
       "payload": {
         "from": "0x3AFEAf648A81aE82e79A0f26B24D46C93B31511B",
         "message": "0x68656c6c6f20776f726c64"
       }
     }
   }
   Watching for transaction completion...
   Transaction completed after 1000ms:
   {
     "data": {
       "id": "lwt_019a05f4-0d2a-7784-ad5a-7c31db6638a4",
       "accountId": "lwac_0199f2c5-6807-7255-90ff-1ea527a435c5",
       "idempotenceId": "7f2d0174-bca5-4b7e-b107-ad2db536a364",
       "action": "personal_sign",
       "status": "completed",
       "subStatus": "signed",
       "initiatedBy": "b599434a-bd9e-4551-bcaf-b1d2d96b2a7e",
       "createdAt": "2025-10-21T08:47:51.595Z",
       "payload": {
         "from": "0x3AFEAf648A81aE82e79A0f26B24D46C93B31511B",
         "message": "0x68656c6c6f20776f726c64",
         "signature": "0x5be91a2a85c8df51b0e7ee4a7607d820955b9cda327b57f947b44cffd76592c201436abd264aa38b0f487e465876a9d7a6511b5e0d0ea8778340fa7885ad41cc1c"
       }
     }
   }
   ```

   </details>

## Configuration

### CLI helpers

- `litewallet config get` – view the full configuration
- `litewallet config reset --env <sandbox | production>` - reset config to a default state
- `litewallet auth` - authenticate & connect accounts
- add `--help` to any command to see options

### Configuration file location

By default the CLI stores configuration at `~/.litewallet/config.json`. Set `NARVAL_CONFIG_DIR` to override the directory, for example when running in CI or on shared hosts.

### Schema reference

| Section     | Field         | Description                                    |
| ----------- | ------------- | ---------------------------------------------- |
| **baseUrl** |               | Base URL for Litewallet API                    |
| **auth**    | `url`         | GNAP grant authentication base URL             |
|             | `accessToken` | Full access token response from authentication |
|             | `privateKey`  | Session private key used to sign requests      |
|             | `grantAccess` | Default grant access configuration array       |
| **account** | `address`     | Default account address                        |
|             | `network`     | Default network (optional)                     |
|             | `label`       | Default account label                          |

## Authentication & Access Token Management

- `litewallet auth` starts the interactive auth flow against `auth.url` and saves credentials
  - `litewallet auth init` starts auth non-interactively — returns a JSON redirect URL and exits immediately. Useful for scripts, CI, or agent integrations.
  - `litewallet auth check` polls for auth completion after the user visits the redirect URL from `auth init`. Returns `pending`, `completed`, or `error`.
- `litewallet auth rotate` refreshes the access token using the management token
- `litewallet auth revoke` revokes access tokens and clears credentials from config

## Accounts

List connected accounts, switch current account.

```bash
# List all connected accounts/networks
litewallet account list

# Switch current account
litewallet switch <index>
```

Check balances

```bash
# List token balances on current account, for all networks
litewallet balance list

# List token balances on all accounts
litewallet balance list --all-accounts

# Filter to Ethereum mainnet only, current account only
litewallet balance list --chain ethereum


| Option                | Description                                                                            |
| --------------------- | -------------------------------------------------------------------------------------- |
| `--chain <chain>`     | Filter by chain (ethereum, base, arbitrum, polygon, sepolia, baseSepolia, or chain ID) |
| `--token <token>`     | Filter by token symbol (e.g. USDC) or contract address                                 |
| `--address <address>` | Filter by wallet address (default: current account)                                    |
| `--all-accounts`      | Query all accounts                                                                     |
| `--all-chains`        | Show balances across all chains for the current account                                |
| `--no-prices`         | Skip USD price enrichment (faster)                                                     |
| `--json`              | Output full JSON with all metadata                                                     |

```

## Transactions

### Transfer (one-step)

Craft and send a token transfer in a single command. Combines `craft-transfer` + `send` into one flow.

```bash
# Transfer USDC (human-readable amount)
litewallet transfer usdc --amount 10.5 --to 0xRecipientAddress

# Transfer ETH
litewallet transfer eth --amount 0.01 --to 0xRecipientAddress

# Transfer with raw amount (smallest unit)
litewallet transfer usdc --amount-raw 10500000 --to 0xRecipientAddress

# Transfer by token contract address
litewallet transfer --token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --amount 10 --to 0xRecipientAddress

# Dry run (print crafted transaction without sending)
litewallet transfer usdc --amount 10.5 --to 0xRecipientAddress --dry-run

# Add an internal memo
litewallet transfer usdc --amount 10.5 --to 0xRecipientAddress --memo "Payment for invoice #42"

# Watch until transaction completes
litewallet transfer usdc --amount 10.5 --to 0xRecipientAddress --watch

# Watch with custom timeout
litewallet transfer usdc --amount 10.5 --to 0xRecipientAddress --watch --timeout 60000
```

### Personal Sign

```bash
litewallet personal-sign --message 'hello world' | litewallet fetch --watch
```

### Sign Typed Data (EIP-712)

Sign EIP-712 typed data via `eth_signTypedData_v4`. Accepts typed data JSON from stdin or a file.

```bash
# Pipe JSON via stdin
echo '{"types":{"EIP712Domain":[{"name":"name","type":"string"}],"Mail":[{"name":"contents","type":"string"}]},"primaryType":"Mail","domain":{"name":"Example"},"message":{"contents":"Hello"}}' \
  | litewallet sign-typed-data

# From a file
litewallet sign-typed-data --file typed-data.json

# Pipe from file and watch for completion
cat typed-data.json | litewallet sign-typed-data | litewallet fetch --watch
```

### Send and fetch

- `litewallet send` initiates a requests to be signed/broadcast
- `litewallet fetch <tx_id> --watch ` polls until a transaction completes
- Compose commands with pipes (`|`) to craft → send → watch in one flow

### Decode (Evaluate)

Decode a transaction or signing request before submitting. Returns Clear Sign output (human-readable intent, decoded parameters, protocol identification, and optional policy evaluation).

```bash
# Full JSONRPC request (detected automatically by "method" field)
litewallet decode '{"method":"eth_sendTransaction","params":[{"from":"0x...","to":"0x...","value":"0x0","data":"0x...","chainId":"0x1"}]}'

# Raw TX data (wrapped as eth_sendTransaction)
litewallet decode '{"from":"0x...","to":"0x...","value":"0x0","data":"0x095ea7b3...","chainId":"0x1"}'

# Personal sign
litewallet decode --data 'hello world' --action personal-sign

# Typed data from file
litewallet decode --action sign-typed-data --file typed-data.json

# Pipe JSON via stdin
cat request.json | litewallet decode
```

## Yield

List, deposit into, and withdraw from yield vaults (Aave, Morpho, etc.). All mutating commands return immediately with a transaction ID — use `litewallet fetch <tx-id>` to check completion. Use `--dry-run` to preview the transaction before sending.

```bash
# List available vaults
litewallet yield list
litewallet yield list --chain base --asset USDC
litewallet yield list --protocol morpho

# Deposit into a vault
litewallet yield deposit --target 0xVaultAddress --asset USDC --amount 100 --chain base

# Dry run (preview without submitting)
litewallet yield deposit --target 0xVaultAddress --asset USDC --amount 100 --chain base --dry-run

# Withdraw from a vault
litewallet yield withdraw --target 0xVaultAddress --asset USDC --amount max --chain base
litewallet yield withdraw --target 0xVaultAddress --asset USDC --amount 50 --chain base
```

## Swap

Swap tokens on the same chain.

```bash
# Swap USDC for WETH on Base
litewallet swap --from USDC --to WETH --amount 100 --chain base

# Dry run
litewallet swap --from USDC --to WETH --amount 100 --chain base --dry-run

# Using token addresses
litewallet swap --from 0x833589... --to 0x4200... --amount-raw 100000000 --chain base
```

## Quote

Get a swap or bridge quote without submitting a transaction.

```bash
# Same-chain swap quote
litewallet quote --from USDC --to WETH --to-chain base --amount 100

# Cross-chain bridge quote
litewallet quote --from USDC --to USDC --from-chain ethereum --to-chain base --amount 100
```

## Bridge

Bridge tokens cross-chain.

```bash
# Bridge USDC from Ethereum to Base
litewallet bridge --from USDC --to USDC --from-chain ethereum --to-chain base --amount 100

# Dry run
litewallet bridge --from USDC --to USDC --to-chain base --amount 100 --dry-run

# Restrict to specific bridge protocol
litewallet bridge --from USDC --to USDC --to-chain base --amount 100 --allow-bridges across
```

## Approve

Approve ERC-20 token spending for a spender address.

```bash
litewallet approve --token USDC --spender 0xSpenderAddress --amount 1000 --chain base
litewallet approve --token 0x833589... --spender 0x... --amount-raw 1000000000

# Dry run (preview without submitting)
litewallet approve --token USDC --spender 0xSpenderAddress --amount 1000 --chain base --dry-run
```

## Troubleshooting

- Use `--verbose` to display validation warnings and HTTP details
- Use `litewallet account list` to ensure you're on the desired account/network