Wallets

Wallets are secure containers for managing digital assets. Fystack offers different wallet types to suit your needs, including Hyper wallets and MPC (Multi-Party Computation) wallets.

Wallet types

Fystack supports two distinct wallet types, each designed for specific use cases and security requirements:

Hyper Wallet

Hyper wallets are derived using Hierarchical Deterministic (HD) key derivation per workspace. This approach provides:

Efficient key management: Uses a single master seed to derive multiple wallet keys
End-user focused: Ideal for generating individual wallets for your end users
Quick creation: Instant wallet generation with immediate success status
Deterministic: Wallets can be recreated from the same seed if needed
Cost-effective: Lower computational overhead for high-volume wallet creation

Best for: Consumer applications, user wallets, high-volume wallet generation

MPC Wallet

MPC (Multi-Party Computation) wallets use advanced cryptographic techniques where the private key is split into multiple shares and distributed across different Mpcium nodes:

Enhanced security: Private key never exists in its complete form on any single node
Distributed trust: Key shares are distributed across multiple secure nodes
Hot wallet protection: Provides institutional-grade security for active wallets
Threshold signatures: Requires consensus from multiple nodes to sign transactions
Longer creation time: Key generation process takes more time due to cryptographic complexity

Best for: Hot wallets, institutional custody, high-value asset storage, exchange wallets

Choosing the right wallet type

Wallet Type	Hyper	MPC
Security Level	High	Institutional-grade
Creation Speed	Instant	7-15 seconds
Use Case	End-user wallets	Hot wallets, custody
Key Management	HD derivation	Multi-party computation
Cost	Lower	Higher
Recovery	HD seed-based	Multi-party recovery

Choose Hyper wallets when you need to quickly generate wallets for individual users. Choose MPC wallets when you need maximum security for operational wallets that hold significant value or require institutional-grade protection.

POST/wallets

Create a wallet

To create a new wallet, send a POST request to the /wallets endpoint with the required parameters.

Required parameters

Name
name
Type
string
Description
A descriptive name for the wallet.
Name
wallet_type
Type
string
Description
The type of wallet to create. Must be either standard or mpc.

Optional parameters

Name

wallet_purpose

Type

enum string

Description

The purpose of the wallet. Defaults to general. See the table below for the available values.

Value	Description
`general`	Default multi-purpose wallet for everyday operations.
`user`	Wallet assigned to an end-user in your client application.
`one_time_use`	Address is intended for a single use only, such as a one-off merchant order.

Name
sweep_task_params
Type
object
Description
Parameters for creating an automatic sweep task. Cannot be used with sweep_task_id.

Name: min_trigger_value_usd
Type: decimal
Description: Minimum USD value threshold to trigger the sweep.

Name: destination_wallet_id
Type: string
Description: UUID of the destination wallet or addressbook record ID if destination_type is address_book.

Name: destination_type
Type: string
Description: Type of destination. Must be either internal_wallet or address_book. Defaults to internal_wallet.

Name
sweep_task_id
Type
string
Description
UUID of an existing sweep task to attach to this wallet. If provided, sweep_task_params will be ignored.

Sweep Tasks

When creating a wallet, you can automatically set up fund sweeping by either:

Creating a new sweep task with sweep_task_params
Attaching an existing sweep task with sweep_task_id

How sweep tasks work

Automatic monitoring: The system continuously monitors the wallet balance
Threshold triggering: When the wallet's USD value reaches the min_trigger_value_usd, a sweep is triggered
Destination flexibility: Funds can be swept to internal wallets or external addresses from your address book
User wallets: Wallets with wallet_purpose: "user" are hidden from the portal interface

If both sweep_task_params and sweep_task_id are provided, the existing sweep task ID takes precedence and the parameters are ignored.

Response

Name
success
Type
boolean
Description
Indicates whether the request was successful.
Name
message
Type
string
Description
A message describing the result of the operation.
Name
code
Type
integer
Description
A numeric code indicating the result status (0 for success).
Name
data
Type
object
Description
Contains the wallet details.

Name: wallet_id
Type: string
Description: The UUID of the newly created wallet.

