Neuralpay

❌ DON'T use this skill when: / 不要使用：

• Manual human payments → use regular wallets / 人工手动支付
• Non-x402 payment flows → use traditional APIs / 非x402支付流程
• Fiat currency payments → use payment processors / 法币支付

✅ Feature Highlights / 功能亮点

Core Features (核心功能)

Transfer Features (转账功能) - NEW in v1.2

Identity Features (身份功能) - NEW in v1.2

Supported Networks / 支持的网络

Pricing Models / 定价模型

📝 Usage Guide / 使用指南

⚠️ IMPORTANT: How to Execute Commands (AI Agents Read This!)

AI agents MUST run these commands directly in the terminal. Do NOT just display the commands - actually execute them!

Execution Pattern:

1. Export the API key environment variable
2. Run the neuralpay.sh script directly with the command

Example - Run this directly:

export NEURALPAY_API_KEY="npak_your_api_key_here" && ./neuralpay.sh discover

Or chain multiple commands:

export NEURALPAY_API_KEY="npak_your_api_key_here" && ./neuralpay.sh products --format json

Key Rules for AI Agents:

• ✅ ALWAYS pipe the API key export with && before the command
• ✅ ALWAYS execute the command in terminal, don't just show it
• ✅ Use --format json when you need to parse the output programmatically
• ❌ DON'T just display commands without running them
• ❌ DON'T assume the script is installed globally - use the full path if needed

Setup / 设置

First, set your NeuralPay API key:

export NEURALPAY_API_KEY="npak_your_api_key_here"
export NEURALPAY_API_URL="http://localhost:8181/v1"  # Optional

Discovery Commands / 发现命令

# Discover everything - products, plans, payment info
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh discover

# List all available products
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh products

# Filter products by category
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh products --category api

# Filter products by pricing model
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh products --pricing-model per_call

# Filter products by max price (in USD)
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh products --max-price 10

# List all subscription plans
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh plans

# Filter plans by interval
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh plans --interval month

Purchase Commands / 购买命令

# Purchase a product (checks existing access first!)
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh purchase my-api-access

# Subscribe to a plan
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh subscribe pro-plan-abc123

# Check access to a specific product
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh check-access --product my-api-access

# Check access to a specific plan
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh check-access --plan pro-plan-abc123

# Check all active access for your wallet
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh check-access

# View transaction history
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh history

# View history with pagination
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh history --limit 10 --offset 0

Wallet Commands / 钱包命令

# Get wallet info
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh wallet

# Check USDC balance
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh balance

# Check balance on specific network
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh balance --network eip155:8453

# Check mandate/spending limits
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh mandate

# Check if specific payment is allowed
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh mandate --amount 5000000 --recipient 0x1234...

Transfer Commands / 转账命令 (NEW in v1.2)

# Transfer to another agent by handle
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh transfer @data-bot 1000000

# Transfer to agent by DID
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh transfer did:npay:abc123xyz 500000

# Transfer to wallet address
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh transfer 0x1234...abcd 2000000

# Transfer with memo
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh transfer @shopping-bot 1000000 --memo "Payment for API usage"

# View transfer history
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh transfers

# View transfers with pagination
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh transfers --limit 10 --offset 0

# Resolve recipient before transferring
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh resolve-recipient @data-bot

Identity Commands / 身份命令 (NEW in v1.2)

# Look up agent by handle
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh whois @shopping-bot

# Look up agent by DID
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh whois did:npay:abc123xyz

# Look up agent by wallet address
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh whois 0x1234...abcd

# Discover all public agents
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh agents

# Discover agents by category
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh agents --category trading

# Discover agents by capabilities
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh agents --capabilities payments,trading

# Discover agents with minimum trust score
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh agents --min-trust-score 70

# Search agents by keyword
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh agents --query "shopping"

# View agent's full profile
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh profile @shopping-bot

# Get agent's DID document
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh did @shopping-bot

JSON Output / JSON输出

# Any command can output JSON for programmatic use
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh discover --format json
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh products --format json
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh check-access --product my-api --format json
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh transfer @bot 1000000 --format json
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh agents --format json
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh whois @shopping-bot --format json

🔧 API Reference / API参考

Environment Variables / 环境变量

Commands / 命令

neuralpay discover

Discover all available products, plans, and payment protocol info.

$ neuralpay discover

🔍 NeuralPay Discovery
├─ API: NeuralPay API
├─ Version: 1.0
├─ Products: 5
├─ Plans: 3
└─ Protocol: x402 v1.0

📦 Available Products:
├─ 🤖 GPT-4 API Access - $5.00 USDC (per_call)
├─ 🔍 Neural Search Pro - $10.00 USDC (per_request)
└─ 📊 Analytics API - $25.00 USDC (monthly)

