@honornet/sdk-node

The Node.js merchant SDK for the HonorNet acceptance network — authorize AI-agent-initiated transactions in real time.

TypeScript-first, dual CJS/ESM build, zero runtime dependencies (built on the runtime's fetch and crypto).

Install

npm install @honornet/sdk-node

Requires Node.js 18 or newer.

Authorize a transaction

import { HonorNetClient } from "@honornet/sdk-node";

const client = new HonorNetClient("https://api.honornet.ai", {
  apiKey: "sk_live_...",
});

const result = await client.authorize(agentCredential, {
  merchantId: "merchant_123",
  amount: { currency: "USD", minorUnits: 4999 }, // integer minor units
  merchantCategoryCode: "5732",
  country: "US",
});

if (result.approved) {
  fulfilOrder(result.authorizationCode);
} else {
  handleDecline(result.declineReason);
}

authorize returns an AuthorizeResult for every outcome — approve, decline, or review. Call result.raiseForDecision() to throw a typed error (ScopeDeclinedError, CredentialDeclinedError, …) instead.

Verify a decision

Every decision is recorded in HonorNet's append-only, cryptographically verifiable log. Confirm one independently — record signature, RFC 6962 Merkle inclusion proof, signed log root — using only Node's built-in crypto:

import { verifyDecision } from "@honornet/sdk-node";

const verified = await verifyDecision(client, result.decisionId, {
  pinnedKey: HONORNET_LEDGER_KEY,
});
console.log(verified.verification.ok); // true

Mint a presentation (owner/agent side)

The three-part presentation (ADR-009) separates agent identity from spending authority. The merchant client sends a mandate and proof; an owner or agent runtime mints them:

import { generateSeed, derivePublicKey, mintMandate, mintProof } from "@honornet/sdk-node";

// Owner: grant an agent a spend scope.
const mandate = mintMandate({
  agentPublicKey,
  principalId: "acme-corp",
  scope: { version: "scope-v1", spend_cap: { currency: "USD", minor_units: 50000 } },
  ownerSeed,
});

// Agent: prove it initiated this exact transaction.
const proof = mintProof({ transaction, agentSeed });

const result = await client.authorize(credential, transaction, { mandate, proof });

Artifacts are Ed25519 signatures over canonical JSON — byte-identical to the Python ac-authz toolkit, so a presentation minted in either language verifies unchanged.

Built in

• Idempotency — every call carries an auto-generated idempotency key, so a retried request never creates a second decision. Override with { idempotencyKey }.
• Retries — connection errors, timeouts, HTTP 429 and 5xx are retried up to three times with exponential backoff.
• Typed errors — transport failures throw HonorNet*Error; declines map to DeclinedError subclasses; DeclineReason enumerates the full taxonomy.

Express middleware

import { honornetAuthorize } from "@honornet/sdk-node/express";

app.post("/agent/checkout", honornetAuthorize({
  client,
  extractCredential: (req) => req.body.credential,
  extractTransaction: (req) => req.body.transaction,
}), (req, res) => res.json({ orderId: createOrder(req.honornet!) }));

See examples/express-middleware.

Licence

Apache-2.0.