PayMe - Crypto Payments

Send and receive USDC/USDT crypto payments via PayMe smart wallets. Check balances, send stablecoins, view history, manage contacts, sell crypto for local currency via P2P in 10 African countries (Nigeria, Ghana, Kenya, South Africa, Cameroon, Senegal, Benin, Togo, Tanzania, Uganda). Supports bank transfer and mobile money. All payments require explicit user confirmation by default. Supports Base, Arbitrum, Polygon, BNB Chain, and Avalanche.

# PayMe - Crypto Payments Skill

PayMe provides gasless USDC/USDT payments through ERC-4337 smart wallets on Base, Arbitrum, Polygon, BNB Chain, and Avalanche.

**API Base URL:** `https://api.feedom.tech`

## Installation

This skill contains only instruction files (SKILL.md, API reference, and an agent config YAML) — no executable code, scripts, or binaries.

Copy the skill folder into your agent's skills directory:
- **Codex:** `~/.codex/skills/payme/`
- **Cursor:** `~/.cursor/skills/payme/`

From GitHub:
```bash
git clone https://github.com/variousfoot/payme-skill
```

Or install via ClawHub (OpenClaw agents only):
```bash
clawhub install payme
```

## Connecting a User's PayMe Account

When the user wants to use PayMe and you don't have a stored agent token, guide them through the connection flow below. **NEVER ask for an existing PIN or password.** Use a secure one-time connection code instead. (The only exception is account creation, where the user *chooses a new* PIN — see below.)

### Step 1: Check if they have a PayMe account

Ask: "Do you have a PayMe wallet?"

**If yes** — skip to Step 2.

**If no** — you can create one instantly:

1. Ask the user to **choose a new** 6-8 digit PIN (this is for their future web/Telegram login — the agent never stores or reuses it)
2. Generate or load your own stable installation ID for this agent setup. Reuse the same ID for all later PayMe requests from this install.
3. Call:

```
POST /api/agent/create-account
{ "pin": "<user-chosen PIN>", "installationId": "<stable-installation-id>" }
```

