@trusset/sdk

TypeScript SDK for the Trusset tokenization infrastructure API. Built for financial institutions, banks, and fintechs integrating MiCA/eWpG-compliant tokenized asset management.

Zero dependencies. Works in Node.js 18+ and modern runtimes with native fetch.

Setup

npm install @trusset/sdk

Requires an API key from your Trusset instance dashboard. Each API key is scoped to a single instance (isolated environment with its own data, contracts, and network config).

import { TrussetClient } from '@trusset/sdk'

const trusset = new TrussetClient({
  apiKey: 'tsk_live_...',
  // baseUrl defaults to https://api.trusset.org
})

Modules

The SDK currently ships the customers module. Tokenization, trading, and lending modules will follow.

customers.manage - CRUD and search

// Create a customer (with or without a wallet)
const customer = await trusset.customers.manage.create({
  name: 'Acme GmbH',
  country: 'DE',
  investorType: 'PROFESSIONAL',
  externalId: 'your-internal-id-123',
})

// The customer gets a referenceKey if no wallet was provided.
// Link a wallet later:
await trusset.customers.manage.linkWallet({
  referenceKey: customer.referenceKey!,
  walletAddress: '0x...',
})

// Search
const byName = await trusset.customers.manage.searchByName('Acme')
const byWallet = await trusset.customers.manage.searchByWallet('0x...')
const byExtId = await trusset.customers.manage.searchByExternalId('your-internal-id-123')

// List with pagination
const page = await trusset.customers.manage.list({ limit: 50, offset: 0, search: 'bank' })

// Update
await trusset.customers.manage.update(customer.id, { country: 'AT' })

// Archive
await trusset.customers.manage.archive(customer.id)

customers.identity - On-chain KYC

All write operations require a configured relayer wallet on the instance. The relayer signs transactions against the IdentityRegistry contract (UUPS upgradeable, MiCA/eWpG compliant).

// Verify a single identity on-chain
const result = await trusset.customers.identity.verify({
  walletAddress: '0x...',
  country: 'DE',
  investorType: 'RETAIL',
  softExpiryDays: 365,
  hardExpiryDays: 730,
})
// result.txHash, result.gasUsed

// Batch verify up to 500 identities in one transaction
await trusset.customers.identity.batchVerify([
  { walletAddress: '0xaaa...', country: 'DE' },
  { walletAddress: '0xbbb...', country: 'FR', investorType: 'PROFESSIONAL' },
])

// Revoke
await trusset.customers.identity.revoke('0x...')

// Get combined on-chain + off-chain status
const status = await trusset.customers.identity.getStatus('0x...')
// status.onChain.isVerified, status.offChain.status

// Compliance check before a token transfer
const check = await trusset.customers.identity.canTransfer({
  from: '0xaaa...',
  to: '0xbbb...',
  amount: '1000000000000000000',
  fromBalance: '5000000000000000000',
  toBalance: '0',
})
// check.allowed, check.reason, check.senderStatus, check.receiverStatus

customers.idLinks - KYC verification links

Send Sumsub-powered KYC verification links to investors via email or SMS.

const link = await trusset.customers.idLinks.create({
  recipientEmail: '[email protected]',
  investorType: 'RETAIL',
  country: 'DE',
  expiryDays: 30,
  sendVia: ['email'],
})
// link.verificationUrl, link.token

const links = await trusset.customers.idLinks.list({ status: 'PENDING' })
await trusset.customers.idLinks.revoke(link.id)
await trusset.customers.idLinks.resend(link.id, ['email'])

customers.sync - Database synchronization

The sync module is built for institutions migrating existing customer databases into Trusset. It handles batched upserts, conflict resolution, and optional on-chain verification in a single call.

import { SyncRecord } from '@trusset/sdk'

// Map your existing database rows to SyncRecord
const records: SyncRecord[] = existingCustomers.map(row => ({
  externalId: row.id,              // Your system's unique ID
  name: row.fullName,
  walletAddress: row.ethAddress,   // Optional
  country: row.countryCode,
  investorType: 'RETAIL',
  metadata: { source: 'legacy-crm' },
}))

const result = await trusset.customers.sync.importRecords(records, {
  batchSize: 50,
  onConflict: 'update',           // 'skip' or 'update'
  verifyOnChain: true,            // Also verify wallets on IdentityRegistry
  verificationDefaults: {
    softExpiryDays: 365,
    hardExpiryDays: 730,
  },
  onProgress: (done, total) => {
    console.log(`Synced ${done}/${total}`)
  },
})

// result.created, result.updated, result.skipped, result.errors

// Export back to your system
const exported = await trusset.customers.sync.exportRecords()

Error handling

All errors extend TrussetError and carry machine-readable codes.

import { TrussetError, AuthError, ValidationError, NetworkError } from '@trusset/sdk'

try {
  await trusset.customers.manage.get('0xinvalid')
} catch (err) {
  if (err instanceof AuthError) {
    // API key invalid or expired
  }
  if (err instanceof ValidationError) {
    // Bad input, check err.message
  }
  if (err instanceof TrussetError) {
    // err.code, err.statusCode, err.requestId
  }
}

The HTTP layer retries transient errors (408, 429, 5xx, network failures) with exponential backoff. Default: 3 retries, 30s timeout. Override via config:

new TrussetClient({
  apiKey: '...',
  timeoutMs: 60_000,
  maxRetries: 5,
})

Configuration

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Instance API key from dashboard | | baseUrl | string | https://api.trusset.org | API base URL | | timeoutMs | number | 30000 | Request timeout in ms | | maxRetries | number | 3 | Retries on transient failures | | logger | Logger | silent | Custom logger implementing debug/info/warn/error |

Architecture

src/
  index.ts              Public exports
  client.ts             TrussetClient entry point
  types/
    common.ts           Shared types (config, API envelope, pagination)
    customers.ts        All customer-related types and interfaces
  modules/
    customers/
      index.ts          Customers facade (combines sub-modules)
      management.ts     CRUD, search, wallet linking
      identity.ts       On-chain verification, compliance checks
      id-links.ts       KYC verification link management
      sync.ts           Bulk database import/export
  utils/
    http.ts             HTTP client with retries and error mapping
    errors.ts           Error class hierarchy
    validation.ts       Input validation helpers

The SDK is structured so additional product modules (tokenization, trading, lending) slot in as sibling directories under modules/. Each module receives the shared HttpClient instance and exposes a clean public API.

Compatibility

• TypeScript / ESM - primary target, full type safety
• Node.js / CommonJS - dual CJS/ESM build via tsup
• Java / Python - the SDK calls a standard REST API with JSON over HTTPS. Any HTTP client in any language works. Typed wrappers for Java and Python are planned.

Build

npm install
npm run build        # outputs to dist/
npm run typecheck    # type validation
npm run test         # vitest

License

MIT - Trusset UG

For future modules (tokenization, trading, lending) we*ll go as siblings: └── modules/ ├── customers/ ├── tokenization/ # next ├── trading/ # next └── lending/ # next