Name: status
Type: string
Description: The current status of the wallet creation process.

Request

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

// Create wallet with new sweep task
await sdk.createWallet({
    name: 'MPC wallet with sweep',
    walletType: WalletType.MPC,
    walletPurpose: WalletPurpose.User,
    sweepTaskParams: {
        minTriggerValueUsd: '100.00',
        destinationWalletId: '123e4567-e89b-12d3-a456-426614174001',
        destinationType: 'internal_wallet'
    }
})

// Or attach existing sweep task
await sdk.createWallet({
    name: 'Hyper wallet',
    walletType: WalletType.Standard,
    sweepTaskId: '987f6543-e21c-43b2-a654-321098765432'
})

Response

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

GET/wallets/creation-status/:wallet_id

Wallet creation status

When you create a wallet, the process happens asynchronously. The initial response will include a status field with one of the following values:

pending: The wallet creation process has started but is not yet complete.
success: The wallet has been successfully created.
error: There was an error creating the wallet.

For standard wallet types, the status will be success immediately after creation.

For mpc wallet types, the creation process may take longer as it involves secure key generation across multiple parties.

Response

Name
wallet_id
Type
string
Description
The UUID of the wallet being created.
Name
status
Type
string
Description
Current status of the wallet creation process. Can be pending, success, or error.

cURL

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

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

GET/workspaces/:workspace_id/wallets

List all wallets

This endpoint allows you to retrieve a paginated list of all wallets in your workspace.

Optional parameters

Name
wallet_type
Type
string
Description
Filter wallets by type.
Name
limit
Type
integer
Description
Limit the number of wallets returned.
Name
offset
Type
integer
Description
Number of wallets to skip before starting to return results.

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

[
  {
    "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"
  }
]

GET/wallets/:wallet_id/deposit-address

Get deposit address

This endpoint returns a deposit address for the specified wallet and asset.

Query parameters

Name
asset_id
Type
string
Description
The UUID of the asset to get the deposit address for.
Name
address_type
Type
string
Description
The type of blockchain address to generate. Must be one of: evm, sol, btc, tron.

Response

Name
success
Type
boolean
Description
Indicates whether the request was successful.
Name
data
Type
object
Description
Contains the deposit address details.

Name: asset_id
Type: string
Description: The UUID of the asset.

Name: address
Type: string
Description: The blockchain address for deposits.

Name: qr_code
Type: string
Description: URL to a QR code image of the deposit address.

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

Get wallet asset overview

This endpoint returns wallet assets with balances, active holds, USD prices, and network details. Use it to display a wallet portfolio. Hidden wallet assets and disabled networks are excluded.

Path parameters

Name
wallet_id
Type
string (uuid)
Description
The UUID of the wallet.

Optional query parameters

Name
offset
Type
integer
Description
Number of records to skip. Must be between 0 and 100000.
Name
limit
Type
integer
Description
Maximum number of records to return. Must be between 0 and 1000. Omit this parameter or set it to 0 to return all matching records.
Name
is_native_only
Type
boolean
Description
Set to true to return only native assets.
Name
search
Type
string
Description
Search by asset name or symbol. Maximum 100 characters.
Name
sort_by
Type
string
Description
Sort by balance, price_usd, or value_usd. When omitted, assets are sorted by name.
Name
sort_order
Type
string
Description
Sort direction: asc or desc. Defaults to asc when sort_by is provided.
Name
min_value_usd
Type
number
Description
Only return assets whose total USD value is at least this amount. Must be 0 or greater.
Name
network_ids
Type
array of strings (uuid)
Description
Filter by network UUIDs. Repeat the query parameter to include multiple networks.

Response

Name
success
Type
boolean
Description
Indicates whether the request was successful.
Name
message
Type
string
Description
A message describing the result of the operation.
Name
code
Type
integer
Description
A numeric code indicating the result status (0 for success).
Name
data
Type
array
Description
The matching wallet assets. Returns an empty array when no assets match.

Name: balance
Type: string
Description: The total asset balance, returned as a decimal string.

