Manage a regulated token

Legal and compliance scope. The endpoints described here are an integration point for identity and compliance systems. They do not by themselves make a token issuance legally compliant. Always work with your legal, regulatory, and compliance teams before issuing regulated assets.

You will pick a regulated QRC standard, define roles, configure permissioned-transfer rules, manage the allowlist, and run an issuance.

Prerequisites

A Qustody tenant with the relevant permissions: tokens:create, tokens:deploy, tokens:mint, tokens:roles:grant, tokens:compliance:update, tokens:allowlist:write, tokens:freeze.
An identity / KYC provider that produces verifiable references for each holder.
A multi-approver approval policy attached to the token’s admin vault.

Step 1 — Pick a standard

Standard	Best for
`QRC-1400`	Issuance/redemption with controller transfers.
`QRC-3643`	Identity-bound investor lists, compliance-aware transfers.

The rest of this guide uses QRC-3643.

Step 2 — Configure the token

POST /v1/tokens

{
  "standard": "QRC-3643",
  "templateId": "tpl_qrc3643_v1",
  "name": "Example Regulated Asset",
  "symbol": "ERA",
  "decimals": 18,
  "supplyPolicy": { "mintable": true, "burnable": true },
  "admin": { "vaultAccountId": "vault_admin", "approvalPolicyId": "policy_strict" },
  "complianceConfig": {
    "permissionedTransfers": true,
    "investorEligibilityProvider": "kyc_provider_id",
    "jurisdictionFlags": ["US-Reg-D-506(c)"]
  },
  "network": "quantum-chain-testnet"
}

Step 3 — Deploy

POST /v1/tokens/{id}/deploy

Approve the deployment, then wait for token.deployed.

Step 4 — Define roles

Grant on-chain roles to the operating vault accounts:

POST /v1/tokens/{id}/roles/grant
{ "role": "MINTER", "subject": { "type": "vaultAccountId", "vaultAccountId": "vault_treasury" } }

Repeat for BURNER, FREEZER, COMPLIANCE_OPERATOR.

Step 5 — Configure permissioned-transfer rules

PATCH /v1/tokens/{id}/compliance

{
  "config": {
    "permissionedTransfers": true,
    "transferRestrictions": {
      "minHoldingPeriodSeconds": 31536000,
      "maxHoldersPerJurisdiction": { "US": 99 }
    }
  }
}

Step 6 — Manage the allowlist

For every eligible holder:

POST /v1/tokens/{id}/allowlist
{ "address": "0x9a8e…", "identityRef": "kyc_subject_001", "expiresAt": "2027-04-27T00:00:00Z" }

To remove an address:

DELETE /v1/tokens/{id}/allowlist/0x9a8e…

Step 7 — Mint to eligible holders

POST /v1/tokens/{id}/mint
{ "amount": "1000000000000000000000", "recipient": { "type": "address", "address": "0x9a8e…" } }

TOKEN_COMPLIANCE_RESTRICTION_FAILED indicates the recipient is not currently allowed.

Step 8 — Freeze and unfreeze

When required (legal hold, fraud, AML follow-up):

POST /v1/tokens/{id}/freeze
{ "subject": { "type": "address", "address": "0x9a8e…" }, "reason": "compliance hold — case_2026_0427" }

Release with POST /v1/tokens/{id}/unfreeze.

Step 9 — Audit trail

Every operation produces an audit-log entry. Verify the chain with:

GET /v1/audit/verify

Combine with GET /v1/token-operations?tokenId={id} for a per-token operation history.

Wording for stakeholders

Good — “Permissioned QRC-3643 tokens enforce policy-controlled, compliance-aware transfer rules.”
Bad — “QRC-3643 tokens are automatically legally compliant.”

Integration

Operations

Tokens

Manage a regulated token

Prerequisites

Step 1 — Pick a standard

Step 2 — Configure the token

Step 3 — Deploy

Step 4 — Define roles

Step 5 — Configure permissioned-transfer rules

Step 6 — Manage the allowlist

Step 7 — Mint to eligible holders

Step 8 — Freeze and unfreeze

Step 9 — Audit trail

Wording for stakeholders

​Prerequisites

​Step 1 — Pick a standard

​Step 2 — Configure the token

​Step 3 — Deploy

​Step 4 — Define roles

​Step 5 — Configure permissioned-transfer rules

​Step 6 — Manage the allowlist

​Step 7 — Mint to eligible holders

​Step 8 — Freeze and unfreeze

​Step 9 — Audit trail

​Wording for stakeholders

​Related

Prerequisites

Step 1 — Pick a standard

Step 2 — Configure the token

Step 3 — Deploy

Step 4 — Define roles

Step 5 — Configure permissioned-transfer rules

Step 6 — Manage the allowlist

Step 7 — Mint to eligible holders

Step 8 — Freeze and unfreeze

Step 9 — Audit trail

Wording for stakeholders

Related