> ## 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.

# Token operation lifecycle

> How deploy, mint, burn, and other token operations flow through approval, signing, broadcast, and audit.

Every token operation reuses the existing Qustody [transaction state machine](/concepts/state-machine) and the existing [post-quantum signing](/concepts/quantum-safety) flow. The only thing token operations add on top is typed request/response shapes, token-aware validation, and `token.*` webhook events.

## Deploy flow

```mermaid theme={null}
sequenceDiagram
  participant Dev as Developer
  participant API as Custody API
  participant Pol as Approval Policy
  participant Sig as Post-Quantum Signer
  participant Chain as Quantum Chain
  participant Audit as Audit Log

  Dev->>API: POST /v1/tokens (DRAFT)
  API->>Audit: Record token created
  Dev->>API: POST /v1/tokens/{id}/deployment/estimate
  API-->>Dev: Gas estimate + warnings
  Dev->>API: POST /v1/tokens/{id}/deploy
  API->>Audit: Record deploy requested
  API->>Pol: Evaluate policy
  Pol-->>API: PENDING_AUTHORIZATION
  API-->>Dev: 202 PENDING_AUTHORIZATION
  Pol->>API: Approval granted
  API->>Sig: Request signature on transaction digest
  Sig-->>API: Signature + public key
  API->>Chain: Broadcast deployment
  Chain-->>API: Tx hash, contract address, block
  API->>Audit: Record deploy completed
  API-->>Dev: token.deployed (webhook)
```

## Mint and burn flow

```mermaid theme={null}
sequenceDiagram
  participant Op as Operator
  participant API as Custody API
  participant Pol as Approval Policy
  participant Sig as Post-Quantum Signer
  participant Chain as Quantum Chain
  participant Contract as Token Contract

  Op->>API: POST /v1/tokens/{id}/mint or /burn
  API->>Pol: Evaluate policy
  Pol-->>API: APPROVED or PENDING_AUTHORIZATION
  alt Approval required
    Pol->>API: Approval granted
  end
  API->>Sig: Request signature
  Sig-->>API: Signature
  API->>Chain: Broadcast contract call
  Chain->>Contract: mint(...) or burn(...)
  Contract-->>Chain: State updated
  Chain-->>API: Receipt + status
  API-->>Op: token.minted or token.burned (webhook)
```

## State transitions

```mermaid theme={null}
stateDiagram-v2
  [*] --> SUBMITTED
  SUBMITTED --> QUEUED
  QUEUED --> PENDING_AUTHORIZATION
  PENDING_AUTHORIZATION --> APPROVED: approver decision
  PENDING_AUTHORIZATION --> REJECTED: approver decision
  APPROVED --> PENDING_SIGNATURE
  PENDING_SIGNATURE --> SIGNED
  SIGNED --> BROADCASTING
  BROADCASTING --> CONFIRMING
  CONFIRMING --> COMPLETED
  BROADCASTING --> FAILED
  CONFIRMING --> FAILED
  PENDING_AUTHORIZATION --> CANCELLED
  PENDING_SIGNATURE --> CANCELLED
  REJECTED --> [*]
  COMPLETED --> [*]
  FAILED --> [*]
  CANCELLED --> [*]
```

## What you observe per state

| State                   | Visible in operation | Visible in transaction | Webhook delivered                    |
| ----------------------- | -------------------- | ---------------------- | ------------------------------------ |
| `SUBMITTED`             | yes                  | yes                    | `token.<verb>_requested`             |
| `PENDING_AUTHORIZATION` | yes                  | yes                    | `approval.required`                  |
| `APPROVED`              | yes                  | yes                    | `approval.decision`                  |
| `PENDING_SIGNATURE`     | yes                  | yes                    | —                                    |
| `SIGNED`                | yes                  | yes                    | —                                    |
| `BROADCASTING`          | yes                  | yes                    | —                                    |
| `CONFIRMING`            | yes                  | yes                    | —                                    |
| `COMPLETED`             | yes                  | yes                    | `token.<verb>` (e.g. `token.minted`) |
| `REJECTED`              | yes                  | yes                    | `token.operation_rejected`           |
| `FAILED`                | yes                  | yes                    | `token.operation_failed`             |

## Related

* [Token webhooks](/qustody/token-management/token-webhooks)
* [Object model](/qustody/token-management/objects)
* [Security model](/qustody/token-management/security-model)
* [Transaction lifecycle](/guides/transaction-lifecycle)