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

POST
/wallets

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

Parámetros

  • Name
    name
    Type
    string
    Required
    required
    Description

    Un nombre descriptivo para la billetera.

  • Name
    wallet_type
    Type
    enum: standard | mpc | hd_mpc
    Required
    required
    Description

    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.
  • Name
    wallet_purpose
    Type
    string
    Default
    default:general
    Description

    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.

  • Name
    gas_sponsorship_enabled
    Type
    boolean
    Default
    default:false
    Description

    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. También puedes cambiarlo más adelante desde la configuración de la billetera.

  • Name
    sweep_task_id
    Type
    string
    Description

    UUID de una sweep task 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.
  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

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.

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 y luego crea el maestro HD desde el modal de creación de billetera en el dashboard de Fystack. El cosigner debe estar en línea cuando se cree la billetera.

Respuesta

  • Name
    success
    Type
    boolean
    Description

    Indica si la solicitud se completó correctamente.

  • Name
    message
    Type
    string
    Description

    Un mensaje que describe el resultado de la operación.

  • Name
    code
    Type
    integer
    Description

    Un código numérico que indica el estado del resultado (0 si fue exitoso).

  • Name
    data
    Type
    object
    Description

    Contiene los detalles de la billetera.

  • Name
    wallet_id
    Type
    string
    Description

    El UUID de la billetera recién creada.

  • Name
    status
    Type
    string
    Description

    El estado actual del proceso de creación de la billetera.

Request: billetera básica

POST
/wallets
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
})

Request: con sweep task

POST
/wallets
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'
})

Response

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

Estado de creación de la billetera

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.

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

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

  • Name
    wallet_id
    Type
    string
    Description

    El UUID de la billetera que se está creando.

  • Name
    status
    Type
    string
    Description

    Estado actual del proceso de creación de la billetera. Puede ser pending, success o error.

Request

GET
/wallets/creation-status/:wallet_id
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=="

Response

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

Listar todas las billeteras

GET
/workspaces/{workspace_id}/wallets

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

Parámetros

  • Name
    wallet_type
    Type
    string
    Description

    Filtra las billeteras por tipo.

  • Name
    limit
    Type
    integer
    Description

    Limita la cantidad de billeteras devueltas.

  • Name
    offset
    Type
    integer
    Description

    Cantidad de billeteras que se omiten antes de empezar a devolver resultados.

Request

GET
/workspaces/:workspace_id/wallets
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)

Response

