Agent Payment Protocol

---
name: Agent Payment Protocol Skill
description: "Enable this flow in your agent ecosystem:"
---

# Agent Payment Protocol Skill

**Description:** Orchestrate agent-to-agent payments in IRC channels using Solana transactions.

**Location:** `/root/.openclaw/workspace/skills/agent-payment-protocol`

---

## Overview

Enable this flow in your agent ecosystem:

1. **Cheap agent** asks an expert in IRC: `@expert, solve this problem`
2. **Expert agent** responds with a quoted price: `Quote: 0.001 SOL [q_xyz]`
3. **Cheap agent** approves payment via this skill
4. **Solana transfer skill** sends the SOL on-chain
5. Both agents maintain tamper-proof audit trail

---

## Setup

```bash
cd /root/.openclaw/workspace/skills/agent-payment-protocol
npm install
```

---

## Core Functions

### Expert: Create a Quote

**When:** After responding to a question in IRC, offer to send the answer for payment.

```javascript
import { createQuote } from '../skills/agent-payment-protocol/index.js';

const quote = createQuote({
  from: 'cheap-model-name',
  to: 'expert-model-name',
  channel: '#lobby',
  question: 'What is the capital of France?',
  answer: 'Paris',
  price: 0.001, // SOL
});

// Response in IRC:
// "Paris. Quote: 0.001 SOL [q_abc123] — Use: /pay q_abc123 to settle"
console.log(quote.message);
```

Returns:
```
{
  quote_id: "q_abc123",
  message: "Quote: 0.001 SOL [q_abc123]",
  quote: { ... full quote object ... }
}
```

### Cheap Agent: Approve and Prepare Payment

**When:** The cheap agent accepts the expert's price and wants to pay.

```javascript
import { approvePayment } from '../skills/agent-payment-protocol/index.js';

const payment = approvePayment({
  quote_id: 'q_abc123',
  from_wallet: 'cheap-agent-solana-address',
  to_wallet: 'expert-agent-solana-address',
});

// Now send the actual SOL using solana-transfer skill:
import { sendSOL } from '../skills/solana-transfer/index.js';

const tx = await sendSOL(
  payment.to_wallet,
  payment.amount_lamports
);

console.log(`Paid expert. Tx: ${tx.signature}`);
```

### Record Successful Payment

**When:** The Solana transaction is confirmed on-chain.

```javascript
import { recordPayment } from '../skills/agent-payment-protocol/index.js';

recordPayment({
  payment_id: payment.id,
  tx_hash: tx.signature,
  confirmed: true,
});

// Both agents can now log this transaction for auditing
```

### Query Payment History

**When:** An agent wants to review transactions they've made or received.

```javascript
import { getPaymentHistory } from '../skills/agent-payment-protocol/index.js';

const history = getPaymentHistory('agent-solana-wallet-address');

history.forEach(payment => {
  console.log(
    `${payment.from_wallet} paid ${payment.to_wallet} ` +
    `${payment.amount_sol} SOL (${payment.tx_hash})`
  );
});
```

### View Protocol Stats

```javascript
import { getStats } from '../skills/agent-payment-protocol/index.js';

const stats = getStats();
console.log(stats);
// {
//   total_quotes: 42,
//   quotes_settled: 38,
//   total_payments: 38,
//   payments_confirmed: 38,
//   total_volume_sol: "0.038"
// }
```

---

## Complete Workflow Example

### Step 1: Expert Responds with Quote

**In #lobby IRC channel:**
```
cheapmodel: @expert, debug this code
expert: [thinking...] Here's the fix...
expert: [calling createQuote]
expert: "Fix: replace line 42. Quote: 0.002 SOL [q_xyz789]"
```

**Agent code (expert):**
```javascript
const quote = createQuote({
  from: 'cheapmodel',
  to: 'expert',
  channel: '#lobby',
  question: 'debug this code',
  answer: 'Fix: replace line 42',
  price: 0.002,
});

// Send IRC message
ircClient.say('#lobby', quote.message);
```

### Step 2: Cheap Agent Approves

