llms.txt

# rwa CLI

CLI for trading tokenized stocks & ETFs (Ondo Global Markets) on Solana via Jupiter.
264 tokens: TSLA, AAPL, NVDA, SPY, QQQ, and more.

## Install

Preferred:

```bash
curl -fsSL https://raw.githubusercontent.com/outputlayer/rwa_cli/main/install.sh | sh
```

The installer downloads a pre-built binary from GitHub Releases when available and falls back to building from source.

From source:

```bash
cargo install --git https://github.com/outputlayer/rwa_cli --bin rwa
```

## Critical agent rules

- NEVER run `rwa` wallet-changing commands in parallel processes or with `&`
- For multi-token trading WITHIN a single call, use `--parallel` flag — safe and fast
- Use `sleep 3` between sequential commands only (not needed with built-in parallel flags)
- Always use `--json` for machine-readable output
- Use `-y` only for real execution, not for `--dry-run`
- There is no `quote` command; use `buy/sell --dry-run`
- `send` transfers assets to another wallet; `sell` swaps for USDC
- CLI auto-retries swap failures; do NOT manually retry them

## Commands

### Market info
- `rwa --json gm hours` — current session + tradable count
- `rwa --json gm hours --tradable` — all tokens tradable right now
- `rwa --json gm list` — all tokens with tradable status
- `rwa --json gm search --search <keyword>` — filter by symbol, name, or sector
- `rwa --json gm search --tradable-only --sector <SECTOR> --type <stock|etf> --name-keyword <WORD>` — bulk filtering without Python
- `rwa --json gm tradable [SYM ...]` — tradable lookup for one, many, or all tokens

### Trading
- `rwa --json gm buy <SYM> <AMT> --dry-run` — preview buy
- `rwa --json gm buy <SYM> <AMT> --quote-only` — quote any size without a balance check; never executes (rejects `-y`), still enforces market hours + slippage. JSON `status` is `dry_run` (same shape as `--dry-run`). Use to size a trade before funding.
- `rwa --json gm buy/sell <SYM> <AMT> --max-bps <N>` — reject the trade if quoted all-in cost (spread+fee) > N bps; returns `error_kind: cost_too_high`. `RWA_MAX_BPS` sets a global default. Works in `--dry-run` as a cost check. Also accepted by `buy-basket`/`sell-basket`/`close-all` (over-budget items land in `failed[]` with `error_kind: cost_too_high`), as is `--slippage <BPS>`.
- `rwa --json gm buy <SYM> <AMT> -y` — execute buy
- `rwa --json gm sell <SYM> <AMT> --dry-run` — preview sell
- `rwa --json gm sell <SYM> <AMT> -y` — execute sell
- `rwa --json gm close-all --dry-run` — preview liquidation
- `rwa --json gm close-all -y` — sell all positions sequentially
- `rwa --json gm close-all --parallel -y` — sell all positions in parallel (~4–11x faster for 4+ tokens)
- `rwa --json gm close-all 50% -y` — sell a percentage of every position
- `rwa --json gm buy-basket <SYM AMT ...> --dry-run` — preview basket buy quotes (SYMBOL AMOUNT pairs)
- `rwa --json gm buy-basket <SYM AMT ...> -y` — buy multiple tokens sequentially
- `rwa --json gm buy-basket <SYM AMT ...> --parallel -y` — buy multiple tokens in parallel
- `rwa --json gm sell-basket <SYM AMT ...> --dry-run` — preview basket sell quotes
- `rwa --json gm sell-basket <SYM AMT ...> -y` — sell multiple tokens sequentially
- `rwa --json gm sell-basket <SYM AMT ...> --parallel -y` — sell multiple tokens in parallel

### Portfolio & history
- `rwa --json gm portfolio` — own wallet holdings
- `rwa --json gm portfolio <WALLET>` — any public wallet
- `rwa --json gm history <SYM>` — price history (default `1M`)
- `rwa --json gm history <SYM> -r 1D` — 1D/1W/1M/3M/1Y/ALL

`portfolio` uses a stable nested JSON contract:
- `cash.sol`
- `cash.usdc`
- `gm_positions.positions[]`
- `gm_positions.value_usd`
- `gm_positions.change_24h_usd`
- `gm_positions.change_24h_pct`

Do not rely on legacy flat `portfolio` fields.

### Transfers
- `rwa --json gm send SOL <AMT> <TO> --dry-run` — preview SOL transfer
- `rwa --json gm send SOL all <TO> -y` — drain SOL (auto-reserves tx fee)
- `rwa --json gm send USDC <AMT> <TO> --dry-run` — preview USDC transfer
- `rwa --json gm send USDC all <TO> -y` — drain USDC with full precision
- `rwa --json gm send <TOKEN> <AMT> <TO> -y` — send GM token

### Maintenance
- `rwa --json gm reclaim` — close empty token accounts, reclaim SOL rent
- `rwa --json gm reclaim --token <SYM>` — reclaim one token only
- `rwa --json update --check` — report if a newer release exists (status `up_to_date` | `update_available`)
- `rwa --json update -y` — self-update to latest (verifies SHA-256, fail-closed)

