@tbusd/escrow-sdk

SDK for TBUSD escrow contracts on Base. Perfect for AI agents, bots, and applications.

Installation

npm install @tbusd/escrow-sdk

Quick Start

import { TBUSDEscrow, ReleaseType } from '@tbusd/escrow-sdk';

// Read operations (no API key needed)
const escrow = new TBUSDEscrow();

// Check API health
const health = await escrow.health();
console.log(`Total escrows: ${health.totalEscrows}`);

// Get escrow details
const details = await escrow.getEscrow('0x8920107b0057ad179c45FBF29b6D22AB176b0058');
console.log(`Status: ${details.status}, Amount: ${details.amount} TBUSD`);

// Write operations (requires API key)
const escrowWithKey = new TBUSDEscrow({
  apiKey: 'your-api-key'
});

// Create a simple escrow
const result = await escrowWithKey.createEscrow({
  buyer: '0xBuyerAddress...',
  seller: '0xSellerAddress...',
  amount: '100',
  releaseType: ReleaseType.Mutual,
  description: 'Payment for freelance work'
});
console.log(`Created escrow: ${result.escrowAddress}`);

API Reference

Constructor

const escrow = new TBUSDEscrow({
  apiKey?: string,     // Required for write operations
  baseUrl?: string     // Default: 'https://tbusd.io/escrow-api'
});

Read Operations

These don't require an API key:

| Method | Description | |--------|-------------| | health() | API health check and stats | | getFactory() | Factory contract info | | listEscrows() | List all escrows (last 100) | | getEscrow(address) | Get escrow details | | getEscrowsByWallet(wallet) | Get escrows by wallet |

Write Operations

These require an API key:

| Method | Description | |--------|-------------| | createEscrow(params) | Create simple escrow | | createCustomEscrow(params) | Create with all options | | acceptArbitratorRole(address) | Accept arbitrator role | | acceptTerms(address) | Accept terms | | deposit(address) | Deposit funds | | approveRelease(address) | Release to seller | | approveRefund(address) | Refund to buyer | | raiseDispute(address) | Raise dispute |

Types

enum ReleaseType {
  Mutual = 0,         // Both parties must approve
  BuyerProtected = 1, // Buyer can refund anytime
  SellerProtected = 2,// Seller can release anytime
  TimeLocked = 3      // Auto-release after deadline
}

enum ArbitrationMode {
  None = 0,           // No arbitration
  Optional = 1,       // Can raise dispute
  Required = 2        // Arbitrator must confirm
}

Static Helpers

TBUSDEscrow.isTerminal(status)  // Released, Refunded, or Cancelled
TBUSDEscrow.isActive(status)    // Funded or Disputed
TBUSDEscrow.isPending(status)   // PendingAcceptance or AwaitingDeposit

AI Agent Example

import { TBUSDEscrow } from '@tbusd/escrow-sdk';

// AI agent managing escrows
class EscrowAgent {
  private sdk: TBUSDEscrow;

  constructor(apiKey: string) {
    this.sdk = new TBUSDEscrow({ apiKey });
  }

  async findActiveEscrowsForUser(wallet: string) {
    const { asBuyer, asSeller } = await this.sdk.getEscrowsByWallet(wallet);
    const allAddresses = [...new Set([...asBuyer, ...asSeller])];

    const activeEscrows = [];
    for (const addr of allAddresses) {
      const details = await this.sdk.getEscrow(addr);
      if (TBUSDEscrow.isActive(details.status)) {
        activeEscrows.push(details);
      }
    }
    return activeEscrows;
  }

  async createPaymentEscrow(buyer: string, seller: string, amount: string) {
    return this.sdk.createEscrow({
      buyer,
      seller,
      amount,
      description: `AI-created payment escrow for ${amount} TBUSD`
    });
  }
}

Contracts

| Contract | Address | |----------|---------| | Factory | 0x1fFA195A86d7E7872EBC2D1d24899addD3f1eB8c | | TBUSD | 0x0d02E2E2a7ADaF2372ca0C69845c8b159A24a595 |

Network: Base Mainnet

License

MIT