Name: on_hold
Type: string
Description: The amount reserved by active holds, returned as a decimal string.

Name: available_balance
Type: string
Description: The balance available to use: total balance minus active holds.

Name: price_usd
Type: string
Description: The USD price per unit of the asset, returned as a decimal string.

Name: value_usd
Type: string
Description: The total balance multiplied by the USD price, returned as a decimal string.

Name: asset
Type: object
Description: The asset details, including its UUID, name, symbol, decimals, and network ID. See Assets for asset fields.

Name: network
Type: object
Description: The network details: id, name, chain_id, logo_url, and explorer_tx when available.

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

{
  "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"
      }
    }
  ]
}

GET/wallets/:wallet_id/balances

Get wallet balances

This endpoint returns a flat list of wallet asset balances with asset and network identifiers. Use it to look up balances by exact symbol, asset ID, or network. Hidden wallet assets and disabled networks are excluded.

Path parameters

Name
wallet_id
Type
string (uuid)
Description
The UUID of the wallet.

Optional query parameters

Name
offset
Type
integer
Description
Number of records to skip. Must be between 0 and 100000.
Name
limit
Type
integer
Description
Maximum number of records to return. Must be between 0 and 1000. Omit this parameter or set it to 0 to return all matching records.
Name
symbol
Type
array of strings
Description
Filter by exact asset symbols, such as USDC. Matching is case-insensitive. Each symbol must contain 1 to 20 alphanumeric characters.
Name
asset_id
Type
array of strings (uuid)
Description
Filter by asset UUIDs.
Name
network_id
Type
array of strings (uuid)
Description
Filter by network UUIDs.
Name
network_code
Type
array of strings
Description
Filter by exact network codes, such as BSC_MAINNET. Matching is case-insensitive. Each code must contain 1 to 50 characters. Use the internal_code from Networks.

Repeat a query parameter to supply multiple values, for example symbol=USDC&symbol=USDT. Values within the same filter match any of those values. Different filters are combined, so a symbol and network filter must both match.

Response

Name
success
Type
boolean
Description
Indicates whether the request was successful.
Name
message
Type
string
Description
A message describing the result of the operation.
Name
code
Type
integer
Description
A numeric code indicating the result status (0 for success).
Name
data
Type
array
Description
The matching wallet assets. Returns an empty array when no assets match.

Name: wallet_id
Type: string (uuid)
Description: The UUID of the wallet.

Name: asset_id
Type: string (uuid)
Description: The UUID of the asset.

Name: symbol
Type: string
Description: The asset symbol.

Name: asset_name
Type: string
Description: The asset name.

Name: asset_logo
Type: string
Description: The URL of the asset logo.

Name: network_id
Type: string (uuid)
Description: The UUID of the network.

Name: network_code
Type: string
Description: The internal code of the network.

Name: network_name
Type: string
Description: The network name.

Name: network_logo
Type: string
Description: The URL of the network logo.

Name: balance
Type: string
Description: The total asset balance, returned as a decimal string.

Name: on_hold
Type: string
Description: The amount reserved by active holds, returned as a decimal string.

Name: available_balance
Type: string
Description: The balance available to use: total balance minus active holds.

Name: price_usd
Type: string
Description: The USD price per unit of the asset, returned as a decimal string.

Name: value_usd
Type: string
Description: The total balance multiplied by the USD price, returned as a decimal string.

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

{
  "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"
    }
  ]
}

GET/wallets/:wallet_id/balance/:asset_id

Get wallet balance by asset ID

This endpoint returns the total balance of a single asset in the wallet. To retrieve active holds and the available balance, use Get wallet balances.

Path parameters

Name
wallet_id
Type
string (uuid)
Description
The UUID of the wallet.
Name
asset_id
Type
string (uuid)
Description
The UUID of the asset.

Response

Name
success
Type
boolean
Description
Indicates whether the request was successful.
Name
message
Type
string
Description
A message describing the result of the operation.
Name
code
Type
integer
Description
A numeric code indicating the result status (0 for success).
Name
data
Type
string
Description
The total balance for the requested asset, returned as a decimal string.

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

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