---
name: paygent-setup
description: Install Paygent and connect it to your agent for secure wallet operations and x402 payments
homepage: https://paygent.net
metadata:
  version: 1
---

# Paygent Setup

Paygent gives your agent a hardware-secured smart wallet for on-chain payments. Private keys live in the Secure Enclave (macOS) or TPM (Linux) and never leave the hardware. Spending limits are enforced on-chain by Safe smart contracts, so even a compromised agent cannot exceed them.

This skill walks you through installation and MCP configuration. You do not need to persist this skill after setup is complete.

## What You Get

Once installed, your agent can:

- **Send payments** within on-chain spending limits (silent, no user prompt)
- **Make x402 HTTP requests** with automatic micropayment handling
- **Check balances and transaction history**
- **Deploy the wallet to new chains** (requires user approval)

## Ephemeral Sandbox Warning (Claude Desktop / Claude Web)

Claude Desktop and Claude Web run commands inside an ephemeral sandbox, not on the user's local machine. **Do not run installation commands in the sandbox.** Instead, ask the user to open a terminal on their local machine and run the commands themselves.

This does not apply to Claude Code, Cursor, Codex, Windsurf, or other agents that run directly on the user's machine.

## Installation

### Step 1: Check if Paygent is already installed

Before prompting the user to install, check whether Paygent is already running by looking for the MCP socket:

```bash
# macOS
test -S ~/Library/Containers/net.paygent.wallet/Data/tmp/mcp.sock && echo "installed" || echo "not found"

# Linux
test -S ${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/paygent-wallet/mcp.sock && echo "installed" || echo "not found"
```

If the socket exists, skip to **MCP Configuration** below.

### Step 2: Ask the user to download Paygent

Direct the user to download and install from:

**https://paygent.net/#download**

- **macOS**: Download the `.dmg`, open it, and drag Paygent to Applications.
- **Linux**: Download the `.AppImage` and run it, or install via apt:

```bash
# Add signing key and repository (one-time)
curl -fsSL https://downloads.paygent.net/keys/paygent.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/paygent.gpg
echo "deb [signed-by=/usr/share/keyrings/paygent.gpg] \
  https://downloads.paygent.net/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/paygent.list

# Install
sudo apt update && sudo apt install paygent-wallet
```

After installing, ask the user to open the app so the MCP socket is available.

## MCP Configuration

After installation, open Paygent. The app registers itself with supported MCP clients automatically via the settings menu.

**Supported clients:** Claude Code, Claude Desktop, Cursor, VS Code (Copilot), Windsurf, OpenCode, Codex CLI.

### Claude Desktop (MCPB Plugin)

For Claude Desktop, download and double-click the MCPB plugin for one-click installation:

**https://downloads.paygent.net/latest/paygent-wallet.mcpb**

This configures Claude Desktop to connect to your running Paygent wallet automatically. Skip to **Verify Connection** below.

### Manual Configuration

If automatic registration is unavailable, add the following to your MCP client config. The manual shims use Unix domain sockets and require:

- **macOS**: `nc` (netcat, built-in)
- **Linux**: `socat` (preferred) or `nc`. Install with `sudo apt install socat` if missing.

**macOS** (socket path: `~/Library/Containers/net.paygent.wallet/Data/tmp/mcp.sock`):

```json
{
  "mcpServers": {
    "paygent-wallet": {
      "command": "/bin/sh",
      "args": ["-c", "S=~/Library/Containers/net.paygent.wallet/Data/tmp/mcp.sock;nc -U \"$S\" 2>/dev/null||{ open -jb net.paygent.wallet;for i in $(seq 25);do sleep .2;nc -U \"$S\" 2>/dev/null&&exit;done;exit 1;}"]
    }
  }
}
```

**Linux** (socket path: `$XDG_RUNTIME_DIR/paygent-wallet/mcp.sock`):

```json
{
  "mcpServers": {
    "paygent-wallet": {
      "command": "/bin/sh",
      "args": ["-c", "S=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/paygent-wallet/mcp.sock;if [ -S \"$S\" ]; then socat - UNIX-CONNECT:\"$S\" 2>/dev/null || nc -U \"$S\" 2>/dev/null; else paygent-wallet &>/dev/null & for i in $(seq 50); do sleep 0.1; if [ -S \"$S\" ]; then socat - UNIX-CONNECT:\"$S\" 2>/dev/null || nc -U \"$S\" 2>/dev/null; exit $?; fi; done; exit 1; fi"]
    }
  }
}
```

## Verify Connection

After configuring MCP, ask your agent to run:

```
check_session
```

If the wallet is set up, this returns the wallet address and deployed chains. If not, the agent can guide you through `create_wallet`.

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `check_session` | Check wallet status |
| `create_wallet` | Create a new wallet (mobile pairing + deploy) |
| `deploy_wallet` | Deploy wallet to a new chain |
| `send_transaction` | Send tokens or native currency |
| `make_http_request_with_x402_payment` | HTTP request with automatic x402 payment |
| `get_tokens` | View token balances |
| `get_transactions` | View transaction history |
| `get_networks` | List supported chains and deployment status |
| `get_api_list` | Browse available x402 APIs |
| `get_api_details` | Get details for a specific x402 API |
| `sign_message` | Sign a message with P256 identity key |
| `get_intent_status` | Poll status of deferred operations |
| `cancel_intent` | Cancel a pending intent |
| `get_devices` | List paired devices |

## Triggers

Use this skill when the user wants to:

- Install or set up Paygent
- Connect Paygent to their AI agent or MCP client
- Get started with hardware-secured wallet payments

## After Setup

Once connected, your agent has access to all MCP tools listed above. Use `get_networks` to see which chains the wallet is deployed on, `get_tokens` for balances, and `send_transaction` or `make_http_request_with_x402_payment` for payments.

## Support

- **Homepage**: https://paygent.net
- **Downloads**: https://downloads.paygent.net