> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/getting-started/quickstart.md).

# Quickstart

Three paths to get started with Gotts, from zero-config to fully customized.

## Option 1: Zero-Config MCP Access (Instant)

Add Gotts Safe to any MCP-compatible client with a single command:

```bash
claude mcp add gotts -- npx @gotts.ai/safe
```

This gives you immediate access to 26 data tools and 6 bootstrap tools with no configuration. Data tools are read-only and work without a wallet or API keys.

The 6 bootstrap tools let the LLM guide you through setup conversationally:

| Tool                 | Purpose                                 |
| -------------------- | --------------------------------------- |
| `check_setup_health` | Diagnose current configuration status   |
| `setup_wallet`       | Configure a wallet for write operations |
| `setup_rpc`          | Set custom RPC endpoints                |
| `setup_identity`     | Register an ERC-8004 on-chain identity  |
| `upgrade_profile`    | Activate additional tool profiles       |
| `gotts_doctor`       | Run diagnostics and fix common issues   |

When you invoke a write tool (e.g., `execute_swap`) without a wallet configured, it returns a `nextAction` pointing to the appropriate bootstrap tool. The LLM uses this to walk you through setup without leaving the conversation.

## Option 2: Zero-Dep Setup (30 Seconds)

Generate a local wallet and config file automatically:

```bash
npx @gotts.ai setup --zero
```

This runs a non-interactive flow that:

1. Generates a random local private key
2. Writes config to `~/.gotts/config.json` (permissions: `0o600`)
3. Generates a Read API key
4. Sets the default profile to `data`

Output:

```
Profile:  data (read-only)
Wallet:   local (auto-generated)
Config:   ~/.gotts/config.json

API Keys:
  Read: gotts_read_...

Start: npx @gotts.ai safe
```

## Option 3: Interactive Setup (5 Minutes)

Run the full setup wizard:

```bash
npx @gotts.ai setup
```

The wizard asks 5 questions:

1. **Intent** -- what you want to do (monitor, trade, provide liquidity, manage vaults, or full access)
2. **Wallet type** -- how to sign transactions (local key, Privy, Safe multisig, or none for read-only)
3. **Wallet credentials** -- keys and IDs for your chosen wallet provider
4. **Custom RPC** -- optional custom RPC endpoint for a specific chain
5. **Profile** -- automatically selected based on your intent, or override manually

The wizard generates all three API key tiers (Read, Feedback, Write) and writes everything to `~/.gotts/config.json`.

Output:

```
Profile:  trader
Wallet:   privy
Config:   ~/.gotts/config.json

API Keys:
  Read:     gotts_read_...
  Feedback: gotts_feedback_...
  Write:    gotts_write_...

Start MCP server:
  npx @gotts.ai safe
```

## Post-Setup Commands

After setup, these commands are available:

```bash
npx @gotts.ai safe           # Start the MCP server (stdio)
npx @gotts.ai safe --http    # Start the MCP server (HTTP on port 3000)
npx @gotts.ai portal         # Launch the Agent Management Dashboard
npx @gotts.ai install-mcp    # Add Gotts Safe to your IDE's MCP config
npx @gotts.ai doctor         # Run diagnostics and verify configuration
npx @gotts.ai config         # View or edit ~/.gotts/config.json
```

### Install MCP in Your IDE

Register Gotts Safe with Claude Code, Cursor, or VS Code:

```bash
npx @gotts.ai install-mcp
```

This writes the MCP server configuration to your IDE's settings file so Gotts tools appear automatically.

## Tool-Triggered Setup

Write tools that require a wallet return structured `nextAction` responses when prerequisites are missing:

```json
{
  "error": "WALLET_NOT_CONFIGURED",
  "message": "A wallet is required to execute swaps.",
  "nextAction": {
    "tool": "setup_wallet",
    "message": "Configure a wallet to enable write operations."
  }
}
```

MCP clients that support tool chaining can use `nextAction` to automatically invoke the bootstrap tool. This enables a conversational onboarding flow where the LLM guides setup step by step.

## Using Skills

Skills are user-facing interfaces that parse intent and delegate to agents. Every skill maps to a slash command. Use `/skill-name` in any MCP-compatible client to invoke a skill directly.

### Common Slash Commands

```bash
# Trading
/execute-swap           # Execute a token swap
/plan-swap              # Plan a swap (advisory, no execution)
/cross-chain-swap       # Swap across chains via ERC-7683

# Research
/analyze-pool           # Analyze pool metrics and health
/research-token         # Research token fundamentals
/portfolio-report       # Generate portfolio report

# Liquidity
/manage-liquidity       # Add, remove, or collect LP fees
/optimize-lp            # Optimize LP range with backtesting

# Infrastructure
/check-safety           # Check current safety status
/setup-agent-wallet     # Provision agent wallet with identity
```

### Progressive Disclosure

Skill results use three tiers of detail:

* **Tier 1** — One-line summary (always shown on success)
* **Tier 2** — Full dashboard with charts and tables (shown for warnings or on request)
* **Tier 3** — Raw JSON, MCP tool call trace, agent delegation trace (on request)

### Sandbox Mode

New users start on an Anvil fork (local testnet). Use `/setup-local-testnet` to enter sandbox mode. Switching to production requires explicit wallet provisioning, funding, and user confirmation.

All 68 slash commands are listed in the [Skills Reference](/docs/reference/skills.md).

## Next Steps

* [Configuration](/docs/getting-started/configuration.md) -- config file schema, environment variables, tool profiles
* [API Keys](https://github.com/wpank/gotts.ai-monorepo/blob/main/docs/security/api-keys.md) -- three-tier key model and authorization
* [MCP Tools](/docs/reference/mcp-tools.md) -- full tool catalog organized by profile
* [Local Testnet](https://github.com/wpank/gotts.ai-monorepo/blob/main/docs/guides/local-testnet.md) -- start a local Uniswap dev environment