Buy from code with the SDK

npm install @zanora/sdk

import { readFileSync } from "node:fs";
import { ZanoraAgent } from "@zanora/sdk";

const agent = new ZanoraAgent({
  apiKey: process.env.ZANORA_API_KEY!,                     // workspace key: authenticates API calls
  walletId: "wal_f33b5618…",                               // the agent's wallet
  agentId: "invoice-bot",                                  // appears on payment proofs
  privateKeyPem: readFileSync("agent-key.pem", "utf8"),    // signs payment proofs
  maxPriceMicros: 5_000_000n,                                     // refuse to sign above $5.00
});

const { results } = await agent.discover({
  query: "extract text from invoices",
  category: "OCR",           // optional filters
  protocol: "rest",
  maxPriceMicros: "2000000",      // a string, in micro-dollars: $2.00
  maxLatencyMs: 3000,
  limit: 5,
});

for (const r of results) {
  console.log(r.capability.name, r.capability.priceMicros, r.provider.name, r.provider.verified, r.score);
}

const result = await agent.invoke<{ text: string }>(best.version.endpoint, {
  body: { imageUrl: "https://example.com/invoice.png" },   // sent as JSON
  // method: "POST" (default), headers: {...}, signal: AbortSignal
});

result.data;                   // the seller's response, typed
result.receipt;                // the signed receipt
result.receiptVerified;        // Zanora signed it
result.responseHashVerified;   // …and it's for this exact response
result.transactionId;

npm install @zanora/mcp

import { resolveCapabilityAddress } from "@zanora/core";
import { StreamableHttpMcpToolCaller } from "@zanora/mcp";

const agent = new ZanoraAgent({ /* …as above… */ mcpCaller: new StreamableHttpMcpToolCaller() });

const { results } = await agent.discover({ query: "invoice OCR", protocol: "mcp" });
const best = results[0]!;

const result = await agent.invokeMcp(resolveCapabilityAddress(best.version), {
  tool: best.capability.toolName!,
  arguments: { imageUrl: "https://example.com/invoice.png" },
});
result.mcpResult;   // the seller's MCP result, unmodified: content blocks, structuredContent, _meta

const r = best.capability.protocol === "mcp"
  ? await agent.invokeMcp(resolveCapabilityAddress(best.version), { tool: best.capability.toolName!, arguments: args })
  : await agent.invoke(best.version.endpoint, { body: args });

const result = await agent.invoke("https://api.example.com/weather", { method: "GET" });
result.external?.receipt; // Zanora's signed record: nonRefundable: true, sellerAttested: false

import { ZanoraPaymentError, ZanoraPolicyRejection } from "@zanora/sdk";

try {
  const r = await agent.invoke(url, { body });
} catch (err) {
  if (err instanceof ZanoraPolicyRejection) {
    // The gateway refused the payment. Nothing was charged.
    // err.code: "POLICY_DENIED" | "APPROVAL_REQUIRED" | "INSUFFICIENT_FUNDS" | "WALLET_FROZEN" | …
    // err.decision?.matchedRule, err.approvalId
  } else if (err instanceof ZanoraPaymentError) {
    // Your client refused before paying. Nothing was charged.
    // err.code: "PRICE_ABOVE_CLIENT_LIMIT" | "CANCELLED" | "INVALID_CHALLENGE" | "MCP_TRANSPORT_UNAVAILABLE"
  } else {
    // e.g. TypeError("fetch failed"): the seller's URL wasn't reachable. The call never got as far as a price.
    throw err;
  }
}

const ac = new AbortController();
setTimeout(() => ac.abort(), 2000);
await agent.invoke(url, { body, signal: ac.signal });
// → ZanoraPaymentError("CANCELLED"): nothing was charged. The only code that guarantees that.

await agent.rateProvider(best.provider.id, result.receipt!.transactionId, 5);  // 1–5, once per purchase
await agent.verifyReceipt(result.receipt!);   // re-check any receipt, including an old one
await agent.balance();                        // { balanceMicros, availableMicros, currency }