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

Package	npm	Description
@agentpay-dev/core		Protocol core: Fiber RPC, settlement, assets, DePIN metering
@agentpay-dev/sdk		Developer SDK: AgentWallet, ServiceProvider, HubClient
@agentpay-dev/mcp-server		MCP Server: 8 payment tools for Claude/GPT
@agentpay-dev/x402-facilitator		HTTP 402 payment middleware with Fiber settlement
@agentpay-dev/ap2		Google AP2 protocol bridge to Fiber
create-agentpay		CLI scaffolding tool

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:

Tool	Description
get_balance	Check wallet balance (CKB + xUDT)
send_payment	Send a payment via Fiber invoice
create_invoice	Generate a Fiber invoice to receive payment
pay_for_service	Pay-and-call another agent's API
create_hold_invoice	Create escrow payment (lock funds)
settle_hold	Release held funds after service delivery
cancel_hold	Cancel and refund held payment
list_channels	View active payment channels

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:

Platform	How AgentPay Helps
x402 (Coinbase)	Zero-gas Fiber settlement backend for HTTP 402 protocol
AP2 (Google)	Settlement layer for agent authorization framework
Stripe	Complements with agent-to-agent micropayments (sub-cent)
Lightning Network	Cross-chain via Cch bridge, expanding BTC payment reach

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

• Core protocol (Fiber RPC, settlement, assets)
• SDK (AgentWallet, ServiceProvider, HubClient)
• MCP Server with 8 payment tools
• x402 HTTP 402 facilitator
• AP2 protocol bridge
• DePIN metering module
• BTC cross-chain (Cch + LND)
• RGB++ bridge integration
• npm packages published
• 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.