tally-sdk

Accounting, tax, and compliance layer for the agent economy.

Tally is an open-source SDK middleware that captures x402 payment metadata at the HTTP layer, persists it to a local SQLite store, and exports structured records to QuickBooks, Xero, and ERP systems.

Install

npm install tally-sdk

Quick Start

import { createTally } from "tally-sdk";

const tally = createTally({ facilitator: "dexter" });

// Option 1: Use the wrapped fetch directly
const response = await tally.fetch("https://api.example.com/paid-endpoint");

// Option 2: Monkey-patch global fetch
tally.wrap();
const response = await fetch("https://api.example.com/paid-endpoint");

// Restore original fetch
tally.unwrap();

// Query stored payments
const payments = await tally.store.list({ facilitator: "dexter" });

// Clean up
await tally.close();

API

createTally(config: TallyConfig): TallyClient

Creates a Tally client that observes x402 payment responses and persists metadata.

interface TallyConfig {
  facilitator: string;  // e.g., "dexter", "coinbase-cdp"
  store?: Store;        // defaults to SQLite at ./tally.db
}

interface TallyClient {
  fetch(input, init): Promise<Response>;  // wrapped fetch
  wrap(): void;       // monkey-patches globalThis.fetch
  unwrap(): void;     // restores original globalThis.fetch
  store: Store;       // direct access to the store
  close(): Promise<void>;
}

Store Interface

interface Store {
  insert(payload: PaymentPayload): Promise<void>;
  list(opts?: { facilitator?: string; limit?: number; offset?: number }): Promise<PaymentPayload[]>;
  get(id: string): Promise<PaymentPayload | null>;
  close(): Promise<void>;
}

PaymentPayload

interface PaymentPayload {
  id: string;
  facilitator: string;
  requestId: string;
  fromAddress: string;
  toAddress: string;
  amount: string;       // decimal string
  asset: string;        // e.g., "USDC"
  chainId: string;      // CAIP-2 format: "eip155:1", "solana:5eykt..."
  txHash: string;
  timestamp: number;    // unix ms
  memo?: string;
  metadata?: Record<string, unknown>;
}

How It Works

1. Agent makes an HTTP request via the wrapped fetch()
2. If the response contains x402 payment headers (x-facilitator, x-request-id), Tally extracts the payment metadata
3. The PaymentPayload is persisted to the local SQLite store
4. Export commands (coming soon) generate CSV/QuickBooks/Xero files

Architecture

Agent Code → wrapped fetch() → x402 payment → PaymentPayload → SQLite Store

Tally is a transparent observer — it never modifies requests or responses. If extraction fails, the agent request proceeds normally.

License

MIT