Welcome to Squid!

Product overview

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

cd squid-pay
npm install
npm run dev

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

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)

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:

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):

Secondary:

Also available from Agents / Settings areas:

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

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

What Chat can and cannot do

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.

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):

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:

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

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/:

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:

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:

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

16. What’s live vs placeholder

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)

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 for the LLM-friendly product guide.

20. Support checklist if something fails