GET/api/v1/token-freezes

List a token's frozen holders

Returns every frozen address and outpoint on a token, with the balance each freeze pins, its reason code, and the case reference recorded with it, plus the full reason-code vocabulary.

AccessRequires a permission in the workspaceMANAGE_COMPLIANCEMANAGE_WORKSPACE

Updated 08 Nov 20261 min read

Each frozen target comes from the token contract's on-chain state; the case reference, who froze it and when come from SQRL's records. If the reason on chain differs from the one recorded, case_uncertain is true and the case is left out rather than guessed. case_requested is true when a freeze or release for the target is still collecting signatures.

supports_freeze is false for tokens issued before freezing existed; their frozen list is always empty. Balances are raw units.

Freezes and releases themselves are made with POST /api/v1/call-contract, function freeze or unfreeze. See Enforcement.

Query parameters

contract_uidnumberRequired

The token.

workspace_idnumberRequired

The workspace the token belongs to. You must hold MANAGE_COMPLIANCE or MANAGE_WORKSPACE in it.

bash

curl "$SQRL_API/api/v1/token-freezes?contract_uid=512&workspace_id=342" \
  -H "authorization: Bearer $SQRL_TOKEN"

const params = new URLSearchParams({ contract_uid: "512", workspace_id: "342" });
const res = await fetch(`${process.env.SQRL_API}/api/v1/token-freezes?${params}`, {
  headers: { authorization: `Bearer ${process.env.SQRL_TOKEN}` },
});
const { frozen, reason_codes } = await res.json();

Response200 OK

{
  "reason_codes": [
    {
      "code": 1,
      "label": "Sanctions screening hit",
      "kind": "freeze"
    },
    {
      "code": 101,
      "label": "Cleared after review",
      "kind": "release"
    }
  ],
  "supports_freeze": true,
  "frozen": [
    {
      "target": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "reason_code": 1,
      "reason_label": "Sanctions screening hit",
      "case_reference": "CASE-2048",
      "frozen_at": "2026-11-02T09:41:07Z",
      "frozen_by": 4088,
      "held_balance": "0",
      "pinned_balance": "4211000",
      "is_outpoint": false,
      "case_requested": false
    }
  ],
  "total_pinned_frozen": "4211000"
}

Was this page helpful?