> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Use DICT with Pix Lerian

> Manage Pix keys, claims, MED 2.0, fraud markers, and VSync with Pix Lerian.

DICT manages the Pix key directory and related dispute workflows. Use the public API for client actions. The plugin coordinates provider calls and local state.

## Register and resolve a key

1. Create an entry with [Create entry](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-entry.md). Send the account scope, required reason, and idempotency headers.
2. Save the entry identifier and read it with [Get entry](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-entry.md).
3. Resolve a key with [Lookup key](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/lookup-key.md) before a key-based payment, or use [Check keys existence](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/check-keys-existence.md) for a batch check.
4. Update or delete only through the entry's public lifecycle routes. Do not treat a lookup as ownership proof for another account.

A salary account (`SLRY`) cannot take a new key: the API refuses it with `422` (`PIX-0176`). If the directory holds the key for another person, the API answers `409` (`PIX-0177`), and an ownership claim is the usual next step. If the directory holds the key for the same owner at another participant, the API answers `409` (`PIX-0178`), and a portability claim is the usual next step.

Entry creation and update can fail closed when their replay store is unavailable. A `503` in that condition is not a safe prompt to repeat the business action under a new key.

## Move a key through a claim

Claims cover ownership and portability. A client flow is:

1. Open the claim with [Create claim](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-claim.md).
2. Read it with [Get claim](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-claim.md).
3. Use the transition that matches the claim role and state: [confirm](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/confirm-claim.md), [complete](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/complete-claim.md), [acknowledge](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/acknowledge-claim.md), or [cancel](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/cancel-claim.md).

Claim mutations other than cancellation are unavailable while VSync reconciles. Claim cancellation is intentionally separate: it remains an exit for an active claim rather than a new source of directory drift.

## Work a MED 2.0 case

A funds recovery opens a tracked case. It does not itself prove that funds were returned.

1. Open it with [Create funds recovery](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-funds-recovery.md) and keep the returned internal identifier. A `202` response means that BACEN has not resolved the creation yet, and the recovery is `PENDING`. Read it again later: it becomes `CREATED`, or answers `404` (`PIX-0110`) when BACEN did not apply the creation.
2. Read the case, its related infraction reports, and its tracking graph through the corresponding reference operations.
3. Update only mutable contact or report fields with the documented merge-patch contract.
4. When the case reaches the state that permits it, initiate its refund through the documented funds-recovery refund operation. Read the case again to observe the new state.
5. Cancel only when its current state allows cancellation.

The plugin scopes funds recoveries to the authenticated participant. You must not use a not-found response to distinguish another participant's resource from an unknown identifier.

## Record and cancel a fraud marker

Use [Create fraud marker](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-fraud-marker.md) with a caller-created request identity. A replay with the same identity and payload returns the same marker. A different payload is rejected. Use [List fraud markers](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-fraud-markers.md) or [Get fraud marker](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-fraud-marker.md) to inspect it, and [Cancel fraud marker](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/cancel-fraud-marker.md) when the marker should no longer apply.

## Let VSync protect key consistency

VSync reconciles local key state against the directory by scope. It progresses from verification to event synchronization and, when needed, file reconciliation. VSync is an internal operational surface. Client applications observe its effect through the `503` gate on protected mutations. They do not call its state, job, log, or reconciliation-action routes.

While a scope reconciles, DICT refuses protected mutations with `503` rather than accepting a change that could add new drift. Wait for the scope to become available. Ask the operator to inspect VSync state if the gate persists. Do not bypass the gate with adapter callbacks or direct storage changes.

For disputed-payment holds and refunds, continue with [SPI and the Block Balancer](https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-spi.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.