---
title: "Wallets"
description: "This guide explains how to create and manage wallets using the Fystack API."
url: https://docs.fystack.io/wallets
last_updated: 2026-10-15
---

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

# 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.

---

## Create a wallet

**Endpoint:** `POST /wallets`

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

### Required parameters

- `name` (string): A descriptive name for the wallet.
- `wallet_type` (string): The type of wallet to create. Must be either `standard` or `mpc`.

### Optional parameters

- `wallet_purpose` (string): 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. Defaults to `general`.
- `gas_sponsorship_enabled` (boolean): 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](https://docs.fystack.io/product/gas-station.md). Disabled by default; it can also be changed later from the wallet settings.
- `sweep_task_id` (string): UUID of an existing [sweep task](https://docs.fystack.io/product/automation.md#sweep-tasks) to attach to this wallet. Create the sweep task first, then copy its ID from the Automation page in the dashboard.

### Sweep tasks

To sweep funds out of new wallets automatically, attach a sweep task when you create them:

1. **Create a sweep task** under **Automation > Add Sweep Task** in the dashboard. See [Automation](https://docs.fystack.io/product/automation.md#sweep-tasks).
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
- **User wallets**: Wallets with `wallet_purpose: "user"` are hidden from the portal interface

> **Info: 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

- `success` (boolean): Indicates whether the request was successful.
- `message` (string): A message describing the result of the operation.
- `code` (integer): A numeric code indicating the result status (0 for success).
- `data` (object): Contains the wallet details.
  - `wallet_id` (string): The UUID of the newly created wallet.
  - `status` (string): The current status of the wallet creation process.

**Request: Basic wallet** `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: With 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"
  }
}
```

---

## Wallet creation status

**Endpoint:** `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.

> **Warning.** For `standard` wallet types, the status will be `success` immediately after creation.

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

### Response

- `wallet_id` (string): The UUID of the wallet being created.
- `status` (string): Current status of the wallet creation process. Can be `pending`, `success`, or `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"
}
```

---

## List all wallets

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

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

### Optional parameters

- `wallet_type` (string): Filter wallets by type.
- `limit` (integer): Limit the number of wallets returned.
- `offset` (integer): Number of wallets to skip before starting to return results.

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

## Get deposit address

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

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

### Query parameters

- `asset_id` (string): The UUID of the asset to get the deposit address for.
- `address_type` (string): The type of blockchain address to generate. Must be one of: `evm`, `sol`, `tron`, or `btc`.

### Response

- `success` (boolean): Indicates whether the request was successful.
- `data` (object): Contains the deposit address details.
  - `asset_id` (string): The UUID of the asset.
  - `address` (string): The blockchain address for deposits.
  - `qr_code` (string): URL to a QR code image of the deposit address.

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

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

---

## Get wallet asset overview

**Endpoint:** `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

- `wallet_id` (string (uuid)): The UUID of the wallet.

### Optional query parameters

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

### Response

- `success` (boolean): Indicates whether the request was successful.
- `message` (string): A message describing the result of the operation.
- `code` (integer): A numeric code indicating the result status (0 for success).
- `data` (array): The matching wallet assets. Returns an empty array when no assets match.
  - `balance` (string): The total asset balance, returned as a decimal string.
  - `on_hold` (string): The amount reserved by active holds, returned as a decimal string.
  - `available_balance` (string): The balance available to use: total balance minus active holds.
  - `price_usd` (string): The USD price per unit of the asset, returned as a decimal string.
  - `value_usd` (string): The total balance multiplied by the USD price, returned as a decimal string.
  - `asset` (object): The asset details, including its UUID, name, symbol, decimals, and network ID. See [Assets](https://docs.fystack.io/assets.md) for asset fields.
  - `network` (object): The network details: `id`, `name`, `chain_id`, `logo_url`, and `explorer_tx` when available.

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

---

## Get wallet balances

**Endpoint:** `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

- `wallet_id` (string (uuid)): The UUID of the wallet.

### Optional query parameters

- `offset` (integer): Number of records to skip. Must be between 0 and 100000.
- `limit` (integer): 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.
- `symbol` (array of strings): Filter by exact asset symbols, such as `USDC`. Matching is case-insensitive. Each symbol must contain 1 to 20 alphanumeric characters.
- `asset_id` (array of strings (uuid)): Filter by asset UUIDs.
- `network_id` (array of strings (uuid)): Filter by network UUIDs.
- `network_code` (array of strings): 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](https://docs.fystack.io/networks.md).

> **Info.** 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

- `success` (boolean): Indicates whether the request was successful.
- `message` (string): A message describing the result of the operation.
- `code` (integer): A numeric code indicating the result status (0 for success).
- `data` (array): The matching wallet assets. Returns an empty array when no assets match.
  - `wallet_id` (string (uuid)): The UUID of the wallet.
  - `asset_id` (string (uuid)): The UUID of the asset.
  - `symbol` (string): The asset symbol.
  - `asset_name` (string): The asset name.
  - `asset_logo` (string): The URL of the asset logo.
  - `network_id` (string (uuid)): The UUID of the network.
  - `network_code` (string): The internal code of the network.
  - `network_name` (string): The network name.
  - `network_logo` (string): The URL of the network logo.
  - `balance` (string): The total asset balance, returned as a decimal string.
  - `on_hold` (string): The amount reserved by active holds, returned as a decimal string.
  - `available_balance` (string): The balance available to use: total balance minus active holds.
  - `price_usd` (string): The USD price per unit of the asset, returned as a decimal string.
  - `value_usd` (string): The total balance multiplied by the USD price, returned as a decimal string.

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

---

## Get wallet balance by asset ID

**Endpoint:** `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](#get-wallet-balances).

### Path parameters

- `wallet_id` (string (uuid)): The UUID of the wallet.
- `asset_id` (string (uuid)): The UUID of the asset.

### Response

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

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