KYT State

KYT (Know Your Transaction) is the transaction monitoring our compliance team runs on every deposit and pay-out. When something needs a closer look, your user, or one specific user/counterparty pair, is temporarily held, placed under review or rejected, and transactions are paused or refused while that lasts.

The KYT-STATE webhook tells you when that changes. This endpoint lets you read the current state on demand, for example right before your user starts a transaction. It only reads the state and never changes it.

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/account/kyt-state

Query Parameters

Parameter	Type	Required	Description
counterpartyKey	string	No	The counterparty's tax id, PIX key or wallet address, exactly as it appears in transactions. Scopes the answer to the pair formed by the account and this counterparty. Up to 256 characters.
subAccountId	string	No	The ID of the subaccount to read the state of.

Note: Remember that you can pass subAccountId as a parameter for the operation to be for the sub account.

Account-wide or per counterparty

Without counterpartyKey, the answer is the account-wide state only. Restrictions scoped to specific counterparties are not reflected, so a company account can read ACTIVE here while one of its counterparties is restricted.

With counterpartyKey, the account-wide state wins whenever it restricts: you get that state and the answer omits counterpartyKey, telling you the restriction applies to the account as a whole. Otherwise the answer is about that pair and echoes the key, also when it is ACTIVE.

info

Call this endpoint with the counterparty before a transaction. That is the only answer that reflects every restriction the transaction would run into.

cUrl Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/kyt-state?counterpartyKey=45981761000100" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Sample JSON Response

A pair held for compliance review:

{
  "kytState": {
    "userId": "9664631a-cdab-4c0e-84bc-18d173e448e8",
    "counterpartyKey": "45981761000100",
    "state": "TEMPORARY_HOLD",
    "expiresAt": "2026-10-07T15:28:51.330773Z",
    "message": "Transactions with this counterparty are temporarily held for compliance review until 2026-10-07T15:28:51Z and will be refused until then. Send an email to compliance@avenia.io and respond to the RFI (request for information).",
    "updatedAt": "2026-10-07T14:28:51.331953Z"
  }
}

An unrestricted account, asked without counterpartyKey:

{
  "kytState": {
    "userId": "9664631a-cdab-4c0e-84bc-18d173e448e8",
    "state": "ACTIVE",
    "message": "User is active. Transactions are allowed."
  }
}

Response Fields

Field	Type	Description
userId	string	The account ID, or the subaccount ID when subAccountId was given. It is the same identifier the KYT-STATE webhook carries in userId.
counterpartyKey	string	Present only when the answer is about one counterparty: the counterparty's tax id, PIX key or wallet address, exactly as it appears in transactions. Absent when the answer is about the account as a whole.
state	string	The current state: TEMPORARY_HOLD, UNDER_REVIEW, REJECTED or ACTIVE. See the table below.
expiresAt	string	Present only for TEMPORARY_HOLD: when the hold lifts, in UTC (RFC 3339).
message	string	A sentence you can show to your end user. For restrictions it ends with how to contact our compliance team.
updatedAt	string	When the state was last written, in UTC. Absent when the account was never restricted.

KYT State values

State	Description
TEMPORARY_HOLD	Transactions are held until expiresAt. The hold lifts by itself at that time.
UNDER_REVIEW	Transactions are held until our compliance team decides.
REJECTED	Transactions are refused permanently.
ACTIVE	Transactions are allowed. Either there was never a restriction or it was lifted by our compliance team.

info

Unlike the webhook, the answer has no previousState: it is a snapshot of the current state, not a change.

Errors

Status	Message	When
400	InvalidFieldError: counterpartyKey is invalid	counterpartyKey is longer than 256 characters.
400	InvalidFieldError: subAccountId is invalid	subAccountId is not a UUID.
404	NotFoundError: subAccountId not found	subAccountId does not belong to your account.