io.github.alefnt/agentpay

AgentPay - BTC-Native AI Agent Payment Protocol

Give every AI Agent a wallet. Let Agents pay each other - instantly, with zero fees.

AgentPay is a BTC-native payment protocol designed for AI Agent economies. Built on CKB Fiber Network (Lightning-compatible L2), it enables:

• Zero-gas micropayments - Pay per API call, no minimum amount
• Hold Invoice escrow - Lock funds until service delivery is confirmed
• BTC interoperability - Cross-chain payments via Lightning Network
• MCP integration - Let Claude/GPT agents make payments natively

Quick Start

Install

npm install @agentpay-dev/sdk @agentpay-dev/core

Create a Payment Agent

import { AgentWallet } from '@agentpay-dev/sdk';

const wallet = new AgentWallet({ fiberRpcUrl: process.env.FIBER_RPC_URL });

// Pay another agent for a service
const result = await wallet.payAndCall(
  'https://translator-agent.example.com',
  'translate',
  { text: 'Hello World', target: 'zh' }
);

Scaffold a New Project

npx create-agentpay my-agent
cd my-agent && npm install

Architecture

+-----------------------------------------------------+
|                    Applications                      |
|  AI Agents  |  DePIN Devices  |  API Marketplaces    |
+-----------------------------------------------------+
|                   AgentPay SDK                       |
|  AgentWallet  |  ServiceProvider  |  HubClient       |
+-----------------------------------------------------+
|                   AgentPay Core                      |
|  Settlement  |  Metering  |  DID  |  Assets          |
+-----------------------------------------------------+
|              CKB Fiber Network (L2)                  |
|  Payment Channels  |  Hold Invoice  |  HTLC Routing  |
+-----------------------------------------------------+
|         CKB L1  +  BTC Lightning Network             |
|    xUDT Assets  |  RGB++  |  Cross-chain (Cch)       |
+-----------------------------------------------------+

Packages

Key Features

Hold Invoice - Trustless Escrow

The killer feature. Agent A locks payment, Agent B delivers, funds release only on confirmation:

import { ServiceProvider } from '@agentpay-dev/sdk';

const provider = new ServiceProvider({
  fiberRpcUrl: process.env.FIBER_RPC_URL,
  services: {
    translate: {
      price: 100_000_000n,  // 1 CKB per request
      handler: async (params) => {
        const result = await doTranslation(params.text, params.target);
        return { translation: result };
      }
    }
  }
});

// Hold flow: Lock -> Deliver -> Release (atomic)
// If service fails, funds auto-refund via HTLC timeout

MCP Server - AI-Native Payments

Registered on the official MCP Registry as io.github.alefnt/agentpay.

Add to Claude Desktop config:

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["@agentpay-dev/mcp-server"],
      "env": { "FIBER_RPC_URL": "http://localhost:8227" }
    }
  }
}

8 MCP Tools:

x402 HTTP Compatibility

Any HTTP API becomes a paid API with one middleware:

import { createX402Middleware } from '@agentpay-dev/x402-facilitator';

const paywall = createX402Middleware({ price: '100000000' });

http.createServer((req, res) => {
  paywall(req, res, () => {
    res.end(JSON.stringify({ data: 'premium content' }));
  });
});
// Client: HTTP 402 -> pay Fiber invoice -> retry -> get content

BTC Cross-Chain

Pay with BTC, settle on CKB via Lightning-Fiber bridge:

import { CchClient } from '@agentpay-dev/core';

const cch = new CchClient({ cchRpcUrl: process.env.CCH_RPC_URL });

await cch.sendBtcToCkb({
  btcPayReq: 'lnbc100n1p...',
  fiberChannelId: '0x...',
});

Ecosystem Integration

AgentPay enhances existing payment solutions:

Project Structure

AgentPay/
  packages/
    core/               # Protocol core (Fiber RPC, settlement, DePIN)
    sdk/                # Developer SDK (Wallet, Provider, Hub)
    mcp-server/         # MCP Server for AI agents
    x402-facilitator/   # HTTP 402 middleware
    ap2/                # Google AP2 bridge
    create-agentpay/    # CLI scaffolding
  services/
    hub/                # Hosted wallet service
    registry/           # Agent discovery service
  examples/
    translate-agent/    # Translation service example
    code-review-agent/  # Code review agent example
    btc-to-ckb/         # Cross-chain payment example
  docs/
    product.md          # Product overview
    architecture.md     # Technical architecture

Documentation

• Product Overview - What AgentPay solves and how
• Architecture - Technical design and protocol layers
• Competitive Analysis - Comparison with x402, AP2, Stripe

Tech Stack

• Runtime: Node.js 20+ / TypeScript 5.5+
• L2 Network: CKB Fiber Network (Lightning-compatible)
• L1 Blockchain: Nervos CKB
• Asset Standard: xUDT (extensible User Defined Token)
• Identity: .bit decentralized identity
• Cross-chain: Cch (CKB - BTC Lightning bridge)
• AI Integration: Model Context Protocol (MCP)
• Build: pnpm workspace monorepo

Development

git clone https://github.com/alefnt/AgentPay.git
cd AgentPay
pnpm install
pnpm build
pnpm test

Roadmap

• [x] Core protocol (Fiber RPC, settlement, assets)
• [x] SDK (AgentWallet, ServiceProvider, HubClient)
• [x] MCP Server with 8 payment tools
• [x] x402 HTTP 402 facilitator
• [x] AP2 protocol bridge
• [x] DePIN metering module
• [x] BTC cross-chain (Cch + LND)
• [x] RGB++ bridge integration
• [x] npm packages published
• [x] MCP Registry registration
• [ ] Fiber mainnet deployment
• [ ] Stablecoin (RUSD) support on CKB
• [ ] Public demo site
• [ ] Production Hub service

License

MIT - see LICENSE for details.

Built for the Agent Economy - where AI agents autonomously discover, negotiate, and pay for services.