---
title: "Billeteras"
description: "Esta guía explica cómo crear y gestionar billeteras con la API de Fystack."
url: https://docs.fystack.io/es/wallets
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# Billeteras

Las billeteras son contenedores seguros para gestionar activos digitales. Fystack ofrece distintos tipos de billetera según tus necesidades, incluidas las billeteras Hyper y las billeteras MPC (Multi-Party Computation).

## Tipos de billetera

Fystack admite dos tipos de billetera:

|  | Hyper | MPC |
| --- | --- | --- |
| Cómo funciona | Claves derivadas de una semilla maestra por workspace (derivación HD) | Clave privada dividida en fragmentos entre nodos de Mpcium, nunca se ensambla en un solo lugar |
| Seguridad | Alta | Nivel institucional, firmas de umbral |
| Velocidad de creación | Instantánea, devuelve `success` de inmediato | 7-15 segundos |
| Costo | Menor | Mayor |
| Recuperación | Se recrea a partir de la semilla HD | Recuperación multiparte |
| Ideal para | Billeteras de usuarios finales, apps de consumo, generación de alto volumen | Hot wallets, custodia, exchanges y billeteras de alto valor |

---

## Crear una billetera

**Endpoint:** `POST /wallets`

Para crear una nueva billetera, envía una solicitud POST al endpoint `/wallets` con los parámetros requeridos.

### Parámetros

