📘
🧾 What is DICT?

The DICT (Transactional Accounts Identifier Directory) is a system managed by the Central Bank of Brazil that stores information about Pix keys (such as CPF, CNPJ, email addresses, phone numbers, and random keys) linked to users' accounts.

It allows participating institutions to perform secure and centralized queries to identify the bank and account associated with a Pix key, enabling instant transfers with speed and accuracy.

The DICT query system uses the "token bucket" model, as described in the DICT Operational Manual (Section 13 – Mechanisms for Preventing Read Attacks).

📘
🛡️ Why does the token bucket system exist?

To ensure the security, stability, and privacy of information in DICT, the Central Bank implemented a usage control mechanism known as the token bucket.

This system:

Prevents overload from excessive queries;
Prevents abuse and mass access attempts;
Reduces the risk of attack attempts (such as large-scale key enumeration);
Protects user data.

This model is described in Section 13 of the DICT Operational Manual and applies to all participating institutions.

It is essential that partners comply with the rules established by the Central Bank, as non-compliance may lead to temporary suspension or even blocking of API access.

📘
⚙️ How the token bucket works

Each CPF or CNPJ has an exclusive token bucket, even if multiple accounts are linked to it. The bucket defines the maximum number of queries that can be performed within a certain period.

Customer type / Bucket capacity

Individual (CPF): up to 10 tokens Business (CNPJ): up to 100 tokens

📘
🔄 Token consumption rules

1 token is consumed for:

Valid Pix key lookup Cash-out request (fund withdrawal)

20 tokens are consumed if:

The query is invalid (non-existent or incorrect key) The transaction is not successfully completed

If the transaction is successful, the token is returned to the bucket.

⚠️ Important: When the available token limit is reached, the client will not be able to perform new DICT queries and will receive the following error:

[query limit exceeded | onz-0009]

📘
⏱️ Automatic refill

Every 1 minute, 2 tokens are automatically replenished, until the bucket reaches its maximum capacity.

This mechanism applies to all environments, including integrations with a high volume of requests.

📘
💡 Important tip

If you notice a high token consumption, it is recommended to:

Review the requests being sent to DICT;

Avoid queries with incorrect or repeated data;

Monitor integration errors and logs to identify failure patterns.