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

# API de anillos de privacidad de Solana

> Consulta UTXO cifradas, el historial de transacciones blindadas, pruebas de Merkle y registros públicos de usuarios para los anillos de privacidad de Solana.

La API de anillos de privacidad de Solana consulta el indexador de privacidad. Devuelve el estado cifrado y los metadatos públicos de las transacciones. Tu billetera descifra las cargas útiles para consultar los saldos privados y el historial. Consulta la [descripción general de privacidad](https://www.helius.dev/docs/es/privacy.md) para conocer los conceptos y el [SDK](https://www.helius.dev/docs/es/privacy/sdk.md) para los flujos de depósito, transferencia y retiro.

## Saldos públicos y privados

Un saldo privado se almacena en UTXO (salidas de transacciones no gastadas). Una UTXO no es una cuenta de Solana.

| | Saldo público | Saldo privado |
| - | - | - |
| Saldo | Lamports en una cuenta de Solana o el `amount` en una cuenta de token SPL | La suma de las UTXO no gastadas de un activo |
| Visibilidad | Público en cadena | Cifrado en cadena |
| Descubrir cuentas de tokens o salidas | [`getTokenAccountsByOwner`](https://solana.com/docs/rpc/http/gettokenaccountsbyowner) devuelve las cuentas de tokens SPL que pertenecen a una dirección | `getEncryptedUtxosByTags` devuelve las salidas cifradas que coinciden con etiquetas de visualización o con un anillo |
| Consultar un saldo | [`getBalance`](https://solana.com/docs/rpc/http/getbalance) para SOL; [`getTokenAccountBalance`](https://solana.com/docs/rpc/http/gettokenaccountbalance) para una cuenta de token SPL | Tu billetera descifra las salidas, comprueba cuáles no se han gastado y suma los importes de cada activo |

Consulta [Estado privado y UTXO](https://www.helius.dev/docs/es/privacy/concepts/utxo.md) para saber cómo se almacenan y gastan los saldos privados.

## Endpoint y autenticación

Envía una solicitud JSON-RPC 2.0 a la ruta del método con tu clave de API de Helius:

```bash theme={"system"}
curl --request POST \
  --url "https://devnet.helius-rpc.com/v1/spr/getUserRecords?api-key=YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getUserRecords",
    "params": {
      "owners": ["11111111111111111111111111111111"]
    }
  }'
```

El `method` debe coincidir con el segmento final de la ruta de la URL. Las rutas de métodos aceptan una sola solicitud; los lotes, los campos `method` duplicados y las discrepancias entre la ruta y el cuerpo devuelven HTTP 400 antes de la ejecución.

Para el desarrollo local, usa `http://127.0.0.1:8784/{method}` después de iniciar la [pila local](https://www.helius.dev/docs/es/privacy/endpoints.md).

## Métodos

> [card] [getEncryptedUtxosByTags](https://www.helius.dev/docs/es/api-reference/privacy/getencryptedutxosbytags.md)
>
> Descubre salidas cifradas mediante etiquetas de visualización o un anillo.

> [card] [getShieldedTransactionsByTags](https://www.helius.dev/docs/es/api-reference/privacy/getshieldedtransactionsbytags.md)
>
> Consulta el historial de transacciones blindadas mediante etiquetas de visualización o un anillo.

> [card] [getShieldedTransactionsBySignature](https://www.helius.dev/docs/es/api-reference/privacy/getshieldedtransactionsbysignature.md)
>
> Recupera los eventos blindados de una transacción de Solana.

> [card] [getShieldedTransactionsByNullifiers](https://www.helius.dev/docs/es/api-reference/privacy/getshieldedtransactionsbynullifiers.md)
>
> Encuentra las transacciones que gastaron los anuladores proporcionados.

> [card] [getMerkleProofs](https://www.helius.dev/docs/es/api-reference/privacy/getmerkleproofs.md)
>
> Obtén pruebas de inclusión para los compromisos del árbol de estado.

> [card] [getNonInclusionProofs](https://www.helius.dev/docs/es/api-reference/privacy/getnoninclusionproofs.md)
>
> Obtén pruebas de no inclusión para los valores de los anuladores.

> [card] [getNullifierQueueElements](https://www.helius.dev/docs/es/api-reference/privacy/getnullifierqueueelements.md)
>
> Lee los anuladores en cola según el orden de secuencia.

> [card] [getUserRecords](https://www.helius.dev/docs/es/api-reference/privacy/getuserrecords.md)
>
> Busca registros públicos de direcciones blindadas.

## Paginación

`getEncryptedUtxosByTags`, `getShieldedTransactionsByTags` y `getShieldedTransactionsByNullifiers` devuelven una página en `result`:

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "context": { "slot": 4242, "blockTime": 1730000000 },
    "data": [],
    "paginationToken": null
  }
}
```

* `data` agrupa los resultados por transacción de Solana, ordenados por slot y firma de forma ascendente. El método de UTXO cifradas usa un arreglo `outputs` en cada grupo; los métodos del historial de transacciones usan un arreglo `events`.
* `limit` cuenta las transacciones de Solana, de 1 a 1,000, y su valor predeterminado es 1,000. Las salidas o los eventos coincidentes de una transacción permanecen juntos en una página.
* Devuelve un `paginationToken` no nulo sin modificar, con las mismas etiquetas o anuladores, el mismo anillo y los mismos filtros de slot. Continúa hasta que el token de respuesta sea `null`.
* `filters.slot` acepta los límites `gt`, `gte`, `lt` y `lte`. Los límites proporcionados se combinan con AND. Cuando una lectura sin límite alcance un token nulo, guarda el `context.slot` de esa página y reanúdala después con `filters.slot.gt` establecido en ese valor. Una lectura limitada por `lt` o `lte` solo cubre los slots hasta ese límite; reanúdala desde el límite, no desde `context.slot`.
* Establece `minContextSlot` para exigir un slot mínimo persistido del indexador. El indexador también exige el slot de tu `paginationToken` y de cualquier filtro `gt` o `gte`. Si no ha alcanzado alguno de ellos, devuelve el error `-32016` con `error.data.contextSlot`; vuelve a intentarlo cuando se haya actualizado.

Las respuestas del historial también pueden incluir `outputTreeId`, el ID más reciente del árbol de estado no pausado. Se omite cuando no está disponible. Cada salida identifica su propio árbol mediante `outputContext.treeId`.

`getNullifierQueueElements` usa paginación basada en secuencias; consulta la [página del método](https://www.helius.dev/docs/es/api-reference/privacy/getnullifierqueueelements.md).

## Codificación de datos

| Valor | Codificación |
| - | - |
| Claves públicas, hashes, compromisos, etiquetas de visualización, anuladores | Cadenas Base58 que representan 32 bytes |
| Firmas de transacciones de Solana | Cadenas Base58 que representan 64 bytes |
| Cargas útiles de texto cifrado, `txViewingPk`, `salt`, `viewingPubkey` del registro | Cadenas Base64 |
| `context.slot` | Slot más alto de Solana persistido por el indexador |
| `context.blockTime` | Hora del bloque como marca de tiempo Unix en segundos |

## Errores

Revisa el campo `error` de JSON-RPC antes de leer `result`, incluso cuando el estado HTTP sea 200.

| Código | Significado |
| - | - |
| `-32600` | La validación de la solicitud falló, no se encontró un registro, la raíz de una prueba indexada está obsoleta o el historial solicitado comienza antes del historial indexado. Un cuerpo de solicitud ilegible también devuelve `-32600` con HTTP 400. Consulta `message` para conocer la causa. |
| `-32601` | Método desconocido o una ruta de método rechazó la solicitud antes de la ejecución. Los rechazos de ruta usan HTTP 400. |
| `-32602` | No se pudieron analizar los parámetros, por ejemplo, debido a una codificación de clave no válida o a un límite fuera del rango permitido. |
| `-32603` | Error interno del servidor. |
| `-32016` | El indexador no ha alcanzado `minContextSlot`, el slot del token de paginación o un filtro de slot `gt`/`gte`. |

HTTP 429 indica una limitación de tasa; consulta los [límites de tasa](https://www.helius.dev/docs/es/billing/rate-limits.md). Consulta [autenticación](https://www.helius.dev/docs/es/api-reference/authentication.md) para configurar la clave de API.


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