- `name` (string, required): Un nombre descriptivo para la billetera.
- `wallet_type` (enum: standard | mpc | hd_mpc, required): El tipo de billetera que se creará:
  - `standard`: **Hyper**. Derivada mediante HD a partir de la semilla cifrada de tu workspace. Clave única, alto rendimiento.
  - `mpc`: **MPC Cloud**. Firma MPC totalmente gestionada. Tus políticas y aprobaciones deciden cada transacción.
  - `hd_mpc`: **Co-signed HD MPC**. Se agrega bajo tu maestro HD y se cofirma con tu cosigner de servidor, por lo que Fystack no puede firmar por sí solo. Primero [configura tu cosigner](https://docs.fystack.io/cosigner/installation.md).
- `wallet_purpose` (string, default: general): El propósito de la billetera. Debe ser uno de `general`, `user`, `gas_tank`, `payment` o `one_time_use`. Si se establece en `user`, la billetera se ocultará en el portal.
- `gas_sponsorship_enabled` (boolean, default: false): Patrocina el gas de las transferencias de tokens desde esta billetera en las redes EVM, Solana y TRON, de modo que la billetera no necesite tener la moneda nativa. El gas se paga desde el gas tank del workspace, consulta [Gas Station](https://docs.fystack.io/es/product/gas-station.md). También puedes cambiarlo más adelante desde la configuración de la billetera.
- `sweep_task_id` (string): UUID de una [sweep task](https://docs.fystack.io/es/product/automation.md#sweep-tasks) existente que se vinculará a esta billetera. Primero crea la sweep task y luego copia su ID desde la página Automation del dashboard.

### ¿Qué es una sweep task? Mueve automáticamente los fondos de las billeteras nuevas

Una sweep task mueve automáticamente los fondos de una billetera a otra billetera o dirección cuando su saldo alcanza un valor en USD definido, para que no tengas que recolectar los depósitos manualmente.

Para configurarla en billeteras nuevas:

1. **Crea una sweep task** en **Automation > Add Sweep Task** del dashboard. Consulta [Automation](https://docs.fystack.io/product/automation.md#sweep-tasks).
2. **Copia el ID de la sweep task** desde la página Automation.
3. **Pásalo como `sweep_task_id`** al crear cada billetera.

**Cómo funcionan las sweep tasks**

- **Monitoreo automático**: el sistema monitorea continuamente el saldo de la billetera
- **Activación por umbral**: cuando el valor en USD de la billetera alcanza el valor mínimo de activación de la tarea, se ejecuta un sweep
- **Flexibilidad de destino**: los fondos pueden transferirse a billeteras internas o a direcciones externas de tu libreta de direcciones

> **Info: Reutiliza una sweep task en varias billeteras.** Vincula el mismo `sweep_task_id` a cada billetera que deba transferir al mismo destino. Así, al actualizar esa única tarea, el cambio se aplica a todas las billeteras vinculadas.

> **Warning: Configura un cosigner de servidor antes de usar hd_mpc.** Las billeteras `hd_mpc` se derivan de un maestro HD-MPC que se firma con un cosigner de servidor. Antes de llamar a este endpoint, [instala y empareja un cosigner de servidor](https://docs.fystack.io/es/cosigner/installation.md) y luego crea el maestro HD desde el modal de creación de billetera en el [dashboard de Fystack](https://app.fystack.io/). El cosigner debe estar en línea cuando se cree la billetera.

### Respuesta

- `success` (boolean): Indica si la solicitud se completó correctamente.
- `message` (string): Un mensaje que describe el resultado de la operación.
- `code` (integer): Un código numérico que indica el estado del resultado (0 si fue exitoso).
- `data` (object): Contiene los detalles de la billetera.
  - `wallet_id` (string): El UUID de la billetera recién creada.
  - `status` (string): El estado actual del proceso de creación de la billetera.

**Request: billetera básica** `POST /wallets`

```typescript
import { FystackSDK, Environment } from "@fystack/sdk"

const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

await sdk.createWallet({
    name: 'Treasury wallet',
    walletType: WalletType.MPC
})
```

```bash
curl -X POST https://api.fystack.io/api/v1/wallets \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature==" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Treasury wallet",
    "wallet_type": "mpc"
  }'
```

**Request: con sweep task** `POST /wallets`

```typescript
import { FystackSDK, Environment } from "@fystack/sdk"

const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

await sdk.createWallet({
    name: 'User deposit wallet',
    walletType: WalletType.Standard,
    walletPurpose: WalletPurpose.User,
    sweepTaskId: '987f6543-e21c-43b2-a654-321098765432'
})
```

```bash
curl -X POST https://api.fystack.io/api/v1/wallets \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature==" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User deposit wallet",
    "wallet_type": "standard",
    "wallet_purpose": "user",
    "sweep_task_id": "987f6543-e21c-43b2-a654-321098765432"
  }'
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "wallet_id": "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
    "status": "pending"
  }
}
```

---

## Estado de creación de la billetera

**Endpoint:** `GET /wallets/creation-status/:wallet_id`

Cuando creas una billetera, el proceso se realiza de forma asíncrona. La respuesta inicial incluirá un campo `status` con uno de los siguientes valores:

- `pending`: el proceso de creación de la billetera comenzó, pero aún no ha terminado.
- `success`: la billetera se creó correctamente.
- `error`: se produjo un error al crear la billetera.

> **Warning.** Para las billeteras de tipo `standard`, el estado será `success` inmediatamente después de la creación.

> **Info.** Para las billeteras de tipo `mpc`, el proceso de creación puede tardar más, ya que implica la generación segura de claves entre múltiples partes.

### Respuesta

- `wallet_id` (string): El UUID de la billetera que se está creando.
- `status` (string): Estado actual del proceso de creación de la billetera. Puede ser `pending`, `success` o `error`.

**Request** `GET /wallets/creation-status/:wallet_id`

```bash
curl -X GET https://api.fystack.io/api/v1/wallets/creation-status/c2b71329-34c9-45aa-89d3-ddde8b15dec5 \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "wallet_id": "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
  "status": "pending"
}
```

---

## Listar todas las billeteras

**Endpoint:** `GET /workspaces/:workspace_id/wallets`

Este endpoint te permite obtener una lista paginada de todas las billeteras de tu workspace.

### Parámetros

- `wallet_type` (string): Filtra las billeteras por tipo.
- `limit` (integer): Limita la cantidad de billeteras devueltas.
- `offset` (integer): Cantidad de billeteras que se omiten antes de empezar a devolver resultados.

**Request** `GET /workspaces/:workspace_id/wallets`

```typescript
import { FystackSDK, Environment } from "@fystack/sdk"

const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

const wallets = await sdk.getWallets()
console.log('wallets', wallets)
```

```bash
curl -X GET https://api.fystack.io/api/v1/workspaces/123e4567-e89b-12d3-a456-426614174000/wallets \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
[
  {
    "id": "7f00773a-abbd-434b-b322-7b4016b3ff4a",
    "name": "MPC wallet",
    "role": "wallet_admin",
    "wallet_type": "mpc",
    "value_usd": "0",
    "top_assets": [],
    "wallet_purpose": "general"
  },
  {
    "id": "8a91b223-4c9f-5ffc-0f1g-235787cfc3f1",
    "name": "Hyper wallet",
    "role": "wallet_admin",
    "wallet_type": "standard",
    "value_usd": "0",
    "top_assets": [],
    "wallet_purpose": "general"
  }
]
```

## Obtener la dirección de depósito

**Endpoint:** `GET /wallets/:wallet_id/deposit-address`

Este endpoint devuelve una dirección de depósito para la billetera y el activo especificados.

### Parámetros de consulta

- `asset_id` (string): El UUID del activo para el que se obtiene la dirección de depósito.
- `address_type` (string): El tipo de dirección blockchain que se generará. Debe ser uno de: `evm`, `sol`, `tron` o `btc`.

### Respuesta

- `success` (boolean): Indica si la solicitud se completó correctamente.
- `data` (object): Contiene los detalles de la dirección de depósito.
  - `asset_id` (string): El UUID del activo.
  - `address` (string): La dirección blockchain para depósitos.
  - `qr_code` (string): URL de una imagen de código QR de la dirección de depósito.

> **Info.** Si se omite `address_type`, Fystack selecciona el tipo de dirección a partir del activo solicitado cuando es posible.

**Request** `GET /wallets/:wallet_id/deposit-address`

```typescript
import { FystackSDK, Environment } from "@fystack/sdk"

const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

const response = await sdk.getDepositAddress(
  "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
  AddressType.Evm
)

// Get Solana deposit address
const response = await sdk.getDepositAddress(
  "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
  AddressType.Solana
)

// Get Tron deposit address
const response = await sdk.getDepositAddress(
  "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
  AddressType.Tron
)
```

```bash
curl -X GET "https://api.fystack.io/api/v1/wallets/c2b71329-34c9-45aa-89d3-ddde8b15dec5/deposit-address?address_type=evm" \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "address": "0xA793457d84CFD255Ed68295984300C4f799E759F",
    "qr_code": "https://quickchart.io/qr?size=300&margin=2&text=0xA793457d84CFD255Ed68295984300C4f799E759F"
  }
}
```

---

## Obtener el resumen de activos de la billetera

**Endpoint:** `GET /wallets/:wallet_id/overview`

Este endpoint devuelve los activos de la billetera con sus saldos, retenciones activas, precios en USD y detalles de red. Úsalo para mostrar el portafolio de una billetera. Se excluyen los activos ocultos de la billetera y las redes deshabilitadas.

### Parámetros de ruta

- `wallet_id` (string (uuid)): El UUID de la billetera.

### Parámetros de consulta

- `offset` (integer): Cantidad de registros que se omiten. Debe estar entre 0 y 100000.
- `limit` (integer): Cantidad máxima de registros que se devuelven. Debe estar entre 0 y 1000. Omite este parámetro o establécelo en 0 para devolver todos los registros coincidentes.
- `is_native_only` (boolean): Establécelo en `true` para devolver solo activos nativos.
- `search` (string): Busca por nombre o símbolo del activo. Máximo 100 caracteres.
- `sort_by` (string): Ordena por `balance`, `price_usd` o `value_usd`. Si se omite, los activos se ordenan por nombre.
- `sort_order` (string): Dirección del orden: `asc` o `desc`. El valor predeterminado es `asc` cuando se proporciona `sort_by`.
- `min_value_usd` (number): Devuelve solo los activos cuyo valor total en USD sea al menos este monto. Debe ser 0 o mayor.
- `network_ids` (array of strings (uuid)): Filtra por UUID de red. Repite el parámetro de consulta para incluir varias redes.

### Respuesta

- `success` (boolean): Indica si la solicitud se completó correctamente.
- `message` (string): Un mensaje que describe el resultado de la operación.
- `code` (integer): Un código numérico que indica el estado del resultado (0 si fue exitoso).
- `data` (array): Los activos de la billetera que coinciden. Devuelve un array vacío cuando ningún activo coincide.
  - `balance` (string): El saldo total del activo, devuelto como string decimal.
  - `on_hold` (string): El monto reservado por retenciones activas, devuelto como string decimal.
  - `available_balance` (string): El saldo disponible para usar: saldo total menos retenciones activas.
  - `price_usd` (string): El precio en USD por unidad del activo, devuelto como string decimal.
  - `value_usd` (string): El saldo total multiplicado por el precio en USD, devuelto como string decimal.
  - `asset` (object): Los detalles del activo, incluidos su UUID, nombre, símbolo, decimales e ID de red. Consulta [Activos](https://docs.fystack.io/es/assets.md) para ver los campos del activo.
  - `network` (object): Los detalles de la red: `id`, `name`, `chain_id`, `logo_url` y `explorer_tx` cuando está disponible.

**Request** `GET /wallets/:wallet_id/overview`

```bash
curl -X GET "https://api.fystack.io/api/v1/wallets/c2b71329-34c9-45aa-89d3-ddde8b15dec5/overview?sort_by=value_usd&sort_order=desc&limit=20" \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": [
    {
      "balance": "125",
      "on_hold": "25",
      "available_balance": "100",
      "asset": {
        "id": "bf130274-e80c-43f3-aac3-c7dbfcbd74cd",
        "name": "USDC (Binance-Peg USD Coin)",
        "symbol": "USDC",
        "decimals": 18,
        "logo_url": "https://bscscan.com/token/images/centre-usdc_28.png",
        "address": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
        "asset_type": "erc20",
        "is_native": false,
        "address_type": "evm",
        "network_id": "c03b242f-5091-499c-86c5-78dbc47ed719",
        "price_usd": "1"
      },
      "price_usd": "1",
      "value_usd": "125",
      "network": {
        "id": "c03b242f-5091-499c-86c5-78dbc47ed719",
        "name": "BNB Mainnet",
        "chain_id": 56,
        "logo_url": "https://s2.coinmarketcap.com/static/img/coins/64x64/1839.png",
        "explorer_tx": "https://bscscan.com/tx/%s"
      }
    }
  ]
}
```

---

## Obtener los saldos de la billetera

**Endpoint:** `GET /wallets/:wallet_id/balances`

Este endpoint devuelve una lista plana de saldos de activos de la billetera con identificadores de activo y de red. Úsalo para consultar saldos por símbolo exacto, ID de activo o red. Se excluyen los activos ocultos de la billetera y las redes deshabilitadas.

### Parámetros de ruta

- `wallet_id` (string (uuid)): El UUID de la billetera.

### Parámetros de consulta

- `offset` (integer): Cantidad de registros que se omiten. Debe estar entre 0 y 100000.
- `limit` (integer): Cantidad máxima de registros que se devuelven. Debe estar entre 0 y 1000. Omite este parámetro o establécelo en 0 para devolver todos los registros coincidentes.
- `symbol` (array of strings): Filtra por símbolos exactos de activos, como `USDC`. La coincidencia no distingue mayúsculas de minúsculas. Cada símbolo debe contener de 1 a 20 caracteres alfanuméricos.
- `asset_id` (array of strings (uuid)): Filtra por UUID de activo.
- `network_id` (array of strings (uuid)): Filtra por UUID de red.
- `network_code` (array of strings): Filtra por códigos de red exactos, como `BSC_MAINNET`. La coincidencia no distingue mayúsculas de minúsculas. Cada código debe contener de 1 a 50 caracteres. Usa el `internal_code` de [Redes](https://docs.fystack.io/es/networks.md).

> **Info.** Repite un parámetro de consulta para indicar varios valores, por ejemplo `symbol=USDC&symbol=USDT`. Los valores dentro del mismo filtro coinciden con cualquiera de ellos. Los distintos filtros se combinan, por lo que un filtro de símbolo y uno de red deben coincidir ambos.

### Respuesta

- `success` (boolean): Indica si la solicitud se completó correctamente.
- `message` (string): Un mensaje que describe el resultado de la operación.
- `code` (integer): Un código numérico que indica el estado del resultado (0 si fue exitoso).
- `data` (array): Los activos de la billetera que coinciden. Devuelve un array vacío cuando ningún activo coincide.
  - `wallet_id` (string (uuid)): El UUID de la billetera.
  - `asset_id` (string (uuid)): El UUID del activo.
  - `symbol` (string): El símbolo del activo.
  - `asset_name` (string): El nombre del activo.
  - `asset_logo` (string): La URL del logo del activo.
  - `network_id` (string (uuid)): El UUID de la red.
  - `network_code` (string): El código interno de la red.
  - `network_name` (string): El nombre de la red.
  - `network_logo` (string): La URL del logo de la red.
  - `balance` (string): El saldo total del activo, devuelto como string decimal.
  - `on_hold` (string): El monto reservado por retenciones activas, devuelto como string decimal.
  - `available_balance` (string): El saldo disponible para usar: saldo total menos retenciones activas.
  - `price_usd` (string): El precio en USD por unidad del activo, devuelto como string decimal.
  - `value_usd` (string): El saldo total multiplicado por el precio en USD, devuelto como string decimal.

**Request** `GET /wallets/:wallet_id/balances`

```bash
curl -X GET "https://api.fystack.io/api/v1/wallets/c2b71329-34c9-45aa-89d3-ddde8b15dec5/balances?symbol=USDC&symbol=USDT&network_code=BSC_MAINNET&limit=20" \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": [
    {
      "wallet_id": "c2b71329-34c9-45aa-89d3-ddde8b15dec5",
      "asset_id": "bf130274-e80c-43f3-aac3-c7dbfcbd74cd",
      "symbol": "USDC",
      "asset_name": "USDC (Binance-Peg USD Coin)",
      "asset_logo": "https://bscscan.com/token/images/centre-usdc_28.png",
      "network_id": "c03b242f-5091-499c-86c5-78dbc47ed719",
      "network_code": "BSC_MAINNET",
      "network_name": "BNB Mainnet",
      "network_logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/1839.png",
      "balance": "125",
      "on_hold": "25",
      "available_balance": "100",
      "price_usd": "1",
      "value_usd": "125"
    }
  ]
}
```

---

## Obtener el saldo de la billetera por ID de activo

**Endpoint:** `GET /wallets/:wallet_id/balance/:asset_id`

Este endpoint devuelve el saldo total de un único activo en la billetera. Para obtener las retenciones activas y el saldo disponible, usa [Obtener los saldos de la billetera](#get-wallet-balances).

### Parámetros de ruta

- `wallet_id` (string (uuid)): El UUID de la billetera.
- `asset_id` (string (uuid)): El UUID del activo.

### Respuesta

- `success` (boolean): Indica si la solicitud se completó correctamente.
- `message` (string): Un mensaje que describe el resultado de la operación.
- `code` (integer): Un código numérico que indica el estado del resultado (0 si fue exitoso).
- `data` (string): El saldo total del activo solicitado, devuelto como string decimal.

**Request** `GET /wallets/:wallet_id/balance/:asset_id`

```bash
curl -X GET "https://api.fystack.io/api/v1/wallets/c2b71329-34c9-45aa-89d3-ddde8b15dec5/balance/bf130274-e80c-43f3-aac3-c7dbfcbd74cd" \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "ACCESS-TIMESTAMP: 1667836889" \
  -H "ACCESS-SIGN: YourBase64EncodedSignature=="
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": "125"
}
```