---
url: https://game-engine-io.github.io/enginex-frontend-sdk/flows/pix-keys.md
---
# PIX keys

The `pixKeys` namespace stores the player's PIX keys, used as the destination of
[withdrawals](/flows/withdrawal) (`withdrawals.request({ amount, pixKeyId })`). All methods require login.

## List

```ts
const keys = await enginex.pixKeys.list()
const preferred = keys.find((k) => k.isDefault) ?? keys[0]
// { id, keyType: 'cpf', maskedKeyValue: '***.456.789-**', isDefault: true, verified: true, createdAt }
```

The full key value **never** comes back from the gateway: only `maskedKeyValue`, for display. `verified`
indicates whether the payment service has already confirmed ownership.

## Add

```ts
const key = await enginex.pixKeys.add({ keyType: 'email', keyValue: 'ana@exemplo.com' })
key.maskedKeyValue // masked version, e.g. 'a***.com'
```

`keyType` is `'cpf'`, `'email'`, `'phone'` or `'random'` (random key). An empty type or value is
rejected with `INVALID_ARGUMENT` (400); an invalid or duplicate key comes back as a payment service
error: handle it by `code` (see [Errors](/concepts/errors)).

## Default key and removal

```ts
await enginex.pixKeys.setDefault({ keyId: key.id }) // becomes the one suggested for withdrawals
await enginex.pixKeys.remove({ keyId: oldKey.id })
```

Both resolve with no value; list again to refresh the screen. A nonexistent id (or one belonging to
another player) arrives as a gateway error, usually `NOT_FOUND`.

## Withdrawal without a saved key

It is not mandatory to save the key first: `withdrawals.request` also accepts `pixKeyType` +
`pixKeyValue` on the spot, and with `pixKeyType: 'cpf'` it uses the CPF from sign-up without needing
the value.
