# Vishwa CLI — User Guide

> Talk to your money — within limits you set. Vishwa CLI is an agent-native console that lets
> you check balances, explore prediction markets, and place and close trades on Solana, all in
> plain English. Every action you ask for is verified against your own constraints **before** it
> executes.

This guide walks through everything shown in the demo, step by step. Each step links to a
short ~10-second video clip (`clips/`) so you can follow along.

---

## How Vishwa works: the gateway + control layer

Vishwa is a **pre-execution verification control layer**. It sits between what an agent *decides*
and what actually *executes*, so funds can move autonomously without handing over blind trust.

```
You / Agent  ──►  Gateway (Vishwa API)  ──►  Control layer (TEE)  ──►  Execution
 plain-English      receives the              verifies the request      signs & settles
 intent             unsigned request          against your constraints  only on a passing proof
```

Four ideas matter:

1. **The agent never holds your keys.** It submits an *unsigned request* — a proposal — through
   the **gateway** (`api.vishwalab.com`). It cannot sign or send a transaction on its own.
2. **The control layer verifies first.** Inside a Trusted Execution Environment (TEE), three
   checks run against your sealed policy:
   - **Authorization** — is this agent allowed to do this action, on this venue?
   - **Solvency & limits** — is it within your per-trade / daily / monthly caps?
   - **Execution fidelity** — is the price within your slippage tolerance vs. the live market?
3. **Constraints are sealed in hardware.** Your limits live inside the TEE — invisible to both
   the agent and the wallet. Only a passing proof unlocks execution.
4. **The data is independent.** The control layer pulls oracle/venue prices *itself*, so it can
   catch a bad fill that a wallet policy engine (which only sees the transaction shape) cannot.

> 💡 **This is the part the demo skips.** The recorded walkthrough starts at "decide & execute."
> In production, **Step 0 (below) comes first** — you define the constraints once, and everything
> after is gated by them.

---

## What you'll be able to do

By the end of this guide you will have:

0. **Defined your constraints** (the guardrails the control layer enforces)
1. Installed Vishwa CLI and signed in (connected to the gateway)
2. Checked your on-chain wallet
3. Browsed live Polymarket prediction markets
4. Placed a trade (bought "Yes" contracts on a market)
5. Reviewed your open positions
6. Closed a position (sold)
7. Reviewed your updated wallet and P&L

You never type a flag or memorize a command. You just describe what you want — inside the limits
you set.

---

## Prerequisites

- **Node.js 18+** (the demo uses v22.10.0) and **npm**
- A terminal (the demo uses Warp)
- A Vishwa account — you'll create/sign in during setup

Check Node is installed:

```bash
node --version
npm --version
```

---

## Step 0 — Define Your Constraints
🎬 *Not in the recorded demo — see note below.*

This is the foundation. Before the agent can move a cent, the **fund owner** seals a
**constraint policy** into the control layer. The agent never sees the full policy — it only
ever gets *allowed* or *denied*.

You can express limits in plain English:

```
set my limits: only trade on Polymarket, max $20 per trade,
$100 per day, buy and sell contracts only — no transfers
```

Under the hood this becomes a signed **constraint policy** sealed inside the TEE. The schema
mirrors Vishwa's control-layer policy:

```jsonc
{
  "authorized_agents": [{
    "id": "agent:vishwa-cli",
    "allowed_operations": ["buy_contracts", "sell_contracts"],
    "per_operation_limits": {
      "buy_contracts": {
        "per_tx_usd": 20,
        "daily_usd": 100,
        "monthly_usd": 1000,
        "approved_venues": ["polymarket"],
        "max_slippage": 0.02
      }
    }
  }],
  "global_constraints": {
    "daily_limit_usd": 100,
    "rate_limiting": { "max_operations_per_minute": 5 }
  }
}
```

What each field controls:

