Trusset Protocol - Infrastructure for Asset Tokenization

This page is for the engineer managing customer records from your backend. After reading it you will know how to create a customer before you have their wallet, how to find one again, and which conflicts return 409. The manage sub-module handles customer CRUD operations, search, and wallet linking. All operations are scoped to the instance bound to your API key.

Create a customer

Customers can be created with or without a wallet address. When no wallet is provided, the system generates a referenceKey that you can use to link a wallet later. With a wallet:

const customer = await trusset.customers.manage.create({
  walletAddress: '0x1234...abcd',
  name: 'Acme Capital GmbH',
  country: 'DE',
  investorType: 'PROFESSIONAL',
  externalId: 'your-crm-id-4821',
  metadata: { department: 'treasury' },
})

Without one. The returned pending.referenceKey looks like ref_a1b2c3d4... and is what you pass to linkWallet once the customer has an address:

const pending = await trusset.customers.manage.create({
  name: 'Pending Investor AG',
  country: 'AT',
  externalId: 'crm-9920',
})

Company customers link to individuals through companyId. A companyUrl is normalized to an absolute https URL on the way in:

const company = await trusset.customers.manage.create({
  name: 'Acme Capital GmbH',
  customerType: 'COMPANY',
  companyUrl: 'acme.example.com',
})

await trusset.customers.manage.create({
  name: 'Jane Doe',
  companyId: company.id,
})

If the wallet address is already registered on-chain in the IdentityRegistry, the customer status is automatically set to verified.

Show CreateCustomerInput fields

string

Ethereum address. Validated client-side before sending.

string

Display name for the customer. Required for company customers.

string

ISO 3166-1 alpha-2 or alpha-3 country code. Stored uppercase.

string

RETAIL, PROFESSIONAL, ELIGIBLE_COUNTERPARTY, or a custom verification profile key.

string

default:"INDIVIDUAL"

INDIVIDUAL or COMPANY. Immutable after creation.

string

Company customers only. Normalized to an absolute https URL.

string

Individual customers only: id of a COMPANY customer in the same instance to link to.

string[]

Up to 20 contact strings (emails, phone numbers), 200 characters each.

string

Your system’s unique identifier. Used for deduplication and as a lookup key.

object

Arbitrary JSON. Not indexed, but stored and returned with the customer record.

Search for a customer

The SDK provides typed search methods that map to different lookup strategies. Each returns a single Customer object or throws a TrussetError with code NOT_FOUND. searchByExternalId resolves reliably regardless of ID format or length. searchByName is the exception to the single-result rule: it does a substring match and returns a paginated list on results.customers and results.total.

const c1 = await trusset.customers.manage.searchByWallet('0x1234...abcd')

const c2 = await trusset.customers.manage.searchByExternalId('crm-4821')

const c3 = await trusset.customers.manage.searchByReference('ref_a1b2c3d4...')

const results = await trusset.customers.manage.searchByName('Acme', {
  limit: 20,
  offset: 0,
})

List customers

list returns customers and total. The search option matches against name, wallet, externalId, referenceKey, and companyUrl in one pass.

const page = await trusset.customers.manage.list({
  limit: 100,
  offset: 0,
  search: 'bank',
  customerType: 'COMPANY',
  includeArchived: false,
})

number

default:100

Records per page. Range: 1-200.

string

Optional filter. INDIVIDUAL or COMPANY.

Update a customer

await trusset.customers.manage.update('customer-id', {
  country: 'CH',
  investorType: 'ELIGIBLE_COUNTERPARTY',
  metadata: { migrated: true },
})

Only provided fields are updated. Omitted fields remain unchanged.

Link a wallet

For customers created without a wallet address, link one using the referenceKey:

await trusset.customers.manage.linkWallet({
  referenceKey: 'ref_a1b2c3d4...',
  walletAddress: '0x5678...efgh',
})

The wallet address must not already be assigned to another customer in the same instance. If the address is already verified on-chain, the customer status updates to verified automatically.

Archive a customer

Archiving soft-deletes a customer. Archived customers are excluded from list queries by default.

await trusset.customers.manage.archive('customer-id')

Manage linked wallets

A customer has one primary wallet and any number of linked wallets. Linked wallets resolve to the same customer in lookups and country checks. A wallet can only belong to one customer per instance. Promoting a linked wallet does not unlink the old one. The previous primary stays linked, labeled “Previously primary”. removeWallet works on linked wallets only, not on the primary.

const wallets = await trusset.customers.manage.listWallets('customer-id')

await trusset.customers.manage.addWallet('customer-id', '0x9999...aaaa', 'Trading desk')

await trusset.customers.manage.promoteWallet('customer-id', '0x9999...aaaa')

await trusset.customers.manage.removeWallet('customer-id', '0x9999...aaaa')

listWallets returns primary, total, and wallets, where each entry carries address, label, isPrimary, and addedAt. Conflicts return 409 with a specific code: ALREADY_PRIMARY, WALLET_ALREADY_LINKED (same customer), or WALLET_IN_USE (another customer).

Look up countries in bulk

Retrieve country codes for a list of wallet addresses in a single call. Useful for compliance checks across large holder sets.

const countries = await trusset.customers.manage.batchGetCountries([
  '0xaaa...', '0xbbb...', '0xccc...',
])

The result maps address to country code, as in { "0xaaa...": "DE", "0xbbb...": "FR" }. Addresses without a matching customer record are omitted from the result.

Getting Started

Customers

Management

Create a customer

Search for a customer

List customers

Update a customer

Link a wallet

Archive a customer

Manage linked wallets

Look up countries in bulk

​Create a customer

​Search for a customer

​List customers

​Update a customer

​Link a wallet

​Archive a customer

​Manage linked wallets

​Look up countries in bulk

Create a customer

Search for a customer

List customers

Update a customer

Link a wallet

Archive a customer

Manage linked wallets

Look up countries in bulk