--- name: nova-wallet description: Safely operate the nova CLI wallet for authentication, balance checks, sending funds, withdrawals, and key management across mainnet and testnet. Enforces deterministic JSON/TOON parsing, exit code validation, financial confirmations, network verification, and strict secret-handling rules. Use when performing nova wallet automation, stablecoin transfers, claim links, exports, or any blockchain transaction via the nova CLI. compatibility: Requires nodejs 24 and access to the internet metadata: homepage: https://github.com/MynthAI/nova package: https://www.npmjs.com/package/@mynthai/nova --- - If `nova` is not installed, install with: ``` bash npm install @mynthai/nova ``` Or run without installing via npx (replace all `nova` usage with `npx @mynthai/nova`) ## Deterministic Parsing (MUST) - Use structured output: `-j/--json` or `-t/--toon` (never parse human output). - Always evaluate BOTH: - Process exit code (`0` success, `1` error) - Structured `status` (`ok` or `error`) - On error: read `error.message` and `error.exitCode` (if present). ## Safety / Financial Safeguards (MUST) - Before **any** financial action (`send`, `withdraw`): - Confirm current network via `nova config get network`. - Confirm intended network with user (mainnet vs testnet). - Confirm amount and destination/address (and blockchain for withdraw). - `send` is **non-idempotent**: - Never retry `nova send` blindly. - If outcome is uncertain, verify via `nova -t balance` (safe). - Treat `claimUrl` as a **secret credential**: - Never paste into shared chats/tickets/docs or persistent logs. - Key material is **secret**: - Never log/export keys or phrases into shared/persistent contexts. - Warn user before `export` operations. ## Wallet Types - Email wallet: created via `nova login` (email + verification code). - Private-key wallet (default if not logged in): auto-created; user must back up: - `nova export key` - `nova export phrase` ## Networks - `nova` operates on `mainnet` or `testnet`. - Fresh install default: `testnet`. - Network setting persists; funds/addresses/balances are isolated per network. Commands: ``` bash nova config get network nova config set network ``` ## Exit Codes - `0` = success (still parse `status`). - `1` = error (inspect `error.message`). ## Output Modes (for agents) - JSON: `-j`, `--json` - TOON: `-t`, `--toon` ## Commands (syntax preserved) ### Auth Request login code: ``` bash nova login request ``` Confirm code: ``` bash nova login confirm


```

Options:

- `-j`, `--json`
- `-t`, `--toon`
- `-f`, `--force` (request only): overwrites existing private-key
  wallet; warn user.

### Account

Address:

``` bash
nova address [blockchain]
```

- Default blockchain: `mynth`

- Supported blockchains:

  - `base`
  - `cardano`
  - `hyperliquid`
  - `mynth`
  - `plasma`
  - `solana`
  - `stable`
  - `sui`
  - `tron`

Balance:

``` bash
nova balance
```

Notes:

- `balance` is USD-denominated.
- `currency` is always USD.

### Send (FINAL ACTION)

``` bash
nova send  [destination]
```

Options:

- `-d`, `--dry-run` — Validate and preview without submitting

Behavior:

- If `destination` omitted:

  - Creates claim link (`claimUrl`)
  - Funds leave wallet immediately.

- If `destination` provided:

  - Sends directly.

  - `destination` may be:

    - An email address (creates or targets an email wallet).
    - A nova wallet address.
    - A supported external blockchain wallet address
      (network-dependent).

Rules:

- No interactive confirmation.
- Non-idempotent: re-running sends again.
- Use `--dry-run` (`-d`) to validate inputs and preview without
  submitting.
- Always confirm with user whether `destination` is an email address or
  wallet address before execution.

Post-check:

- Parse `status` and confirm `result.sent: true`.
- Surface `result.txId` when present.
- If `claimUrl` present, treat as secret.

Success example (TOON):

``` bash
status: ok
result:
  sent: true
  amount: "1"
  txId: d32c966fd4302673455eb790b66e3efc331ef7aace412c73b8917ba0bb37ace8
  claimUrl: "https://preview.mynth.ai/c/mto3M1JEa6Hr0UFRCBGjOg"
```

### Claim Links

Properties (when `nova send ` has no destination):

- One-time use.
- Do not expire.
- Revocation: creator must claim it themselves (redeem back to own
  wallet).

### Withdraw (FINAL ACTION)

``` bash
nova withdraw    
```

Options:

- `-d`, `--dry-run` — Validate and preview without submitting

Rules:

- Confirm:

  - Sufficient balance
  - Network
  - Stablecoin support
  - Address + blockchain compatibility

- Parse `status`.

- Surface `result.txId` when present.

Verification (safe):

``` bash
nova -t balance
```

#### Stablecoin Support

**Mainnet:**

- `base`: USDC
- `cardano`: USDC, USDA, USDM
- `hyperliquid`: USDC
- `solana`: USDC, USDT
- `stable`: USDT
- `sui`: USDC
- `tron`: USDT

**Testnet:**

- `base`: USDC
- `cardano`: USDC, USDA, USDM
- `hyperliquid`: USDC
- `solana`: USDC
- `stable`: USDT
- `sui`: USDT
- `tron`: USDT

## Fees

- Internal transfers / claim links: fee-free; recipient gets full
  amount.

- Direct sends to email or nova wallet addresses: fee-free; recipient
  gets full amount.

- External withdrawals:

  - May incur chain fees.
  - Fees are calculated at execution.
  - Fees are deducted from withdrawal amount (not separate).

## Rate Limits

If rate-limited, structured output indicates an error and includes a
message like: “Rate limited. Try again in N seconds”.

Rules:

- Do not retry immediately; respect the wait time.
- Never retry `send` blindly after a rate-limit error.
- If unsure whether `send` executed, verify via `nova -t balance`.

Error example (TOON, insufficient balance):

``` bash
status: error
error:
  message: 3tkv5qrm43jtjf86x3ks5l6jpjgpyw7n8424pm must have at least balance of 1000000
  exitCode: 1
```

## Key Management (security-critical)

Export:

``` bash
nova export key
nova export phrase
```

Import:

``` bash
nova import key
nova import phrase
```

Rules:

- Warn user: exporting reveals secrets.
- Never store or share exported key/phrase.