| Constraint | What it enforces |
|------------|------------------|
| `allowed_operations` | Which actions the agent may take (e.g. buy/sell only — never transfer out) |
| `approved_venues` | The allow-list of execution venues (e.g. Polymarket) |
| `per_tx_usd` / `daily_usd` / `monthly_usd` | Spend caps per trade, per day, per month |
| `max_slippage` | How far the fill price may drift from the live market |
| `rate_limiting` | Max operations per minute/hour — blocks runaway loops |

After this is sealed, **every** step below is checked against it automatically. A `buy` that
would exceed `per_tx_usd`, hit an un-approved venue, or fill outside `max_slippage` is **denied
before it ever signs**.

> ⚠️ **Missing from the demo:** the recorded walkthrough does *not* show this step — it begins
> at Step 1 and trades freely. Treat Step 0 as required in any real deployment. *(The exact
> `vishwa-cli` command/flow for sealing a policy should be confirmed against your deployment —
> the schema above reflects the control-layer policy model.)*

---

## Step 1 — Install & Sign In
🎬 `clips/01-setup-and-login.mp4`

Vishwa ships as an agent skill. Point the agent at the install guide and it handles the rest:

```
Please follow the instructions to install Vishwa from
https://api.vishwalab.com/skills/vishwa-cli/skill.md
```

The agent will:

1. **Check prerequisites** — confirms Node.js and npm are present.
2. **Install the CLI globally** — installs the `vishwa-cli` package via npm.
3. **Sign you in** — runs:

   ```bash
   vishwa-cli login
   ```

   This opens your browser to `vishwalab.com/auth/login`. Approve the session and the CLI is
   connected to the Vishwa **gateway**. Your agent wallet is created/linked automatically.

✅ When this finishes you have a working CLI bound to your Vishwa wallet, with every request
routed through the gateway into the control layer you configured in Step 0.

---

## Step 2 — Check Your Wallet
🎬 `clips/02-check-wallet.mp4`

Just ask:

```
get my wallet
```

You'll see your Solana wallet at a glance:

| Field | Example |
|-------|---------|
| Address | `7zU3…GkemzLG` (your Solana address) |
| SOL balance | `0.0951 SOL` |
| Tokens | `USDC: 10.38`, `JupUSD: 10.26` |

This is your live on-chain balance — SOL for gas plus any stablecoin holdings used for trading.

---

## Step 3 — Browse Prediction Markets
🎬 `clips/03-browse-markets.mp4`

Vishwa connects to **Polymarket**. Ask to see what's active:

```
show me the polymarket hot events
```

Then drill into a specific market in plain language:

```
2026 FIFA World Cup Winner
```

The agent returns a ranked table of contenders with **live prices and volume**:

| Team | Price (¢/share) | Volume |
|------|-----------------|--------|
| France | 16.2¢ | $39.5M |
| Spain | 16.0¢ | $32.0M |
| England | 11.0¢ | $27.9M |
| … | … | … |

It also explains **how it works**: each outcome is a Yes/No market. Buying "Yes" at $0.162
means each share pays out **$1.00** if that outcome wins. Prices move in real time as people
trade, and resolved/eliminated outcomes settle to "No."

---

## Step 4 — Place a Trade
🎬 `clips/04-buy-contracts.mp4`

Describe the trade you want:

```
Buy France 10 yes contracts in this market
```

The agent does the right thing automatically:

1. **Looks up the live orderbook** to find the best available ask.
2. **Checks the market minimum.** Polymarket has a **$5 minimum order**. 10 contracts at
   ~$0.162 is only ~$1.62 — too small — so the agent scales the order up to the minimum
   (**31 contracts ≈ $5.02**) and tells you it did so.
3. **Submits the request through the gateway** — and the control layer verifies it against your
   Step 0 policy before anything signs:
   - *Authorization:* `buy_contracts` is allowed, venue is `polymarket` ✔
   - *Solvency & limits:* ~$5.02 ≤ `per_tx_usd` and within `daily_usd` ✔
   - *Fidelity:* fill price within `max_slippage` of the live book ✔
