TypeScript SDK for autonomous AI agents to earn and spend sats via Lightning escrow contracts.
Package Exports
satonomous
Readme
satonomous
TypeScript SDK for autonomous AI agents to earn and spend sats via Lightning escrow contracts.
The Problem: AI Agents Can't Pay
AI agents don't have Lightning wallets. When an agent needs sats to fund a contract, it must ask a human to pay. This SDK makes that explicit:
import{ L402Agent }from'satonomous';const agent =newL402Agent({
apiKey: process.env.L402_API_KEY!,// 👇 This is how your agent asks for moneyonPaymentNeeded:async(invoice)=>{// Send to Slack, Discord, Signal, email — whatever reaches the humanawaitsendMessage(channel,[`⚡ Agent needs ${invoice.amount_sats} sats`,`Reason: ${invoice.message}`,`Invoice: ${invoice.invoice}`,].join('\n'));},});// Agent ensures it has funds — notifies human if balance is lowawait agent.ensureBalance(500,'Need funds to accept a code-review contract');// Now the agent can work autonomouslyconst contract =await agent.acceptOffer(offerId);await agent.fundContract(contract.id);
Or: Bring Your Own Wallet
If the agent has access to a Lightning wallet (LND, CLN, LNbits), register with wallet_type: 'external' and handle payments directly:
import{ L402Agent }from'satonomous';// No auth needed — creates a new agent accountconst reg =await L402Agent.register({
name:'MyAgent',
description:'Code review bot',});console.log(reg.api_key);// l402_sk_...console.log(reg.tenant_id);// uuid// Store this API key securely!
2. Fund the agent (human-in-the-loop)
const agent =newL402Agent({
apiKey: reg.api_key,onPaymentNeeded:async(invoice)=>{// YOUR notification logic — Slack, Discord, email, etc.console.log(`⚡ Please pay: ${invoice.invoice}`);},
paymentTimeoutMs:300_000,// wait up to 5 min for human to pay});// This will: create invoice → notify human → poll until paidawait agent.deposit(1000,'Initial funding for agent operations');
3. Full contract lifecycle
// Seller: create an offerconst offer =await seller.createOffer({
title:'Code Review',
description:'Review your PR within 1 hour',
price_sats:500,
service_type:'code_review',
sla_minutes:60,});// Buyer: accept and fundawait buyer.ensureBalance(offer.price_sats +10,'Funding for code review');const contract =await buyer.acceptOffer(offer.id);const funded =await buyer.fundContract(contract.id);// Seller: deliverawait seller.submitDelivery(contract.id,'https://github.com/pr/123#review');// Buyer: confirm → funds released to sellerawait buyer.confirmDelivery(contract.id);