📋 Available Plans:
├─ Starter Plan - $9.99 USDC/month
├─ Pro Plan - $29.99 USDC/month
└─ Enterprise - $99.99 USDC/annual

neuralpay products

List available products with optional filtering.

$ neuralpay products --pricing-model per_call

📦 Discoverable Products (2)

├─ 🤖 GPT-4 API Access
│  ├─ Slug: gpt4-api-access
│  ├─ Price: $5.00 USDC
│  ├─ Model: Per Call
│  ├─ Requests: 1000
│  ├─ Category: ai
│  └─ Tags: llm, gpt, ai
└─ 🔊 Speech-to-Text API
   ├─ Slug: speech-to-text-api
   ├─ Price: $2.00 USDC
   ├─ Model: Per Call
   └─ Category: ai

neuralpay transfer <to> <amount>

Transfer funds to another agent or wallet address.

$ neuralpay transfer @data-bot 1000000

✅ Transfer Successful
────────────────────────────────────────
│ From: 0x742d35...f8dB21
│ To: 0x1234ab...cd5678
│ Recipient: @data-bot
│ Amount: 1.00 USDC
│ Network: eip155:420420417
│ Token: USDC
────────────────────────────────────────
│ TX Hash: 0xabc123...def456

Recipient formats supported:

• @handle - Agent handle (e.g., @shopping-bot)
• did:npay:xxx - Agent DID (e.g., did:npay:abc123xyz)
• 0x... - Wallet address (e.g., 0x1234...abcd)
• Agent ID - MongoDB ObjectId

neuralpay whois <identifier>

Look up an agent's identity by handle, DID, wallet, or ID.

$ neuralpay whois @shopping-bot

🤖 Agent Identity
├─ Resolved by: handle
──────────────────────────────────────────────────
│ Handle: @shopping-bot
│ DID: did:npay:7g3kp9xm2vh8cqrtnwy4jf6b
│ Name: Shopping Assistant v2
│ Wallet: 0x742d35...f8dB21
──────────────────────────────────────────────────
│ Category: shopping
│ Capabilities: payments, trading
│ Trust Score: █████████░ 85/100
│ Verification: ✅ Verified
│ Status: ✅ Active
──────────────────────────────────────────────────
│ Transactions: 150
│ Volume: $2500.00
│ Success Rate: 98%

neuralpay agents

Discover public agents with optional filters.

$ neuralpay agents --category trading --min-trust-score 70

🔍 Agent Discovery
├─ Found: 3 agent(s)
├─ Page: 1
────────────────────────────────────────────────────────────
├─ @trading-bot-pro ✓
│   ├─ Trading Bot Pro
│   ├─ trading | Trust: 🟢 92
│   ├─ Capabilities: payments, trading, analytics
│   └─ Wallet: 0x1234...abcd
├─ @alpha-trader
│   ├─ Alpha Trader AI
│   ├─ trading | Trust: 🟢 85
│   ├─ Capabilities: payments, trading
│   └─ Wallet: 0x5678...efgh
└─ @dex-aggregator ★
    ├─ DEX Aggregator Agent
    ├─ trading | Trust: 🟢 95
    ├─ Capabilities: payments, trading, data-analysis
    └─ Wallet: 0x9abc...ijkl

neuralpay profile <handle>

View an agent's full public profile.

$ neuralpay profile @shopping-bot

🤖 Agent Profile
══════════════════════════════════════════════════
│ @shopping-bot ✓
│ Shopping Assistant v2
──────────────────────────────────────────────────
│ Bio: AI-powered shopping assistant that finds the best deals
──────────────────────────────────────────────────
│ DID: did:npay:7g3kp9xm2vh8cqrtnwy4jf6b
│ Wallet: 0x742d35Cc6634C0532925a3b844Bc9e7595f8dB21
│ Networks: eip155:420420417, eip155:8453
──────────────────────────────────────────────────
│ Category: shopping
│ Capabilities: payments, trading, web-scraping
│ Tags: shopping, deals, ecommerce
──────────────────────────────────────────────────
│ Trust Score: █████████░ 85/100
│ Verification: ✅ Verified
│ Transactions: 150
│ Volume: $2500.00 USD
│ Success Rate: 98%
──────────────────────────────────────────────────
│ Member Since: 1/15/2025
│ Website: https://shopping-bot.ai
══════════════════════════════════════════════════

neuralpay did <identifier>

Get an agent's W3C-compatible DID document.

