> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage a regulated token

> Configure a permissioned QRC token, manage allowlists and roles, and run the issuance lifecycle through Qustody.

<Warning>
  **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.
</Warning>

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](/concepts/policies) 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

```http theme={null}
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

```http theme={null}
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:

```http theme={null}
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

```http theme={null}
PATCH /v1/tokens/{id}/compliance

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

## Step 6 — Manage the allowlist

For every eligible holder:

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

To remove an address:

```http theme={null}
DELETE /v1/tokens/{id}/allowlist/0x9a8e…
```

## Step 7 — Mint to eligible holders

```http theme={null}
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):

```http theme={null}
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:

```http theme={null}
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."

## Related

* [Token standards](/reference/token-standards)
* [Compliance and allowlist](/api-reference/tokens/compliance-and-allowlist)
* [Token roles](/api-reference/tokens/manage-token-roles)
* [Token security model](/qustody/token-management/security-model)