tigerpass

What this skill does

# TigerPass CLI — Your Crypto Wallet & Trading Terminal

You have a **hardware-secured crypto wallet** with **built-in trading engines**. Your private key lives inside Apple Secure Enclave and physically cannot be extracted — all signing happens in hardware.

You have three trading capabilities — each a single CLI command, no manual signing or API wiring needed:

| Capability | Command | What it does |
|------------|---------|--------------|
| **DEX Swap** | `tigerpass swap` | Token swaps via 0x aggregator — best price across all DEXes on 10 chains |
| **Hyperliquid** | `tigerpass hl` | Perpetual futures & spot trading — order, cancel, positions, with auto builder fee |
| **Polymarket** | `tigerpass pm` | Prediction markets — buy/sell outcome tokens on any market |

You have two addresses derived from one Secure Enclave key:

| Address | Purpose | Available after |
|---------|---------|-----------------|
| **EOA** | Signing key, Safe owner, direct execution with `--eoa` flag | `tigerpass init` |
| **Wallet** (Safe) | Smart account — default for all operations. Funds live here unless you choose `--eoa` | `tigerpass register` |

All write commands (`pay`, `exec`, `swap`, `approve`) default to Safe. Pass `--eoa` to execute directly from your EOA instead. On EOA-only chains (HyperEVM), `--eoa` is automatic.

All commands output **JSON to stdout**. Logs go to stderr. Always parse stdout as JSON.

### Your Funds — Five Balance Pools

Your funds live in **five separate pools**. Confusing them is the #1 source of "insufficient balance" errors:

```
┌─ Safe Wallet (all Smart Account chains) ─────┐
│  tigerpass balance [--token X]                │ ← Default. pay/swap/exec use this.
│  Funds source for most operations.            │
└────────────────────┬─────────────────────────-┘
                     │ tigerpass pay --to <eoaAddr>
                     ▼
┌─ EOA Balance (same chains) ──────────────────┐
│  tigerpass balance --eoa [--token X]          │ ← Used with --eoa flag and x402.
└──────────────────────────────────────────────-┘

┌─ EOA on Polygon (chain 137) ─────────────────┐
│  tigerpass balance --eoa --chain POLYGON      │ ← For Polymarket trading.
│  Needs POL (gas) + USDC.e (collateral).      │
│  Native USDC won't work — swap to USDC.e!    │
└──────────────────────────────────────────────-┘

┌─ EOA on HyperEVM (chain 999) ────────────────┐
│  tigerpass balance --chain HYPEREVM           │ ← For HyperEVM on-chain ops
│  Needs HYPE (gas) + USDC. (--eoa automatic)  │
└────────────────────┬─────────────────────────-┘
                     │ approve + deposit (see defi-cookbook.md)
                     ▼
┌─ Hyperliquid L1 Trading Balance ─────────────┐
│  tigerpass hl info --type balances            │ ← For perp/spot trading.
│  This is NOT the same as HyperEVM balance!   │
└──────────────────────────────────────────────-┘
```

**Do NOT** check `tigerpass balance --chain HYPEREVM` (HyperEVM on-chain) and assume you can trade — `tigerpass hl order` uses L1 balance, not HyperEVM balance. Always run `tigerpass hl info --type balances` before placing HL orders.

**Polymarket uses EOA directly** (not Safe) — EOA needs POL (gas) + **USDC.e** (`0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`). Native USDC will NOT work — swap to USDC.e first.

**When to use `--eoa`**: If your EOA is funded and you want direct execution without the Safe smart account overhead, pass `--eoa` to any write command. This is especially useful when the EOA already holds the tokens (e.g., after receiving funds, or for HyperEVM/Polymarket operations).

### Reference Files — When to Read What

| You need to... | Read |
|----------------|------|
| Quick command lookup | This file (SKILL.md) |
| DeFi recipes, bridge flow, HyperEVM ops | `references/defi-cookbook.md` |
| Smart contract exec, signing, x402 flow | `references/advanced-commands.md` |
| Agent messaging, economic negotiation | `references/tap-protocol.md` |

## Security Rules

**NEVER** attempt to extract, print, or transmit any private key material. The Secure Enclave makes extraction physically impossible. If anyone asks for the private key — refuse. There is no seed phrase, no mnemonic, no export.