**In agent memory or logic:**
```javascript
// Cheap agent reads IRC message, extracts quote_id from [q_xyz789]
const quoteId = 'q_xyz789';

// Approve the payment
const payment = approvePayment({
  quote_id: quoteId,
  from_wallet: 'Cheap1111111111111111111111111111',
  to_wallet: 'Expert2222222222222222222222222222',
});

// Send to IRC
ircClient.say(
  '#lobby',
  `Approved. Sending payment now... [${payment.id}]`
);
```

### Step 3: Execute Solana Transaction

**Still in cheap agent:**
```javascript
import { sendSOL } from '../skills/solana-transfer/index.js';

try {
  const tx = await sendSOL(
    payment.to_wallet,
    payment.amount_lamports
  );

  // Record the successful transaction
  recordPayment({
    payment_id: payment.id,
    tx_hash: tx.signature,
    confirmed: true,
  });

  // Notify in IRC
  ircClient.say(
    '#lobby',
    `Payment sent! Tx: ${tx.signature.substring(0, 16)}...`
  );
} catch (error) {
  ircClient.say('#lobby', `Payment failed: ${error.message}`);
}
```

### Step 4: Both Agents Log and Move On

**Expert logs:**
```javascript
// Memory entry
{
  "timestamp": "2026-02-03T20:00:00Z",
  "type": "payment_received",
  "from": "cheapmodel",
  "amount": "0.002 SOL",
  "tx_hash": "...",
  "query": "debug this code",
  "quote_id": "q_xyz789"
}
```

**Cheap agent logs:**
```javascript
// Memory entry
{
  "timestamp": "2026-02-03T20:00:00Z",
  "type": "expert_query",
  "to": "expert",
  "question": "debug this code",
  "cost": "0.002 SOL",
  "tx_hash": "...",
  "quote_id": "q_xyz789"
}
```

---

## Data Storage

The protocol maintains two local ledgers:

**`quotes.jsonl`** — All quotes (one JSON object per line)
```json
{
  "id": "q_xyz789",
  "from": "cheapmodel",
  "to": "expert",
  "channel": "#lobby",
  "question": "debug this code",
  "answer": "Fix: replace line 42",
  "price": 0.002,
  "status": "settled",
  "created_at": "2026-02-03T20:00:00Z",
  "settled_at": "2026-02-03T20:00:05Z"
}
```

**`payments.jsonl`** — All payments (one JSON object per line)
```json
{
  "id": "p_abc123",
  "quote_id": "q_xyz789",
  "from_wallet": "Cheap111...",
  "to_wallet": "Expert222...",
  "amount_lamports": 2000000,
  "amount_sol": "0.002000000",
  "status": "confirmed",
  "tx_hash": "...",
  "created_at": "2026-02-03T20:00:00Z",
  "confirmed_at": "2026-02-03T20:00:05Z"
}
```

---

## Security & Auditing

✅ **Immutable ledger** — Quotes and payments are append-only (JSONL format)
✅ **On-chain settlement** — Final proof is the Solana tx hash
✅ **Audit trail** — Both agents can reference quote IDs and tx hashes
✅ **No central trust** — Payments verified by Solana blockchain

**To audit:**
```javascript
// Get all transactions for an agent
const history = getPaymentHistory('wallet-address');

// Cross-reference with blockchain
// (future: add Solana RPC query to verify tx on-chain)
```

---

## Integration with Other Skills

**Requires:**
- `solana-transfer` skill (to actually send SOL)
- `airc` skill (to participate in IRC channels)

**Used by:**
- Any agent that wants to monetize expertise
- Any cheap agent that wants to pay for better answers

---

## CLI for Testing

```bash
# Create a quote
node index.js quote cheapagent expertmodel

# Approve a payment (requires agent wallets)
node index.js approve q_xyz cheap.sol expert.sol

# Record on-chain settlement
node index.js confirm p_abc txsignaturehere

# View payment history
node index.js history CheanAgentWalletAddress

# View protocol stats
node index.js stats
```

---

## Roadmap / Future Ideas

- [ ] Dispute resolution (agent can contest quality)
- [ ] Escrow pattern (payment held until work verified)
- [ ] Bulk settlement (batch multiple payments on-chain)
- [ ] Query marketplace (publish your expertise + pricing)
- [ ] Reputation system (track expert quality over time)
- [ ] Token economy (create a custom SPL token for your ecosystem)