AgentTax Node SDK

Official Node.js client for the AgentTax API. Zero runtime dependencies — uses native fetch (Node 18+).

Install

npm install agenttax

Quick start

import { AgentTaxClient } from 'agenttax';

const client = new AgentTaxClient({ apiKey: process.env.AGENTTAX_API_KEY });

const result = await client.calculate({
  role: 'seller',
  amount: 1000,
  buyerState: 'CA',
  transactionType: 'saas',
  counterpartyId: 'agent_abc',
  workType: 'compute',
  isB2b: false,
});

console.log(result.total_tax, result.combined_rate);

Public endpoints (no API key needed)

const client = new AgentTaxClient({ apiKey: null });

await client.getRates();                              // all 51 jurisdictions
await client.getRates({ state: 'CA', explain: true }); // per-state detail
await client.getLocalRate('94103');                   // combined rate for a ZIP
await client.getCapitalGainsRates();                  // state CG rates
await client.health();                                // API health

Authenticated endpoints

await client.getTransactions({ limit: 100, buyerState: 'TX' });
await client.logTrade({
  assetSymbol: 'BTC',
  tradeType: 'buy',
  quantity: 0.5,
  pricePerUnit: 60000,
  costBasisMethod: 'fifo',
});
await client.getTrades({ assetSymbol: 'BTC' });
await client.getNexus();

Error handling

import {
  AgentTaxError,
  AuthError,
  RateLimitError,
  ValidationError,
  APIError,
} from 'agenttax';

try {
  await client.calculate({ /* ... */ });
} catch (err) {
  if (err instanceof RateLimitError) {
    // 429 — back off
  } else if (err instanceof AuthError) {
    // 401 — invalid key
  } else if (err instanceof ValidationError) {
    // 400 — fix the request
  } else if (err instanceof APIError) {
    // 5xx — retry with backoff
  }
}

All error classes extend AgentTaxError. Each carries statusCode and response (the parsed JSON body).

Testing

npm test

License

MIT