@kustodia_app/node

Official Node.js SDK for Kustodia — escrow payments for marketplaces and AI agents.

Supports fiat (SPEI, Wire) and crypto (USDC on Arbitrum, Base, Polygon).

Install

npm install @kustodia_app/node

Quick Start

Sandbox (no API key needed)

import { Kustodia } from '@kustodia_app/node';

const kustodia = new Kustodia();

// Create → Fund → Release in 3 lines
const escrow = await kustodia.sandbox.create({ amount: 50000 });
const funded = await kustodia.sandbox.fund(escrow.data.id);
const released = await kustodia.sandbox.release(escrow.data.id);

Production

import { Kustodia } from '@kustodia_app/node';

const kustodia = new Kustodia({ apiKey: 'kust_live_...' });

const payment = await kustodia.escrows.create({
    amount: 50000,
    payer_email: '[email protected]',
    payee_email: '[email protected]',
});
console.log(payment.data.tracking_url);

Disputes

// Raise a dispute
await kustodia.disputes.raise(paymentId, { reason: 'Item not as described' });

// Seller responds
await kustodia.disputes.respond(paymentId, { response: 'Shipped correctly, see evidence' });

// Check details
const dispute = await kustodia.disputes.get(paymentId);

Delivery Tracking

// Attach carrier tracking to auto-release on delivery
await kustodia.delivery.attach(paymentId, {
    carrier: '99minutos',
    tracking_id: 'TRK-12345',
    auto_release_on_delivery: true,
});

// Check status
const status = await kustodia.delivery.status(paymentId);

Web3 Escrows

// Create an on-chain escrow (USDC on Arbitrum)
const escrow = await kustodia.web3.create({
    buyer_wallet: '0xBuyer...',
    seller_wallet: '0xSeller...',
    token: 'USDC',
    chain: 'arbitrum',
    amount: 1000,
});

// Release to seller
await kustodia.web3.release(escrow.data!.id);

Trust Scores

// User trust score (fiat + web3 combined)
const trust = await kustodia.trust.user(userId);
console.log(`Score: ${trust.score}/100 — Tier: ${trust.tier}`);

// Wallet trust score
const walletTrust = await kustodia.trust.wallet('0x...');

// Transaction trust context
const txTrust = await kustodia.trust.payment(paymentId);

Custody Agreements

// Get auto-generated custody agreement
const agreement = await kustodia.agreements.get(paymentId);

// Send signing OTP to buyer's email
await kustodia.agreements.requestOtp(paymentId, { role: 'buyer' });

// Sign with OTP
await kustodia.agreements.sign(paymentId, { role: 'buyer', otp: '123456' });

Webhook Verification

import { Kustodia } from '@kustodia_app/node';

app.post('/webhook/kustodia', (req, res) => {
    const event = Kustodia.webhooks.verify(
        req.body,
        req.headers['x-kustodia-signature'] as string,
        'whsec_your_secret'
    );
    console.log(event.type, event.data);
    res.json({ received: true });
});

Webhook Configuration

// Configure webhook endpoint
await kustodia.webhookConfig.configure({
    url: 'https://your-app.com/webhooks/kustodia',
    events: ['payment.created', 'payment.released', 'payment.disputed'],
});

// Test it
const result = await kustodia.webhookConfig.test();

API Reference

new Kustodia(config?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | API key from Dashboard → Developers | | baseUrl | string | https://api.kustodia.app | Base URL | | timeout | number | 30000 | Request timeout in ms |

Resources

| Resource | Methods | |----------|---------| | sandbox | create, get, fund, release, dispute, stats | | escrows | create, get, list, release, dispute, cancel, refund, track | | recurring | create, get, list, pause, resume, cancel | | kyc | createSession, getSession, getUserStatus, attest | | disputes | raise, get, respond, appeal | | evidence | list, viewUrl | | webhookConfig | get, configure, test | | web3 | status, create, get, list, byWallet, onchain, release, refund, sync | | delivery | status, attach, simulate | | trust | user, refreshUser, wallet, refreshWallet, payment | | fx | rate, ticker, convert, books, fees | | agreements | get, requestOtp, sign, pdfUrl | | support | create, list, get, update | | marketplace | getSettings, updateSettings |

Static

Kustodia.webhooks.verify(payload, signature, secret)

Verifies HMAC-SHA256 signature with constant-time comparison.

Webhook Events

| Event | Fired When | |-------|------------| | payment.created | Escrow created | | payment.deposited | SPEI/Wire deposit confirmed | | payment.released | Funds released to seller | | payment.cancelled | Escrow cancelled | | payment.disputed | Dispute raised | | payment.refunded | Funds refunded to buyer | | payment.expired | Escrow expired | | kyc.session_created | KYC session initiated | | kyc.verified | KYC approved | | kyc.rejected | KYC rejected | | delivery.confirmed | Carrier delivery confirmed |

License

MIT