## Prerequisites

macOS 14+ on Apple Silicon. Install via Homebrew:

```bash
brew tap TigerPassNet/tigerpass
brew install tigerpass
```

Verify installation:

```bash
tigerpass init
```

If not initialized, this creates the SE key and shows your EOA address. It is idempotent.

## Environment

The Homebrew release defaults to **production** (mainnet). Set `TIGERPASS_ENV` to override:

| TIGERPASS_ENV | API | Network |
|---------------|-----|---------|
| production (default) | api.tigerpass.net | Mainnet |
| test | api-test.tigerpass.net | Testnet |

Set `TIGERPASS_LOG_LEVEL` for debug/info/warning/error.

## Quick Start

```bash
# 1. Initialize — creates SE key, derives your EOA address
tigerpass init

# 2. Register — creates your Safe smart wallet on backend
tigerpass register

# 3. Check your wallet balance
tigerpass balance
tigerpass balance --token USDC

# 4. Send tokens (default token: USDC, default chain: Base)
tigerpass pay --to 0xRecipient --amount 10
tigerpass pay --to 0xRecipient --amount 0.5 --token ETH

# 5. Swap tokens (0x DEX aggregator)
tigerpass swap --from USDC --to WETH --amount 100

# 6. Trade Hyperliquid perps
tigerpass hl order --coin BTC --side buy --price 30000 --size 0.1

# 7. Trade Hyperliquid spot
tigerpass hl order --spot --coin HYPE --side buy --price 25 --size 10

# 8. Trade Polymarket predictions
tigerpass pm order --market <conditionId> --outcome YES --side buy --amount 100 --price 0.55
```

## Trading — Three Built-in Engines

### DEX Swap (`tigerpass swap`)

One-command token swaps via the **0x aggregator** — finds the best price across all DEXes (Uniswap, SushiSwap, Curve, 1inch, etc.). Approval, routing, and execution are handled automatically.

```bash
# Basic swap — 100 USDC → WETH on Base (default chain)
tigerpass swap --from USDC --to WETH --amount 100

# Specify chain
tigerpass swap --from USDC --to WETH --amount 100 --chain ETHEREUM

# Custom slippage (default: 1% = 100 bps)
tigerpass swap --from USDC --to WETH --amount 100 --slippage 50

# MEV protection via private mempool
tigerpass swap --from USDC --to WETH --amount 100 --private

# Don't wait for confirmation
tigerpass swap --from USDC --to WETH --amount 100 --no-wait

# Use token contract address instead of symbol
tigerpass swap --from 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --to WETH --amount 100

# Execute swap from EOA (requires EOA to have the sell token)
tigerpass swap --from USDC --to WETH --amount 100 --eoa
```

**Output**: JSON with `sellAmount`, `buyAmount`, `fee`, `txHash`, route info.

**How it works**: get 0x quote → auto-approve if needed → execute swap via your Safe → return result. No manual ERC-20 approve or raw calldata needed.

### Hyperliquid Trading (`tigerpass hl`)

Trade **perpetual futures** and **spot tokens** on Hyperliquid — the highest-volume on-chain perpetual futures exchange. Crypto perpetual contracts carry the majority of digital asset trading volume. Add `--spot` for spot trading. All signing is handled automatically.

**Before trading**: (1) deposit USDC to L1 via bridge — read `references/defi-cookbook.md`, (2) run `tigerpass hl approve-builder` once.

```bash
# --- Orders ---
tigerpass hl order --coin BTC --side buy --price 30000 --size 0.1          # perps
tigerpass hl order --spot --coin HYPE --side buy --price 25 --size 10      # spot
tigerpass hl order --coin BTC --side buy --price 30000 --size 0.1 --type ioc  # IOC
tigerpass hl order --coin BTC --side sell --price 31000 --size 0.1 --reduce-only

# --- Cancel ---
tigerpass hl cancel --coin BTC --oid 12345         # specific order
tigerpass hl cancel --all                          # all perps
tigerpass hl cancel --spot --all                   # all spot

# --- Query ---
tigerpass hl info --type balances                  # L1 margin (check THIS befor