How Primary VDT Works

Primary VDT integration is path-based — you wire only the APIs your product needs. Every integrator starts with registry discovery, then branches into browse, create, or lifecycle actions.

Process Overview

1. List & Select Registry
2. Browse Ledgers or Create & Mint
3. View Ledger Detail
4. Update, Transfer, or Burn (as needed)

Step 1 — List and Select a Registry

Call List Registries to load registries for your organization, then Get Registry with the selected registryId to inspect the schema — required attributes, searchable fields, isDataVdt, and lifecycle flags.

All subsequent VDT calls use this registry context. Read isDataVdt first — it determines which create, update, transfer, and burn paths are valid.

Registry type rules

Action	ERC-721 (isDataVdt: false)	DataVDT (isDataVdt: true)
Create without mint	Rejected — options.mint: true required	Allowed — saves a draft ledger
Create with mint	Create + mint	Create + mint
Update (draft)	N/A — mint required on every write	Allowed — revise attribute values
Update (already minted)	Allowed with options.mint: true (re-mint)	Rejected — immutable after mint
Transfer	When registry transferable: true	Not supported
Burn	When registry burnable: true (custom ERC-721)	Not supported

Once a DataVDT ledger is minted, it is never updated or re-minted in any flow.

Step 2 — Browse or Create

After selecting a registry, your UI branches based on user intent:

Browse existing ledgers

• List VDTs — paginated ledger list for the registry
• Search VDTs (optional) — filter by searchable attribute values when the user searches instead of scrolling
• Get VDT — open ledger detail (4W snapshot)

Create and mint

• ERC-721 registry — Create Primary VDT with options.mint: true (required)
• DataVDT registry — create as draft (options.mint: false) or create and mint (options.mint: true) in one call
• Optionally refresh the list or open the new ledger via Get VDT using the returned entityId

Integrators often expose both paths: a ledger table (browse) and a Create button (create & mint).

Step 3 — View Ledger Detail

Get VDT returns the full ledger snapshot — attribute values, mint status, version, and 4W audit context. This is the detail screen users see when they open any ledger from the list or search results.

Step 4 — Ledger Actions

From the detail view, expose actions based on isDataVdt, mint status, and registry lifecycle flags:

Update

Registry	Mint status	Behavior
DataVDT	Draft (not minted)	Update VDT — revise attributes; set options.mint: true to mint when ready
DataVDT	Minted	Not allowed — ledger is immutable
ERC-721	Any	Update VDT with options.mint: true — re-mints on-chain

Call Get VDT again after a successful update to show the latest state.

Transfer (ERC-721 only)

Do not expose transfer for DataVDT registries. For ERC-721 registries where transferable: true:

1. List Org Members (GET /kyb/groups/members) — load KYB business-group members (Business Customers, Business Contacts, custom groups)
2. User selects a destination org from the list
3. Transfer VDT — pass entityId and toOrgId; executes asynchronously on Polygon

Burn (ERC-721 only)

Do not expose burn for DataVDT registries. Burn VDT permanently destroys a minted ERC-721 token when the registry is burnable. The request is queued asynchronously.

What Primary VDT Gives Your Organization

Capability	What It Means for You
Registry-driven schemas	Define attribute rules once; enforce them on every API call
Create with optional mint	DataVDT: draft or mint; ERC-721: mint required
List & filter	Browse all VDTs under a registry or find instances by attribute values
Ledger read	Full 4W audit context for any VDT instance
Update	DataVDT: draft only; ERC-721: re-mint with options.mint: true
Transfer	ERC-721 only — move org-owned VDTs when transferable
Burn	ERC-721 only — destroy minted tokens when burnable

Required Token Scopes

Operation	Scope
List / Get Registry	vdt.read
Create / Update VDT	vdt.write
List / search / get VDT	vdt.read
Create / update	vdt.write
List org members (KYB)	kyb.organization.read
Transfer	vdt.transfer
Burn	vdt.burn