locus

# Locus Payment Skill

Locus connects AI agents to crypto wallets via MCP. Tools are **dynamic** — each user gets different tools based on their permission group.

## Setup (Agent-Guided)

When the user asks to set up Locus, use payments, or anything payment-related — check if Locus is configured and walk them through setup interactively:

### Step 1: Check if mcporter is installed
```bash
command -v mcporter || npm i -g mcporter
```

### Step 2: Check if Locus is already configured
```bash
mcporter config get locus 2>/dev/null
```
If configured, skip to **Usage**. If the user wants to reconfigure, run:
```bash
mcporter config remove locus
```

### Step 3: Ask the user for their API key
Tell them:
> You'll need a Locus API key to connect your wallet. Get one at **https://app.paywithlocus.com** — each key is tied to your wallet and permission group. Paste it here when you're ready.

Wait for the user to provide their key. It should start with `locus_`. If it doesn't, warn them and confirm before proceeding.

### Step 4: Configure mcporter
```bash
mcporter config add locus \
  --url "https://mcp.paywithlocus.com/mcp" \
  --header "Authorization=Bearer <API_KEY>" \
  --scope home
```

### Step 5: Verify the connection
```bash
mcporter list locus
```
If tools appear, setup is complete — tell the user they're ready. If it fails, ask them to double-check their API key and try again.

### Alternative: Script-based setup
Users can also run the setup script directly from the Clawdbot workspace root:
```bash
bash skills/locus/scripts/setup.sh
```

## Usage

**Always discover available tools first:**
```bash
mcporter list locus --schema
```

This returns all tools the user's permission group allows. Tools vary per user — do not assume which tools exist. Use the schema output to understand parameters.

**Call any discovered tool:**
```bash
mcporter call locus.<tool_name> param1=value1 param2=value2
```

For array/object parameters:
```bash
mcporter call locus.<tool_name> --args...

# Locus — Payment Tools for AI Agents

Locus connects your ClawdBot agent to a crypto wallet via MCP, enabling payments, balance checks, and token management.

## Quick Start

1. **Install the skill:**
   ```bash
   clawdhub install locus
   ```

2. **Run setup from your ClawdBot workspace root:**
   ```bash
   bash skills/locus/scripts/setup.sh
   ```

3. **Get your API key** at https://app.paywithlocus.com — each key is tied to your wallet and permission group.

4. **Verify it works:**
   ```bash
   mcporter list locus
   ```

That's it! Your agent can now send payments, check balances, and manage token approvals.

## Manual Setup (without script)

If you prefer to configure manually:
```bash
npm i -g mcporter    # if not installed
mcporter config add locus \
  --url "https://mcp.paywithlocus.com/mcp" \
  --header "Authorization=Bearer YOUR_API_KEY" \
  --scope home
```

## What Your Agent Can Do

Tools vary by permission group, but typically include:
- **get_payment_context** — Budget status & whitelisted contacts
- **list_tokens** — Available tokens with balances and limits
- **send_token** — Send to wallet address, ENS name, or email
- **send_token_multi** — Batch send multiple tokens
- **approve_token** — Set ERC-20 spending allowances

## Learn More

https://paywithlocus.com