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+

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

   litewallet config reset --env sandbox

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

2. Authenticate

   litewallet auth

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

3. Send your first transaction

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

   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"
       }
     }
   }

4. Personal sign

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

   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"
       }
     }
   }

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.

# List all connected accounts/networks
litewallet account list

# Switch current account
litewallet switch <index>

Check balances

# 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.

# 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

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.

# 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).

# 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.

# 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.

# 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.

# 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.

# 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.

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