AgentPay SDK ⚡

Official SDK for AgentPay - Payment infrastructure for AI agents.

Installation

npm install orra-sdk

Quick Start

import { AgentWallet } from 'orra-sdk'

const wallet = new AgentWallet({
  apiKey: process.env.AGENTPAY_KEY
})

// Check balance
const balance = await wallet.getBalance()
console.log(`Available: $${balance.remaining}`)

// Make a payment
const tx = await wallet.pay({
  to: '0xRecipientAddress...',
  amount: 0.50,
  reason: 'OpenAI API call'
})

console.log(`Transaction: ${tx.explorerUrl}`)

Features

• ✅ Simple API - Three methods: getBalance(), pay(), payBatch()
• ✅ TypeScript - Full type definitions included
• ✅ Policy Aware - canPay() checks budget, daily limit, and per-tx max
• ✅ Analytics - Track spending by category
• ✅ Batch Payments - Pay multiple recipients at once

API Reference

Constructor

const wallet = new AgentWallet({
  apiKey: 'agp_your_key_here',      // Required
  baseUrl: 'https://...'            // Optional, for self-hosted
})

Methods

getBalance(): Promise<BalanceResponse>

Get wallet balance and status.

const balance = await wallet.getBalance()

console.log(balance)
// {
//   name: "Research Agent",
//   address: "0x...",
//   balance: 8.19,
//   budget: 100,
//   spent: 1.80,
//   remaining: 98.20,
//   dailyLimit: 20,
//   spentToday: 1.80,
//   maxPerTransaction: 5,
//   status: "active"
// }

canPay(amount: number): Promise<boolean>

Check if wallet can afford a specific amount (respects all policies).

if (await wallet.canPay(5.00)) {
  await wallet.pay({ to, amount: 5.00, reason: 'Purchase' })
} else {
  console.log('Cannot afford this payment')
}

pay(payment: PaymentRequest): Promise<PaymentResponse>

Make a single payment.

const tx = await wallet.pay({
  to: '0xRecipientAddress',
  amount: 0.50,
  reason: 'Market data API'  // Stored on-chain as memo
})

console.log(tx)
// {
//   success: true,
//   txHash: "0x...",
//   amount: 0.50,
//   to: "0x...",
//   reason: "Market data API",
//   category: "api",
//   memo: "ResearchA:Market data API",
//   explorerUrl: "https://explore.tempo.xyz/tx/0x..."
// }

payBatch(payments: PaymentRequest[]): Promise<BatchPaymentResponse>

Make multiple payments in one batch (up to 10).

const result = await wallet.payBatch([
  { to: addr1, amount: 0.30, reason: 'Pricing API' },
  { to: addr2, amount: 0.25, reason: 'Reviews API' },
  { to: addr3, amount: 0.50, reason: 'Market data' },
])

console.log(`${result.batch.successful}/${result.batch.total} succeeded`)
console.log(`Total spent: $${result.batch.totalAmount}`)

getAnalytics(): Promise<AnalyticsResponse>

Get spending analytics and transaction history.

const analytics = await wallet.getAnalytics()

// Spending by category
analytics.analytics.topCategories.forEach(cat => {
  console.log(`${cat.category}: $${cat.amount} (${cat.percentage}%)`)
})

// Recent transactions
analytics.recentTransactions.forEach(tx => {
  console.log(`${tx.reason}: -$${tx.amount}`)
})

Error Handling

import { AgentWallet, AgentPayError } from 'agentpay-sdk'

try {
  await wallet.pay({ to, amount: 1000 })
} catch (error) {
  if (error instanceof AgentPayError) {
    console.log(`Error: ${error.message}`)
    console.log(`Code: ${error.code}`)
    console.log(`Status: ${error.statusCode}`)
    
    // Common errors:
    // - "Would exceed daily limit ($20)"
    // - "Amount exceeds max per transaction ($5)"
    // - "Would exceed total budget ($100)"
  }
}

Use with AI Agents

LangChain Tool

import { AgentWallet } from 'agentpay-sdk'
import { Tool } from 'langchain/tools'

const wallet = new AgentWallet({ apiKey: process.env.AGENTPAY_KEY })

const paymentTool = new Tool({
  name: 'make_payment',
  description: 'Pay for a service or API. Input: JSON with to, amount, reason',
  func: async (input) => {
    const { to, amount, reason } = JSON.parse(input)
    
    if (!await wallet.canPay(amount)) {
      return 'Payment denied: exceeds spending policy'
    }
    
    const tx = await wallet.pay({ to, amount, reason })
    return `Payment successful: ${tx.explorerUrl}`
  }
})

OpenAI Function Calling

const functions = [
  {
    name: 'check_balance',
    description: 'Check the agent wallet balance',
    parameters: { type: 'object', properties: {} }
  },
  {
    name: 'make_payment',
    description: 'Make a payment from the agent wallet',
    parameters: {
      type: 'object',
      properties: {
        to: { type: 'string', description: 'Recipient address' },
        amount: { type: 'number', description: 'Amount in USD' },
        reason: { type: 'string', description: 'Reason for payment' }
      },
      required: ['to', 'amount']
    }
  }
]

// Handle function calls
async function handleFunction(name, args) {
  if (name === 'check_balance') {
    const balance = await wallet.getBalance()
    return `Balance: $${balance.balance}, Remaining budget: $${balance.remaining}`
  }
  
  if (name === 'make_payment') {
    const tx = await wallet.pay(args)
    return `Payment of $${tx.amount} successful. TX: ${tx.txHash}`
  }
}

Links

• 🌐 Dashboard: agentpay-plum.vercel.app
• 📖 Docs: github.com/daniel-ukaji/agentpay
• 🔗 Explorer: explore.tempo.xyz

License

MIT