Freeze or unfreeze an account

post

https://api.qfp.quantnetwork.net/api/accounts/{accountRef}/controls

Freezes or unfreezes an account at the token contract. FREEZE applies a compliance freeze to an ACTIVE account; UNFREEZE lifts it on a FROZEN account. These two account-control operations are raised here, not through POST /api/transactions, which rejects them with a 400.

Submission and polling

Like a transaction submission, this is asynchronous and idempotent: 202 for a first submission, 200 for a replay under an Idempotency-Key already used. The body reports the operation raised — its transactionId correlates the later on-chain outcome, read back with GET /api/transactions/{transactionId} — and its state and timestamps.

It does not carry the account's status; read that back with GET /api/accounts/{accountRef}.

When controls take effect

A freeze takes effect immediately: the account moves ACTIVE → FROZEN as the operation is accepted. An unfreeze does not: the account stays FROZEN and returns to ACTIVE only once the unfreeze confirms on-chain.

Path Params

accountRef

string

required

length ≤ 128

[A-Za-z0-9._:-]+

The bank's own reference for the account.

Body Params

operation

string

enum

required

An account-control operation. FREEZE freezes an ACTIVE account at the token contract; UNFREEZE lifts the freeze on a FROZEN account. These are the only two operations the controls endpoint accepts, and the two the transaction endpoint rejects.

Allowed:

reason

string

length ≤ 100

The reason for the operation. Required for a FREEZE and optional for an UNFREEZE, and at most 100 characters when supplied. It is stored among the operation's arguments and read back under params.reason on GET /api/transactions/{transactionId} and the transaction log. A FREEZE with no reason, or an over-long reason on either operation, is a 400.

Headers

API-Version

string

required

^\d+\.\d+\.\d+$

The version of the Quant Flow API the request follows, as major.minor.patch (for example 1.0.0). The request is interpreted, and the response shaped, according to that version.

Idempotency-Key

string

required

length ≤ 255

Caller-supplied key making the write at-most-once. Replay semantics are endpoint-specific: customer and account registry writes replay the original response and reject a changed payload with 422; transaction and deployment submissions return the current operation with 200 and ignore a changed payload. See the operation's response documentation. Use one key per intent. Missing, blank or longer than 255 characters is a 400.

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200A replay: this Idempotency-Key already raised an operation, returned as it now stands.

202Accepted. The operation was raised; state is the state it was accepted in, not where it has since got to. Read it back with GET /api/transactions/{transactionId} using transactionId.

401Returned once authentication is enforced, when the request carries no Authorization header or an unresolvable token. (planned — not returned today, see the API description.)

404No account exists with that reference.

500An unexpected error occurred while handling the request.