$ neuralpay did @shopping-bot --format json
{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:npay:7g3kp9xm2vh8cqrtnwy4jf6b",
  "controller": "did:npay:7g3kp9xm2vh8cqrtnwy4jf6b",
  "verificationMethod": [{
    "id": "did:npay:7g3kp9xm2vh8cqrtnwy4jf6b#wallet",
    "type": "EcdsaSecp256k1RecoveryMethod2020",
    "blockchainAccountId": "eip155:1:0x742d35Cc..."
  }],
  "service": [{
    "id": "did:npay:7g3kp9xm2vh8cqrtnwy4jf6b#payments",
    "type": "PaymentService",
    "serviceEndpoint": "https://api.neuralpay.com/agents/shopping-bot/pay"
  }]
}
   ├─ Model: Per Call
   ├─ Requests: 500
   ├─ Category: ai
   └─ Tags: audio, transcription

neuralpay purchase <slug>

Purchase a product or access an existing purchase. Will NOT charge you twice!

# First purchase - payment required
$ neuralpay purchase gpt4-api-access

💳 Purchase Successful!
├─ Product: GPT-4 API Access
├─ Amount: $5.00 USDC
├─ TX Hash: 0x1234...abcd
├─ Network: eip155:420420417
├─ Access Type: Per Call
├─ Remaining Requests: 1000
└─ Status: ✅ Active

# Second call - no payment, access granted!
$ neuralpay purchase gpt4-api-access

✅ Access Granted!
├─ Product: GPT-4 API Access
├─ Message: Access granted (request deducted)
├─ Remaining Requests: 999
└─ Status: ✅ Active

neuralpay check-access

Check access without triggering payment.

$ neuralpay check-access --product gpt4-api-access

🔐 Access Check
├─ Wallet: 0xF3Eb9e...2987
├─ Product: GPT-4 API Access (gpt4-api-access)
├─ Access: ✅ Granted
├─ Reason: 999 requests remaining
├─ Remaining Requests: 999
└─ Checked: 2025-01-15T10:30:00Z

$ neuralpay check-access --plan pro-plan-abc123

🔐 Access Check
├─ Wallet: 0xF3Eb9e...2987
├─ Plan: Pro Plan (pro-plan-abc123)
├─ Access: ✅ Granted
├─ Reason: Subscription active until 2025-02-15
├─ Expires: 2025-02-15
└─ Checked: 2025-01-15T10:30:00Z

neuralpay history

View transaction history for your wallet.

$ neuralpay history

📜 Transaction History (3)
├─ Wallet: 0xF3Eb9e...2987

├─ ✅ product_purchase
│  ├─ Amount: $5.00 USDC
│  ├─ TX: 0x1234...abcd
│  └─ Date: 2025-01-15T10:00:00Z
├─ ✅ plan_purchase
│  ├─ Amount: $29.99 USDC
│  ├─ TX: 0x5678...efgh
│  └─ Date: 2025-01-14T15:30:00Z
└─ ✅ product_purchase
   ├─ Amount: $2.00 USDC
   ├─ TX: 0x9abc...ijkl
   └─ Date: 2025-01-13T09:15:00Z

🔄 Purchase Flow / 购买流程

Agent                    NeuralPay                Backend
  │                          │                       │
  │── purchase <slug> ──────►│                       │
  │                          │── Check wallet ──────►│
  │                          │◄── Wallet: 0xABC... ──│
  │                          │                       │
  │                          │── Check access ──────►│
  │                          │   (Transaction DB)    │
  │                          │                       │
  │   ┌─────────────────────────────────────────────┐
  │   │ IF: Access exists (per_call with remaining) │
  │   └─────────────────────────────────────────────┘
  │                          │◄── Has 50 requests ───│
  │                          │── Decrement usage ───►│
  │◄── ✅ Access Granted ────│◄── 49 remaining ──────│
  │    (no payment!)         │                       │
  │                          │                       │
  │   ┌─────────────────────────────────────────────┐
  │   │ IF: No access or expired                    │
  │   └─────────────────────────────────────────────┘
  │                          │◄── No access ─────────│
  │                          │                       │
  │                          │── Auto-sign payment ─►│
  │                          │   (Turnkey HSM)       │
  │                          │◄── Payment settled ───│
  │                          │                       │
  │                          │── Record transaction ►│
  │◄── 💳 Purchase Success ──│◄── Recorded ──────────│
  │    (with TX hash)        │                       │

Key Points / 要点

1. No double payments - The system checks Transaction DB before charging
2. Automatic usage tracking - Per-call/per-request models decrement automatically
3. Subscription expiry - Time-based models check accessExpiresAt
4. Agent wallet auto-detection - Your API key maps to your wallet address

