@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);

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 });
});

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 |

Sandbox

| Method | Description | |--------|-------------| | sandbox.create(params) | Create a sandbox escrow | | sandbox.get(id) | Get sandbox escrow status | | sandbox.fund(id) | Simulate SPEI deposit | | sandbox.release(id) | Release funds to seller | | sandbox.dispute(id, reason) | Open a dispute | | sandbox.stats() | Get aggregate stats |

Escrows

| Method | Description | |--------|-------------| | escrows.create(params) | Create a new escrow | | escrows.get(id) | Get escrow by ID | | escrows.list({ page, limit, status }) | List with pagination | | escrows.release(id) | Release funds to payee | | escrows.dispute(id, reason) | Open a dispute | | escrows.cancel(id) | Cancel an escrow | | escrows.refund(id, reason?) | Request a refund | | escrows.track(id) | Public tracking (no auth) |

Recurring

| Method | Description | |--------|-------------| | recurring.create(params) | Create a subscription | | recurring.list() | List all subscriptions | | recurring.get(id) | Get subscription by ID | | recurring.pause(id) | Pause a subscription | | recurring.resume(id) | Resume a subscription | | recurring.cancel(id) | Cancel a subscription |

Webhooks

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

Verifies HMAC-SHA256 signature with constant-time comparison.

License

MIT