200
[
  {
    "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

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

  • Name
    asset_id
    Type
    string
    Description

    El UUID del activo para el que se obtiene la dirección de depósito.

  • Name
    address_type
    Type
    string
    Description

    El tipo de dirección blockchain que se generará. Debe ser uno de: evm, sol, tron o btc.

Respuesta

  • Name
    success
    Type
    boolean
    Description

    Indica si la solicitud se completó correctamente.

  • Name
    data
    Type
    object
    Description

    Contiene los detalles de la dirección de depósito.

  • Name
    asset_id
    Type
    string
    Description

    El UUID del activo.

  • Name
    address
    Type
    string
    Description

    La dirección blockchain para depósitos.

  • Name
    qr_code
    Type
    string
    Description

    URL de una imagen de código QR de la dirección de depósito.

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
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
)

Response

200
{
  "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

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

  • Name
    wallet_id
    Type
    string (uuid)
    Description

    El UUID de la billetera.

Parámetros de consulta

  • Name
    offset
    Type
    integer
    Description

    Cantidad de registros que se omiten. Debe estar entre 0 y 100000.

  • Name
    limit
    Type
    integer
    Description

    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.

  • Name
    is_native_only
    Type
    boolean
    Description

    Establécelo en true para devolver solo activos nativos.

  • Name
    search
    Type
    string
    Description

    Busca por nombre o símbolo del activo. Máximo 100 caracteres.

  • Name
    sort_by
    Type
    string
    Description

    Ordena por balance, price_usd o value_usd. Si se omite, los activos se ordenan por nombre.

  • Name
    sort_order
    Type
    string
    Description

    Dirección del orden: asc o desc. El valor predeterminado es asc cuando se proporciona sort_by.

  • Name
    min_value_usd
    Type
    number
    Description

    Devuelve solo los activos cuyo valor total en USD sea al menos este monto. Debe ser 0 o mayor.

  • Name
    network_ids
    Type
    array of strings (uuid)
    Description

    Filtra por UUID de red. Repite el parámetro de consulta para incluir varias redes.

Respuesta

  • Name
    success
    Type
    boolean
    Description

    Indica si la solicitud se completó correctamente.

  • Name
    message
    Type
    string
    Description

    Un mensaje que describe el resultado de la operación.

  • Name
    code
    Type
    integer
    Description

    Un código numérico que indica el estado del resultado (0 si fue exitoso).

  • Name
    data
    Type
    array
    Description

    Los activos de la billetera que coinciden. Devuelve un array vacío cuando ningún activo coincide.

  • Name
    balance
    Type
    string
    Description

    El saldo total del activo, devuelto como string decimal.

  • Name
    on_hold
    Type
    string
    Description

    El monto reservado por retenciones activas, devuelto como string decimal.

  • Name
    available_balance
    Type
    string
    Description

    El saldo disponible para usar: saldo total menos retenciones activas.

  • Name
    price_usd
    Type
    string
    Description

    El precio en USD por unidad del activo, devuelto como string decimal.

  • Name
    value_usd
    Type
    string
    Description

    El saldo total multiplicado por el precio en USD, devuelto como string decimal.

  • Name
    asset
    Type
    object
    Description

    Los detalles del activo, incluidos su UUID, nombre, símbolo, decimales e ID de red. Consulta Activos para ver los campos del activo.

  • Name
    network
    Type
    object
    Description

    Los detalles de la red: id, name, chain_id, logo_url y explorer_tx cuando está disponible.

Request

GET
/wallets/:wallet_id/overview
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=="

Response

200
{
  "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

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

  • Name
    wallet_id
    Type
    string (uuid)
    Description

    El UUID de la billetera.

Parámetros de consulta

  • Name
    offset
    Type
    integer
    Description

    Cantidad de registros que se omiten. Debe estar entre 0 y 100000.

  • Name
    limit
    Type
    integer
    Description

    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.

  • Name
    symbol
    Type
    array of strings
    Description

    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.

  • Name
    asset_id
    Type
    array of strings (uuid)
    Description

    Filtra por UUID de activo.

  • Name
    network_id
    Type
    array of strings (uuid)
    Description

    Filtra por UUID de red.

  • Name
    network_code
    Type
    array of strings
    Description

    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.

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

  • Name
    success
    Type
    boolean
    Description

    Indica si la solicitud se completó correctamente.

  • Name
    message
    Type
    string
    Description

    Un mensaje que describe el resultado de la operación.

  • Name
    code
    Type
    integer
    Description

    Un código numérico que indica el estado del resultado (0 si fue exitoso).

  • Name
    data
    Type
    array
    Description

    Los activos de la billetera que coinciden. Devuelve un array vacío cuando ningún activo coincide.

  • Name
    wallet_id
    Type
    string (uuid)
    Description

    El UUID de la billetera.

  • Name
    asset_id
    Type
    string (uuid)
    Description

    El UUID del activo.

  • Name
    symbol
    Type
    string
    Description

    El símbolo del activo.

  • Name
    asset_name
    Type
    string
    Description

    El nombre del activo.

  • Name
    asset_logo
    Type
    string
    Description

    La URL del logo del activo.

  • Name
    network_id
    Type
    string (uuid)
    Description

    El UUID de la red.

  • Name
    network_code
    Type
    string
    Description

    El código interno de la red.

  • Name
    network_name
    Type
    string
    Description

    El nombre de la red.

  • Name
    network_logo
    Type
    string
    Description

    La URL del logo de la red.

  • Name
    balance
    Type
    string
    Description

    El saldo total del activo, devuelto como string decimal.

  • Name
    on_hold
    Type
    string
    Description

    El monto reservado por retenciones activas, devuelto como string decimal.

  • Name
    available_balance
    Type
    string
    Description

    El saldo disponible para usar: saldo total menos retenciones activas.

  • Name
    price_usd
    Type
    string
    Description

    El precio en USD por unidad del activo, devuelto como string decimal.

  • Name
    value_usd
    Type
    string
    Description

    El saldo total multiplicado por el precio en USD, devuelto como string decimal.

Request

GET
/wallets/:wallet_id/balances
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=="

Response

200
{
  "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

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.

Parámetros de ruta

  • Name
    wallet_id
    Type
    string (uuid)
    Description

    El UUID de la billetera.

  • Name
    asset_id
    Type
    string (uuid)
    Description

    El UUID del activo.

Respuesta

  • Name
    success
    Type
    boolean
    Description

    Indica si la solicitud se completó correctamente.

  • Name
    message
    Type
    string
    Description

    Un mensaje que describe el resultado de la operación.

  • Name
    code
    Type
    integer
    Description

    Un código numérico que indica el estado del resultado (0 si fue exitoso).

  • Name
    data
    Type
    string
    Description

    El saldo total del activo solicitado, devuelto como string decimal.

Request

GET
/wallets/:wallet_id/balance/:asset_id
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=="

Response

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