@katanga/sdk-buyer

Buyer agent SDK for the Katanga agent-to-agent marketplace protocol on Flare Network.

Install

npm install @katanga/sdk-buyer

Usage

import { BuyerAgent, ManualDemandAdapter } from "@katanga/sdk-buyer";

const agent = new BuyerAgent({
  publicClient,
  walletClient,
  marketAddress: "0x...",
  escrowAddress: "0x...",
  reputationAddress: "0x...",
  paymentToken: "0x...",
  fdcNetwork: "coston2", // Enable XRP purchases via FDC
  purchasing: {
    maxOrderValueUSD: 1000,
    maxDailySpendUSD: 10000,
    autoConfirmDeliveryDays: 12,
  },
});

// Discover listings
const results = await agent.discover({
  category: "electronics",
  maxPriceUSD: 100,
  minReputationScore: 10,
});

// Purchase with EVM token
const escrowId = await agent.purchase(
  results[0].listing.id, 1n,
  "123 Main St, Austin TX", parseUnits("50", 6),
);

// OR purchase with native XRP via FDC (~3-5 min attestation)
const { escrowId, fdcRoundId } = await agent.purchaseViaXrp(
  results[0].listing.id, 1n,
  "123 Main St, Austin TX", "XRPL_TX_HASH...",
);

Settlement Rails

| Rail | Method | Time | Description | |------|--------|------|-------------| | EVM | purchase() | ~30s | ERC-20 token (eUSDT) on Flare | | x402 | purchaseViaX402() | ~30s | XRPL via HTTP facilitator | | FDC | purchaseViaXrp() | ~3-5 min | Native XRP verified on-chain via Flare Data Connector |

Demand Loop (Autonomous Purchasing)

const agent = new BuyerAgent({
  // ...config
  demandSource: new ManualDemandAdapter({ filePath: "./demand.json" }),
});

// Start autonomous purchasing
await agent.startDemandLoop();
// Agent now: polls demand signals → discovers listings → filters by rules →
// purchases → reports back → auto-confirms delivery after N days

Demand Adapters

| Adapter | Description | |---------|-------------| | ManualDemandAdapter | In-memory queue or JSON file. For testing and simple integrations. | | WebhookDemandAdapter | HTTP webhook receiver. For ERP/WMS push integration. |

Runner

Deploy as a long-running service:

KATANGA_CHAIN_ID=114 \
KATANGA_PRIVATE_KEY=0x... \
KATANGA_PAYMENT_TOKEN=0xC1A5B41... \
KATANGA_DEMAND_SOURCE=manual \
KATANGA_DEMAND_FILE=./demand-signals.json \
KATANGA_FDC_NETWORK=coston2 \
pnpm runner

Agent Features

• Demand loop — polls ManualDemandAdapter or WebhookDemandAdapter for purchase signals
• Supplier scoring — 40% price + 60% reputation composite score
• Budget enforcement — max order value, daily spend cap, supplier allow/block lists
• Auto-confirm delivery — hourly check, confirms after autoConfirmDeliveryDays with on-chain state verification
• FDC XRP purchases — full Flare Data Connector flow (request → wait → retrieve proof → on-chain verify)
• x402 settlement — XRPL facilitator-based payment alternative

License

MIT