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 wallet types:

Hyper MPC
How it works Keys derived from one master seed per workspace (HD derivation) Private key split into shares across Mpcium nodes, never assembled in one place
Security High Institutional-grade, threshold signatures
Creation speed Instant, returns success immediately 7-15 seconds
Cost Lower Higher
Recovery Recreate from the HD seed Multi-party recovery
Best for End-user wallets, consumer apps, high-volume generation Hot wallets, custody, exchange and high-value wallets

Create a wallet

POST
/wallets

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

Parameters

  • Name
    name
    Type
    string
    Required
    required
    Description

    A descriptive name for the wallet.

  • Name
    wallet_type
    Type
    string
    Required
    required
    Description

    The type of wallet to create. Must be either standard or mpc.

  • Name
    wallet_purpose
    Type
    string
    Default
    default:general
    Description

    The purpose of the wallet. Must be one of general, user, gas_tank, payment, or one_time_use. If set to user, the wallet will be hidden from the portal.

  • Name
    gas_sponsorship_enabled
    Type
    boolean
    Default
    default:false
    Description

    Sponsor gas for token transfers from this wallet on EVM, Solana, and TRON networks, so the wallet does not need to hold the native coin. Gas is paid from the workspace gas tank, see Gas Station. It can also be changed later from the wallet settings.

  • Name
    sweep_task_id
    Type
    string
    Description

    UUID of an existing sweep task to attach to this wallet. Create the sweep task first, then copy its ID from the Automation page in the dashboard.

What is a sweep task? Automatically move funds out of new wallets

A sweep task automatically moves funds from a wallet to another wallet or address once its balance reaches a set USD value, so you don't have to collect deposits by hand.

To set one up for new wallets:

  1. Create a sweep task under Automation > Add Sweep Task in the dashboard. See Automation.
  2. Copy the sweep task ID from the Automation page.
  3. Pass it as sweep_task_id when creating each wallet.

How sweep tasks work

  • Automatic monitoring: The system continuously monitors the wallet balance
  • Threshold triggering: When the wallet's USD value reaches the task's minimum trigger value, a sweep is triggered
  • Destination flexibility: Funds can be swept to internal wallets or external addresses from your address book

Reuse one sweep task across wallets

Attach the same sweep_task_id to every wallet that should sweep to the same destination. Updating that one task then applies to every attached wallet.

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: Basic wallet

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: With 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"
  }
}

Wallet creation status

GET
/wallets/creation-status/{wallet_id}

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.

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

List all wallets

GET
/workspaces/{workspace_id}/wallets

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

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

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

Get deposit address

GET
/wallets/{wallet_id}/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, tron, or btc.

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.

If address_type is omitted, Fystack selects the address type from the requested asset when possible.

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

Get wallet asset overview

GET
/wallets/{wallet_id}/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.

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

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

Get wallet balances

GET
/wallets/{wallet_id}/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.

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

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

Get wallet balance by asset ID

GET
/wallets/{wallet_id}/balance/{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

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