4. **Signs and submits** the transaction — only because the request passed.

> If the order had exceeded your per-trade cap or hit an un-approved venue, the control layer
> would **deny it before signing** — the agent simply reports it can't proceed.

You get a clean confirmation:

| Detail | Value |
|--------|-------|
| Market | France — 2026 FIFA World Cup Winner |
| Side | Buy Yes |
| Contracts | 31 |
| Cost | ~$5.02 (31 × $0.162) |
| Transaction | `4ME9FRDZ…PDaZ2GneJ` |

> 💡 The agent is transparent: it explains *why* it bought 31 instead of 10 (the $5 floor)
> before you commit, so there are no surprises.

---

## Step 5 — Check Your Positions
🎬 `clips/05-check-positions.mp4`

```
show me my positions
```

You get a per-position breakdown:

| Detail | Value |
|--------|-------|
| Position | France — 2026 FIFA World Cup Winner (Yes) |
| Contracts held | 28.64 |
| Avg purchase price | $0.162 / contract |
| Total cost | $4.64 |
| Current value | $4.61 (mark $0.161) |
| Open orders | 0 |
| P&L | −$0.03 (−0.6%) |

The agent notes that only part of the order filled at the exact price, and reminds you that
you can **claim the payout if the outcome wins** or **sell anytime** before resolution.

---

## Step 6 — Sell / Close a Position
🎬 `clips/06-sell-position.mp4`

```
sell all contracts in this position
```

The agent closes the whole position and confirms:

| Detail | Value |
|--------|-------|
| Contracts sold | 28.64 France Yes |
| Sell price | ~$0.161 / contract |
| Proceeds | ~$4.61 |
| Transaction | `5Se2D3Z9…2ZuFntaye` |

It summarizes the round trip: bought for ~$4.64, sold for ~$4.61 — a small loss of ~$0.03
plus fees — and notes the funds return to your wallet shortly.

---

## Step 7 — Wallet Recap & P&L
🎬 `clips/07-wallet-recap.mp4`

Close the loop by asking again:

```
get my wallet
```

Now the agent shows a **before / after** view of the whole session:

| Asset | Before | After | Change |
|-------|--------|-------|--------|
| SOL | 0.0951 | 0.0894 | −0.0057 (tx fees) |
| USDC | 10.38 | 5.16 | −5.22 (buy/sell + fees) |
| JupUSD | 10.26 | 10.53 | +0.27 |

…plus a plain-English recap of the France play (bought, sold, net result) and a prompt to
explore more markets.

---

## The big idea

Everything above happened **without a single dashboard, flag, or transaction-builder**. You
described intent in natural language and the agent:

- read live market data,
- handled exchange rules (minimum order size),
- submitted each action as an **unsigned request through the gateway**,
- had it **verified against your constraints** in the control layer,
- and only then signed and submitted on-chain — reporting results in human terms.

That's the Vishwa model: **agent-native finance with a pre-execution control layer**. The human
(or another agent) states the goal; the agent proposes; and the verification infrastructure
decides whether it's allowed *before* anything irreversible happens. Autonomy with a hardware
seatbelt.

---

## Quick command reference

| You want to… | Just say… |
|--------------|-----------|
| Set guardrails | "set my limits: only Polymarket, max $20/trade, $100/day, buy & sell only" |
| Install | "Install Vishwa from https://api.vishwalab.com/skills/vishwa-cli/skill.md" |
| Sign in | `vishwa-cli login` (the agent runs this for you) |
| See balances | "get my wallet" |
| See markets | "show me the polymarket hot events" |
| Open a market | "2026 FIFA World Cup Winner" |
| Buy | "buy France 10 yes contracts in this market" |
| View holdings | "show me my positions" |
| Close | "sell all contracts in this position" |
| Review | "get my wallet" |

---

*Generated from the product demo recording. Figures shown are example values from the demo
session and will differ from your live account.*