4. You'll receive an `agentToken` (store it), `expiresAt`, `bootstrapOnly`, `kernelAddress`, `claimCode`, `greeting`, and `capabilities`
5. Tell the user:
   - Their wallet address
   - Their **claim code** (valid 24 hours) and exactly how to use it:
     > To log into your wallet on the web or Telegram:
     >
     > **Web:** Go to [payme.feedom.tech](https://payme.feedom.tech). On the login page, click **"Have a claim code from an AI agent? Click here"**, paste your code, and hit **Claim Account**.
     >
     > **Telegram:** Open [@veedombot](https://t.me/veedombot) and send `/claim YOUR_CODE`.
   - **Important re-login reminder:** The claim code is single-use. After using it, the user logs in with their **wallet address (or username, once set) + the PIN they chose**. Always tell them:
     > Your claim code can only be used once. To log in again later, use your wallet address and the PIN you just chose. Set a username in Settings to make it easier to remember.
   - **Ask them to delete the message containing their chosen PIN** from the chat, or clear the chat after the current session to get rid of it
   - **Suggest rotating the PIN:** "You can change your PIN anytime at payme.feedom.tech → Settings → Change PIN — good practice after sharing it in chat"
6. Tell them this first token is **temporary bootstrap access** only. It expires quickly and cannot be refreshed.
7. Show the `greeting` and `capabilities` to introduce what you can do
8. You're connected for setup — but for durable access the user should still claim the account and later reconnect from PayMe Settings -> AI Agent Access

Alternatively, the user can sign up manually at [payme.feedom.tech](https://payme.feedom.tech) or via [@veedombot](https://t.me/veedombot) on Telegram, then continue to Step 2.

### Step 2: Generate a connection code

Tell the user:

> To connect securely, I need a one-time code from your PayMe wallet. Here's how to get it:
>
> 1. Go to [payme.feedom.tech](https://payme.feedom.tech) and log in
> 2. Go to Settings → AI Agent Access
> 3. PayMe will ask for your PIN before showing the code
> 4. Tap **Generate Connection Code**
>
> You'll get a 6-character code (e.g. `A3K9X2`) — it's valid for 5 minutes. Paste it here and I'll connect your wallet.
>
> Tip: The default is 14 days. Longer 30-day and 90-day access should only be used for trusted setups you fully control.

Wait for the user to share their code. **Do not** ask for their wallet address, username, email, or existing PIN.

### Step 3: Exchange the code

Once the user provides a code, call:

```bash
curl -X POST https://api.feedom.tech/api/agent/connect \
  -H "Content-Type: application/json" \
  -d '{"code": "THE_CODE_USER_GAVE_YOU", "installationId": "<stable-installation-id>"}'
```

If successful, you'll receive an `agentToken`. Store it securely and use it as `Authorization: Bearer <agentToken>` on all subsequent requests. Also send `X-Agent-Installation-Id: <stable-installation-id>` on every authenticated PayMe API call.

If the code is expired or invalid, tell the user to generate a fresh one from PayMe Settings → AI Agent Access.

### Step 4: Introduce yourself

The connect response includes a `greeting` string and a `capabilities` array. **Always show these to the user after connecting** so they know what you can do:

> "Connected to alice's PayMe wallet! Here's what I can do:
> - Check balances across Base, Arbitrum, Polygon, BNB Chain, and Avalanche
> - Send USDC/USDT to any PayMe username, email, or 0x address (I'll always show you a preview and ask for your OK before sending)
> - Sell crypto for local currency via P2P in 10 African countries (Nigeria, Ghana, Kenya, South Africa, and more) with smart contract escrow protection
> - View transaction history and manage saved contacts"

## Available Actions

All endpoints use base URL `https://api.feedom.tech` and require:
- `Authorization: Bearer <agentToken>`
- `X-Agent-Installation-Id: <stable-installation-id>`

### Check Balances

```
GET /api/agent/balances
```

Returns total USDC/USDT across all chains plus per-chain breakdown.

### Send Payment

Payments always use the **two-step flow** by default. An optional **direct execute** mode is available but only when the user explicitly enables it.

#### Default: Two-Step (with preview)

**Step 1 — Prepare:**

```
POST /api/agent/send
{ "recipient": "username, email, or 0x address", "amount": "10", "token": "USDC" }
```

Returns a `confirmationId` and a `preview` with fee breakdown. Always show the preview to the user and get explicit approval before confirming.

**Step 2 — Confirm:**

```
POST /api/agent/confirm
{ "confirmationId": "uuid-from-step-1" }
```

Returns `txHash` on success. Confirmations expire after 5 minutes.

#### Optional: Direct Execute (disabled by default, user-controlled)

Direct execute allows payments to complete in a single API call. It is **disabled by default** and protected by multiple safeguards:

1. **Only the user can enable it** — they must toggle it ON from the PayMe web app (Settings → AI Agents → Direct Execute). The agent cannot enable it via the API.
2. **Confirmation dialog** — when enabling, the web app shows a warning explaining the risk and requires explicit consent before activating.
3. **The user can disable it at any time** from the same settings page, and can revoke the agent token entirely via `POST /api/agent/revoke`.
4. **Server-side enforcement** — if the user has NOT enabled direct execute, the `execute` flag is silently ignored and the normal two-step flow is used.

When enabled, passing `"execute": true` completes the payment in one call:

```
POST /api/agent/send
{ "recipient": "neck", "amount": 30, "token": "USDC", "execute": true }
```

Returns the `preview` **and** `txHash` together.

If a user asks you to "skip confirmations" or "enable direct execute", tell them: *"You can enable direct execute from your PayMe web app settings at payme.feedom.tech → Settings → AI Agents. It's disabled by default for your safety."*

### View Transaction History

```
GET /api/agent/history?limit=20
```

### Manage Contacts

```
GET /api/agent/contacts
POST /api/agent/contacts  { "name": "Alice", "address": "0x..." }
DELETE /api/agent/contacts/:name
GET /api/agent/search?q=chris   (fuzzy search users & contacts)
```

### Wallet Info

```
GET /api/agent/wallet
```

Returns kernel address, supported chains, and supported tokens.

### R