### Wallet
- `rwa keys generate --encrypt` — create encrypted wallet
- `rwa keys import --seed-phrase "word1 word2 ..."` — import mnemonic
- `rwa keys import --private-key <BASE58>` — import private key
- `rwa keys show` — show address + key path
- `rwa keys encrypt` — convert `key.json` -> `key.age`
- `rwa keys decrypt` — convert `key.age` -> `key.json`

## Amount formats

- Exact: `100`
- Percentage: `50%`
- All: `all`

Inputs with too many decimal places are rejected instead of being silently rounded.

## Trading sessions (ET)

- Pre-Market: 4:00 AM – 9:29 AM
- Regular: 9:30 AM – 3:59 PM
- Post-Market: 4:00 PM – 7:59 PM
- Overnight: 8:00 PM – 3:59 AM
- Closed: Weekend / NYSE holidays

Not all tokens are tradable in every session. Use `gm tradable <SYM...>` for symbol checks, `gm tradable` for the full set, or filtered `gm search --tradable-only ...` for bulk scans.

## Bulk workflows

Check tradable + buy basket in 2 commands (most efficient):

```bash
# 1. Get all tradable healthcare stocks in one call
rwa --json gm search --tradable-only --sector Healthcare --type stock

Jupiter API note:
- The CLI tries public Jupiter routes in this order: `lite-api.jup.ag/swap/v2` first, then `ultra-api.jup.ag`, then `lite-api.jup.ag/ultra/v1`, with `lite-api.jup.ag/swap/v1` as the final fallback.
- Route availability can differ by session, holiday calendar, and MM liquidity.

# 2. Buy all tradable tokens at once — one command, parallel
rwa --json gm buy-basket JNJ 25 LLY 25 PFE 25 ABBV 25 --parallel -y
```

Syntax for buy-basket and sell-basket: interleaved `SYMBOL AMOUNT` pairs. Each token gets its own amount:

```bash
rwa --json gm buy-basket TSLA 100 AAPL 50 NVDA 25 --parallel -y   # different amounts
rwa --json gm sell-basket SPY 5 TSLA 3 NVDA all --parallel -y     # partial sells
```

Full exit:

```bash
rwa --json gm close-all --parallel -y   # parallel: all swaps at once (~22s)
# or: rwa --json gm close-all -y         # sequential if needed
rwa --json gm reclaim
rwa --json gm send USDC all <ADDR> -y
rwa --json gm send SOL all <ADDR> -y
```

## Parallel vs sequential

| Tokens | Sequential | Parallel | Speedup |
|--------|-----------|---------|--------|
| 4 | ~97s | ~22s | 4.4× |
| 6 | ~147s | ~22s | 6.7× |
| 10 | ~247s | ~22s | 11× |

Parallel is safe for different tokens. jupiterz routes through multiple MMs internally — if one MM returns a bad quote, the CLI retries to get a better one.

## Error handling

With `--json`, failures return `{"status":"error","error":"..."}` on stdout and exit code `1`.

- `not_tradable` → skip token or check `list --search <SYM>`
- `amount_below_minimum` → buy below 1 USDC (single or basket item); raise the amount
- `insufficient_funds` → wallet lacks USDC or SOL for the trade; fund the wallet, do not retry
- `no_position` → selling a token the wallet does not hold; check `portfolio` first
- Exit code 75 = transient (retry sensible: rpc_unavailable / execute_unavailable / confirmation_timeout / lock contention); exit 1 = permanent
- `market_closed` → tell user when trading reopens
- `No swap route` / `HTTP 400` → likely no liquidity or accidental parallel execution
- `slippage_too_high` → reduce size or skip token
- `confirmation_timeout` → tx may still land; check Solscan before retrying
- `on_chain_failure` → treat as real chain failure, not a preview issue
- `execute_unavailable` (swap) → Jupiter `/execute` was rate-limited/unavailable; the CLI already auto-retries with a fresh order. On repeats, set `RWA_JUPITER_API_KEY` for higher limits.
- `route_unfillable` (swap) → the quoted route would fail on-chain (RFQ MM can't fill) or the signed tx under-delivers vs its own quote beyond slippage tolerance; the CLI auto-refetches excluding that router. Surfaces only after retries are exhausted. Pin a persistently bad router with `RWA_EXCLUDE_ROUTERS=jupiterz` (comma-separated).
- `rpc_unavailable` (also `Solana RPC ... unavailable` / `all RPC endpoints failed` / `HTTP 429` in error text) → public nodes are rate-limited; the CLI already retries transient errors and 429s with backoff. On repeated failures, wait a few seconds, or set `RWA_RPC_URL` to a dedicated endpoint (free API key from Alchemy/Helius/QuickNode/Chainstack/dRPC) — the canonical fix per Solana's own docs.
- `gm portfolio` auto-falls back to Jupiter Ultra holdings when Solana RPC is unavailable; the JSON gains `"source":"jupiter"` (absent on the normal RPC path).