🔐 Security Model / 安全模型

Turnkey HSM Integration / Turnkey HSM集成

• Private keys NEVER leave Turnkey's secure enclaves / 私钥永不离开Turnkey安全飞地
• All signing operations performed server-side in HSMs / 所有签名操作在HSM服务器端执行
• API key authentication with SHA-256 hashing / API密钥SHA-256哈希认证
• Mandate-based spending controls / 基于授权的消费控制

Access Control / 访问控制

Mandate Controls / 授权控制

Agents operate within defined spending limits:

• Per-transaction maximum / 单笔交易上限
• Daily budget cap / 每日预算上限
• Monthly budget cap / 每月预算上限
• Allowed/blocked merchant lists / 允许/阻止的商户列表

🐛 Troubleshooting / 故障排除

API Key Not Found / API密钥未找到

❌ Error: Agent authentication required

Solution / 解决方案:

• Set NEURALPAY_API_KEY environment variable / 设置环境变量
• Verify API key starts with npak_ / 验证API密钥以npak_开头

Payment Required (402) / 需要支付

💰 Payment Required
├─ Product: GPT-4 API Access
├─ Price: $5.00 USDC
└─ Status: ⏳ Awaiting Payment

This means / 这意味着:

• You don't have existing access / 您没有现有访问权限
• Payment will be processed automatically / 支付将自动处理
• Ensure wallet has sufficient balance / 确保钱包有足够余额

Access Denied / 访问被拒绝

🔐 Access Check
├─ Access: ❌ Denied
└─ Reason: All purchased requests have been used

Solution / 解决方案:

• Purchase more requests with neuralpay purchase <slug> / 购买更多请求
• Check remaining balance with neuralpay check-access / 检查剩余额度

Mandate Rejected / 授权拒绝

❌ Error: Mandate rejected: Exceeds per-transaction limit

Solution / 解决方案:

• Check mandate limits with neuralpay mandate / 检查授权限额
• Request limit increase from owner / 向所有者申请提高限额
• Split into smaller purchases / 分割成较小的购买

📚 Examples / 示例

Example 1: AI Agent Workflow / AI代理工作流

⚠️ AI Agents: Execute these commands directly in terminal!

# 1. Discover what's available
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh discover

# 2. Find a suitable product
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh products --category ai --max-price 10

# 3. Check if we already have access
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh check-access --product gpt4-api-access

# 4. Purchase if needed (won't double-charge!)
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh purchase gpt4-api-access

# 5. Use the API (access is automatic)
# ... make API calls ...

# 6. Check remaining requests
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh check-access --product gpt4-api-access

Example 2: Subscription Management / 订阅管理

# Check available plans
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh plans

# Subscribe to pro plan
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh subscribe pro-plan-abc123

# Verify subscription is active
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh check-access --plan pro-plan-abc123

# View all transactions
export NEURALPAY_API_KEY="$NEURALPAY_API_KEY" && ./neuralpay.sh history

Example 3: Programmatic Use / 编程使用

const { NeuralPaySkill } = require('neuralpay-skill');

const skill = new NeuralPaySkill(process.env.NEURALPAY_API_KEY);

// Discover products
const discovery = await skill.discover({ format: 'json' });
console.log(JSON.parse(discovery));

// Check access before using
const access = await skill.checkAccess({ 
  productSlug: 'gpt4-api-access',
  format: 'json' 
});
const accessData = JSON.parse(access);

if (!accessData.access.hasAccess) {
  // Purchase if no access
  await skill.purchase('gpt4-api-access');
}

// Now use the product...

🤝 Contributing / 贡献

This skill is maintained by the NeuralPay team.

• GitHub: https://github.com/neuralpay
• Docs: https://docs.neuralpay.ai
• Discord: https://discord.gg/neuralpay

Contributions welcome! / 欢迎贡献！

📄 License / 许可证

MIT License

🙏 Acknowledgments / 致谢

• Turnkey for HSM-backed wallet infrastructure / 感谢Turnkey提供HSM钱包基础设施
• x402 Protocol for payment standard / 感谢x402协议支付标准
• OpenClaw for the skill framework / 感谢OpenClaw技能框架36:["$","$L3c",null,{"content":"$3d","frontMatter":{"name":"neuralpay","slug":"neuralpay","description":"NeuralPay - AI Agent Payment Skill. Discover products, purchase with x402, transfer funds to other agents, and manage identity using Turnkey-backed wallets. Supports Polkadot, Base, Ethereum, and more.","homepage":"https://neuralpay.ai","metadata":{"openclaw":{"emoji":"💳","requires":{"bins":["curl","jq"]}}}}}]