# Welcome to Squid!

We’re thrilled to have you here! Dive in to learn how to give your AI agents a wallet, payments, and safe review flows.

Squid is financial infrastructure for the agent economy — a control plane where agents and Chat **propose**, you **review**, and **your wallet signs**. It is not a custodian, seed-phrase wallet, or autonomous trading bot.

## Get started

- **[Introduction](#2-what-squid-is-and-is-not)** — Learn the core concepts and what makes Squid unique — and what it is not.
- **[Quickstart](#1-quick-start)** — Install dependencies and open the console locally in minutes.
- **[Console](#4-app-map)** — Explore wallet, deposit, chat, money, and Needs Review surfaces.
- **[Agents](#9-agents-mcp)** — Connect agents via MCP and automate A2A workflows safely.

---

# Squid — Product Documentation

Practical guide to the Squid financial console: what it does, how to use each surface, and what is actually live.

**Product version:** 3.0M  
**Mental model:** agents and Chat **propose** → Squid validates / may HOLD → you **review** → **your wallet signs** → Squid **verifies** on-chain → then it becomes a receipt.

Squid is **not** a custodian, seed-phrase wallet, or autonomous trading bot. It never asks for recovery phrases or private keys.

---

## 1. Quick start

```bash
cd squid-pay
npm install
npm run dev
```

Open `http://localhost:4173` when running the Squid Pay console locally.

| You changed… | Then… |
| --- | --- |
| `server.js` | Restart the Node server |
| `public/*` | Hard-refresh the browser |
| Privy / Hyperliquid client sources | `npm run build:client` (or `npm run dev`, which rebuilds) |

Copy `.env.example` → `.env` and set at least Privy (`PRIVY_APP_ID`, `NEXT_PUBLIC_PRIVY_APP_ID`, `PRIVY_APP_SECRET`) for email login. Optional: Supabase, OpenAI, payment-link CDP/MPP keys — see `.env.example`.

---

## 2. What Squid is (and is not)

| Squid **is** | Squid **is not** |
| --- | --- |
| Control plane for agent-era money (chat, pay, trade, policy, paid products) | A bank that holds your funds |
| Proposal + review + **user-wallet signing** | A place that stores seed phrases |
| Local Node server + vanilla browser UI | An autonomous trading bot |
| Empty until **real** verified activity | A demo with fake balances |

New accounts start empty. Money history appears only after a wallet signature and independent server verification.

---

## 3. Sign in

On the welcome screen you choose how to continue.

### Continue with Email (recommended)

1. Choose **Continue with Email**.
2. Enter your email → Privy sends a one-time code (OTP).
3. Enter the code.
4. Squid verifies the Privy session server-side and creates or links a **Squid Solana wallet** (embedded) if needed.
5. You land on the console; Home shows **Squid Wallet** with address, SOL/USDC, and **Deposit**.

Same email → same Squid wallet on return. Squid stores only public address + Privy user id + email — never keys.

### Continue with wallet

Connect and sign a login nonce with:

| Wallet | Network family |
| --- | --- |
| Phantom | Solana |
| Backpack | Solana |
| MetaMask | EVM |
| Coinbase Wallet | EVM |

You can use external wallets alongside (or instead of) the embedded Squid wallet for payments and trades.

### First-time onboarding

New accounts may be asked for:

1. Location (continent / country)
2. Optional first AI agent
3. Favorite chain (Base, Solana, or Ethereum)

You can change profile and favorites later in **Settings**.

### Log out

Use **Log out** in the nav. Sessions use the `squid_session` cookie.

---

## 4. App map

Primary nav (left):

| Nav label | Page | Use it for |
| --- | --- | --- |
| **Home** | Dashboard | Squid Wallet, balances, recent activity, Deposit |
| **Chat** | Chat | Talk, draft payments/trades, review cards |
| **Money** | Money | Pay composer, Trade (Hyperliquid), payment links / cards |
| **Needs Review** | Hold | Approve / reject / modify agent or high-risk proposals |
| **Agents** | Agents | MCP agents, policies, A2A automations, emergency pause |
| **Activity** | Logs | Timeline of console activity |

Secondary:

| Nav label | Use it for |
| --- | --- |
| **Squid CLI** | Browser CLI + Platform API key |
| **Settings** | Profile, AI, paid products, account |
| **Help** | In-app help docs |

Also available from Agents / Settings areas:

| Surface | Purpose |
| --- | --- |
| **Rules & Receipts** | What is *allowed* vs what is *proven* |
| **AI Settings** | Chat provider, style, memory, assistant on/off |
| **Approvals / Launch** | Platform approval cards and product launch surfaces (mode-dependent) |

---

## 5. Home — Squid Wallet & Deposit

**Home** is your wallet overview.

### Squid Wallet card

- Public Solana address (shortened + copy)
- Live **SOL** and **USDC** balance reads (Solana RPC)
- Wallet source label (e.g. **Squid** for Privy embedded)

### How to deposit

1. Open Home → **Deposit**.
2. Copy the address or scan the QR from another wallet / exchange.
3. Send **SOL** or **USDC (Solana)** to that address.
4. Wait for confirmation; balances refresh automatically while you are signed in.

Deposit only funds the address shown. Sending on the wrong network can lose funds.

### Link / unlink external wallets

From Money or Settings flows you can connect Phantom, Backpack, MetaMask, or Coinbase for signing Solana or EVM payments and Hyperliquid. Squid never takes custody of those keys.

---

## 6. Chat

Chat is the conversational control plane.

### How to use it

1. Open **Chat**.
2. Ask questions or describe a payment/trade in plain language  
   (e.g. “Send 5 USDC on Solana to ADDRESS”).
3. If details are missing, Squid asks for required fields (amount, asset, network, recipient).
4. When complete, you get a **review card** — not a payment yet.
5. Confirm → your wallet opens to **sign**.
6. After broadcast, Squid verifies the chain/provider receipt, then shows a **receipt**.

### Client action states

```text
collecting → validating → quoting → review → signing → broadcast → verified → receipt
                                                              └──────────→ error
```

### What Chat can and cannot do

| Can | Cannot |
| --- | --- |
| Explain balances, rules, holds | Move money without your signature |
| Draft pay / trade reviews | Bypass policy or Needs Review |
| Apply low-impact settings (theme, favorite chain) | Change keys, sign, or destroy the account |

Larger Chat-driven settings changes create an **Approve / Reject** card; the server applies them only after you approve.

Gear / **AI Settings**: optional OpenAI (or compatible) assistant, tone, memory. Native payment/trade parsing still runs first when Squid recognizes a money intent.

---

## 7. Money

Open **Money**. Tabs typically include **Pay**, **Market / Trade**, and related card / link surfaces.

### Pay — send funds

1. Open **Money → Pay**.
2. Enter recipient, asset (`SOL` / `USDC` / `ETH`), network, optional note.
3. Review the quote / risk summary.
4. Confirm → sign in the matching wallet (Solana or EVM).
5. Squid verifies the receipt before writing history.

**Solana path:** prepare transaction → wallet signs → server checks signature.  
**EVM path (Base / Arbitrum / Ethereum):** wallet sends → `POST /api/payments/evm/confirm` checks sender, recipient, amount, token contract, and receipt.

History shows only rows with a signature, tx hash, or verified settlement — never simulated “success.”

Outbound sends use short-lived **payment intents** (about 15 minutes): amount, recipient, asset, network, and policy version are locked before the wallet opens. Agents cannot approve or sign these.

### Trade — Hyperliquid

1. Open **Money → Market / Trade**.
2. Connect MetaMask or Coinbase on **Arbitrum**.
3. Enable Hyperliquid trading (wallet signature).
4. Optionally deposit USDC to Hyperliquid’s bridge (minimum typically **5 USDC** + ETH for gas).
5. Place orders — each order is signed in your wallet.

| Venue | Status |
| --- | --- |
| Hyperliquid | Live signing path |
| Polymarket | UI placeholder — not connected |
| Kalshi | UI placeholder — not connected |

### Payment links (get paid)

Create links from **Money → Pay** or **Agents → A2A**:

1. Set amount (USDC) and optional description.
2. Ensure a signature-verified EVM receiving wallet is linked (email/Solana-only accounts verify a receiver once).
3. Share the public URL (24-hour, one-time style links).

Buyers can:

- **Human checkout** — MetaMask / Coinbase / Phantom EVM pays exact USDC; Squid verifies the tx hash.
- **Agent / x402 checkout** — machine clients get an x402 challenge (default: Base Sepolia test mode).
- **MPP** — only if Stripe + MPP gateway env vars are fully configured.

Default env is testnet (`SQUID_PAYMENT_ENV=test`). Production needs `SQUID_PAYMENT_ENV=production` and, for agent x402, CDP credentials. See `version/PAYMENT_LINKS_X402_MPP.md`.

---

## 8. Needs Review

When risk or agent policy says a proposal must wait for a human:

1. Open **Needs Review** (badge shows pending count).
2. Read the proposal (type, amount, recipient, why it was held).
3. Choose **Approve**, **Reject**, **Modify**, or **Reprocess**.

Approving a hold does **not** by itself move money. A real payment still needs the normal wallet sign + verify path. Agents and Platform API keys can never approve holds or sign.

Risk bands for `POST /api/actions` (deterministic):

| Score | Outcome |
| --- | --- |
| ≥ 80 | BLOCK |
| ≥ 45 | HOLD |
| ≥ 25 | WARN |
| else | EXECUTE (policy/context only — still not a chain payment) |

---

## 9. Agents & MCP

### Create an agent

1. Open **Agents**.
2. Create an agent (name + optional first policy).
3. Copy the **one-time API key** immediately — you will not see the full key again.
4. Point your MCP client at Squid:

```text
URL:  http://localhost:4173/mcp
Auth: Authorization: Bearer <agent-api-key>
```

For remote agents, deploy Squid behind HTTPS and use that public `/mcp` URL.

### What agents can do

- Read account context, balances, holds, rules (within scope)
- **Propose** actions → usually land in **Needs Review**

### What agents cannot do

- Sign transactions
- Broadcast
- Approve holds
- Transfer funds

### Policy knobs (per agent)

- Per-action / daily / session **USDC** limits  
- Allowed assets and networks  
- Trusted recipients  
- Extra approval threshold  
- Expiry  
- **Emergency pause** (blocks new agent proposals)

Monetary limits are in USDC. Proposals in ETH/SOL are denied when a monetary limit exists unless a verified price-quote policy is in place.

### Platform API key

**Settings → Squid CLI** (or CLI section): create an account-level key for workspace-wide proposals and the native CLI. Same rule: proposals only; no signing.

### Paid MCP sessions

Paid products of type `mcp_session` can mint a short-lived Bearer grant for `/mcp/paid` after verified settlement. Hashed at rest; not a standing key.

---

## 10. A2A automation

Under **Agents → A2A**:

1. Open an agent’s menu → create or edit an automation.
2. Build a graph: one **Trigger**, then up to five sequential **Pay** or **Trade** blocks (Polymarket is preview-only).
3. **Validate** → **Simulate** (safe default).
4. **Activate** only when you intentionally enable an exact configuration.

Automation is **testnet-first**. Live broadcast needs:

- Explicit owner activation  
- Capped Base vault authority (Pay) and/or isolated Hyperliquid API-wallet subaccount (Trade)  
- External KMS/HSM executor — Squid does **not** store automation signing keys  

Details: `version/A2A_AUTOMATION.md`.

---

## 11. Rules & Receipts

Open **Rules & Receipts** (page id `Files`).

> **Rules** = what is allowed · **Receipts** = what is proven after wallet sign + server verify.

### Rules tab

| Tool | Effect |
| --- | --- |
| Structured payment policies | Max USDC, allowed assets/networks, require trusted recipient |
| Trusted recipients (vendors) | Address book used in risk scoring |
| Context notes | Free-text lines for Chat/context only — never execute |

Rules raise or lower risk scores and HOLDs. They never move money.

### Verified receipts tab

Only payments/products with signature, tx hash, or settlement proof:

- Amount, asset, network, status  
- Recipient / product  
- Proof hash with copy + explorer link  

Empty until you complete a real send or paid-product settlement.

---

## 12. Settings & AI Settings

### Settings

- Profile name, email display, location  
- Favorite chain / account mode (can hide some surfaces)  
- Paid product / payment-link configuration entry points  
- Account access and logout-related controls  

### AI Settings (`Data & AI`)

- Enable / disable assistant  
- Provider and model (needs server `OPENAI_API_KEY` or compatible config)  
- Style and memory management  

The assistant explains and drafts; it cannot bypass wallet confirmation or policy.

---

## 13. Squid CLI

### Browser CLI

1. Open **Squid CLI** (or Settings → CLI).
2. Create / view the blurred **Platform API key**.
3. Click **Open CLI** → authenticated console at `/cli`.  
   Launch uses a one-time token (≈60s); the key is never put in the URL.
4. Optional four-step tutorial on first visit.

Browser CLI uses your signed-in owner session. It can run allowlisted read/propose commands only — no OS shell, no hold approval, no signing.

### Native terminal CLI

Package under `squid cli/`:

```bash
npm run cli -- --help
npm run cli -- auth set-key
npm run cli -- status
npm run cli -- wallets list
npm run cli -- holds list
npm run cli -- actions propose --type transfer --asset USDC --amount 25 --recipient 0x... --chain Base
```

Authenticate with the Platform API key (stored locally with restrictive permissions). Same safety boundaries as the browser CLI.

---

## 14. Squid Brain (decision engine)

Server-side financial decision system under `src/brain/`. Every analyzed intent is scored through policy, fraud, anomaly, financial risk, agent security, heuristics, and optional LLM reasoning.

Final decisions are only:

```text
ALLOW | HOLD | BLOCK
```

Hard policy violations always **BLOCK**; ML/LLM cannot override them. Provider failures never default to allow. Owners can submit feedback; offline training/export exists — there is **no** uncontrolled online learning.

For operators: see `README.md` (Brain + migrations) and `brainsquid.md`.

---

## 15. Safety rules (do not break these expectations)

1. **No private keys or seed phrases** in Squid.  
2. **Normal money movement requires your wallet signature.**  
3. Chat cards and drafts are not receipts.  
4. History is written only after **server verification** of signature / tx.  
5. Agents and CLI **propose**; humans + wallets execute.  
6. Files and rules are **context**, never executors.  
7. Incomplete actions return a **structured error**, never fake success.

Structured error shape:

```json
{
  "status": "failed",
  "type": "validation_error",
  "code": "machine_readable_code",
  "message": "Human-readable explanation.",
  "context": {}
}
```

---

## 16. What’s live vs placeholder

| Feature | Status |
| --- | --- |
| Privy email OTP + Squid Solana wallet + Deposit | Live (needs Privy env + dashboard config) |
| External wallet login (Phantom / Backpack / MetaMask / Coinbase) | Live |
| Solana SOL / USDC balance read | Live RPC |
| Solana / EVM payments with verify | Implemented — test with real low-value txs |
| Hyperliquid markets + signed orders | Live path (Arbitrum wallet) |
| MCP `/mcp` propose-only agents | Live |
| Payment links (human + x402 test) | Partial — facilitator/env dependent |
| A2A automation broadcast | Simulation-first; live needs vault + executor |
| Polymarket / Kalshi | UI only |
| Seeded demo balances | **Removed** — empty until real activity |

---

## 17. Typical journeys

### A. Email → fund → first send

1. Continue with Email → OTP → land on Home.  
2. Deposit SOL/USDC to Squid Wallet.  
3. Money → Pay (or Chat: “send …”).  
4. Review → sign → wait for verified receipt.  
5. Confirm in **Rules & Receipts → Verified receipts**.

### B. Connect agent safely

1. Agents → create agent → copy API key.  
2. Configure MCP client with Bearer key.  
3. Agent proposes a transfer → appears in **Needs Review**.  
4. You approve the hold, then complete wallet signing if you still want the payment.  
5. Use emergency pause if something looks wrong.

### C. Trade on Hyperliquid

1. Money → Trade → connect MetaMask/Coinbase on Arbitrum.  
2. Enable trading → deposit USDC if needed.  
3. Place a signed order → verify status in the Trade UI / activity.

### D. Get paid via link

1. Link an EVM receiving wallet if needed.  
2. Create payment link with amount.  
3. Share URL; buyer pays; Squid records receipt only after verification.

---

## 18. Project layout (for builders)

```text
server.js                 # All API, auth, policy, MCP, payments, persistence
public/
  index.html              # Shell + login
  app.js                  # Console UI + wallet flows
  styles.css
  privy-auth.jsx|.bundle.js
  hyperliquid.js|.bundle.js
  cli.html / payment.html
src/brain/                # Decision engine
data/accounts/*.json      # Per-user state (gitignored)
squid cli/                # Native CLI package
version/                  # Deeper product docs
tests/                    # node --test
```

State mutations: browser calls API → `server.js` validates → `persist()` → UI re-renders from response.

---

## 19. Deeper docs

These files live in the Squid Pay product repository (not this marketing site). On this site, use the [product documentation Markdown guide](/docs.md) for the LLM-friendly product guide.

| Doc | When to read |
| --- | --- |
| `AGENTS.md` | Coding agents / session handoff |
| `README.md` | Architecture, API inventory, production checklist |
| `version/MVP.md` | Full product map and auth diagram |
| `version/CONTINUE.md` | Near-term payment/chat priorities |
| `version/PAYMENT_QA.md` | End-to-end wallet / payment QA matrix |
| `version/PAYMENT_LINKS_X402_MPP.md` | x402 / MPP rails |
| `version/A2A_AUTOMATION.md` | Automation states and gates |
| `version/SEND_SPEND_SECURITY.md` | Payment intents and spend limits |
| `VERCEL_DEPLOYMENT.md` | Deploy notes |

---

## 20. Support checklist if something fails

| Symptom | Likely fix |
| --- | --- |
| `ERR_CONNECTION_REFUSED` | Server not running — `npm run dev`, use port **4173** |
| “Endpoint not found” on payments | Stale Node process — restart server, hard-refresh |
| Email OTP never arrives | Check Privy Dashboard (app id, email login, allowed origins including `http://localhost:4173`) |
| Wallet created but no balances | Fund via Deposit; confirm Solana mainnet address; wait for RPC refresh |
| Agent cannot “pay” | Expected — agents only propose; you must review and sign |
| Payment link x402 fails | Confirm `SQUID_PAYMENT_ENV` and CDP / facilitator config for that mode |