OpenAPI 3.1 spec + @hundi/api-client SDK

# npm / pnpm / yarn — preferred
npm  add @hundi/api-client
pnpm add @hundi/api-client
yarn add @hundi/api-client

# Versioned tarball — air-gapped fallback
curl -sLO https://docs.hundi.network/sdk/hundi-api-client-0.1.0.tgz
pnpm add ./hundi-api-client-0.1.0.tgz

# Codegen from OpenAPI spec — any language
npx @openapitools/openapi-generator-cli generate \
  -i https://api.hundi.network/openapi.json \
  -g python \
  -o ./hundi-client

import { HundiClient, HundiApiError } from '@hundi/api-client';

// Unauthenticated — reads only
const client = new HundiClient({
  baseUrl: 'https://api.hundi.network',
});

// Authenticated — HMAC-signs mutating routes
const authedClient = new HundiClient({
  baseUrl: 'https://api.hundi.network',
  credentials: {
    apiKey: process.env.HUNDI_API_KEY!,
    secret: process.env.HUNDI_API_SECRET!,
  },
});

const { quote, risk } = await client.createQuote({
  pair: { base: 'USD', quote: 'INR' },
  side: 'buy',
  notional_base: '10000.00',
  principal_did: 'did:hundi:0xabc...',
  beneficiary_did: 'did:hundi:0xbenef...',
});

// The risk envelope carries the parallel-gate decision (sanctions, KYC,
// limits, agent_scope, velocity). A denial returns 403 with risk.decision
// = 'rejected' and full per-check detail.
if (risk.decision === 'rejected') {
  console.error('Quote rejected:', risk.reasons);
} else {
  const { transaction } = await authedClient.acceptQuote(quote.id, {
    principal_did: 'did:hundi:0xabc...',
    beneficiary_did: 'did:hundi:0xbenef...',
  });
  console.log('Transaction id:', transaction.id);
}

const tx = await client.getTransaction(transactionId);
// tx.status: 'pending' | 'submitting' | 'submitted' |
//            'finalized' | 'failed' | 'blocked' | 'cancelled'

const auditResponse = await client.getTransactionAudit(transactionId);
// auditResponse.events: ordered audit_log entries for this transaction —
// includes IVMS101 packet, sanctions screening result, ZK facts, both
// XRPL hashes (EscrowCreate + EscrowFinish) once finalized.

// For real-time updates instead of polling, subscribe to the WS feed:
// wss://api.hundi.network/v1/stream/events?kinds=transactions.finalized,transactions.blocked

const proof = await client.getAuditProof(auditRowId);
// proof: {
//   leaf_hash,           // sha256(canonical_bytes)
//   leaf_index,
//   proof: [             // Merkle inclusion path
//     { sibling, position: 'left' | 'right' },
//     ...
//   ],
//   root_hash,           // daily Merkle root for proof.date
//   canonical_bytes,     // exact bytes the leaf was hashed from
//   xrpl_anchor_tx_hash, // on-chain anchor (mainnet or testnet)
//   xrpl_ledger_index,
//   anchored_at,
// }
//
// Independent verification: rehash canonical_bytes, walk the proof to
// the root, then fetch the XRPL tx and compare its hundi/audit/root
// memo. The verify-audit CLI in the Hundi repo demonstrates the full
// algorithm in ~50 lines.

# Public read-only request
curl -s https://api.hundi.network/v1/transactions?limit=10 | jq

# Authenticated request (HMAC enforcement: required)
TS=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
BODY='{"pair":{"base":"USD","quote":"INR"},"side":"buy","notional_base":"10000.00"}'

# Canonical signing input: METHOD\nPATH\nTIMESTAMP\nBODY
INPUT=$(printf 'POST\n/v1/quotes\n%s\n%s' "$TS" "$BODY")
SIG=$(printf '%s' "$INPUT" | openssl dgst -sha256 -hmac "$HUNDI_API_SECRET" -hex | awk '{print $2}')

curl -s -X POST https://api.hundi.network/v1/quotes \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "X-Hundi-API-Key: $HUNDI_API_KEY" \
  -H "X-Hundi-Timestamp: $TS" \
  -H "X-Hundi-Signature: $SIG" \
  -d "$BODY"

// Browser or Node; the SDK does not yet wrap this — use a WS library
import WebSocket from 'ws';

const ws = new WebSocket('wss://api.hundi.network/v1/stream/events');

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    topic: 'events',
    kinds: ['transactions.finalized', 'transactions.blocked', 'co_sign.held'],
    pair: 'USD/INR',
  }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === 'event') {
    console.log(msg.kind, msg.payload);
  }
});

// 30s heartbeat; reply to ping with pong. Reconnect with exponential
// backoff + jitter on connection drop.

try {
  await authedClient.acceptQuote(quoteId, { principal_did: '...' });
} catch (err) {
  if (err instanceof HundiApiError) {
    if (err.code === 'RISK_REJECTED') {
      // Risk gate denied — see err.envelope for per-check detail
    } else if (err.code === 'KYC_REFRESH_OVERDUE') {
      // Principal's annual KYC refresh is past due; settlement-time block
    } else if (err.code === 'AGENT_NOT_AUTHORISED') {
      // Mode B: (agent_did, pair) not in the agent's scope
    } else {
      // err.status, err.code, err.envelope, err.bodyText all available
    }
  }
}