Ví

Ví là nơi lưu trữ an toàn để quản lý tài sản số. Fystack cung cấp nhiều loại ví phù hợp với nhu cầu của bạn, bao gồm Hyper wallet và ví MPC (Multi-Party Computation).

Các loại ví

Fystack hỗ trợ hai loại ví:

	Hyper	MPC
Cách hoạt động	Khóa được dẫn xuất từ một master seed duy nhất cho mỗi workspace (dẫn xuất HD)	Khóa riêng tư được chia thành nhiều phần trên các node Mpcium, không bao giờ được ghép lại tại một nơi
Bảo mật	Cao	Cấp độ tổ chức, chữ ký ngưỡng
Tốc độ tạo	Tức thì, trả về `success` ngay lập tức	7-15 giây
Chi phí	Thấp hơn	Cao hơn
Khôi phục	Tái tạo từ HD seed	Khôi phục đa bên
Phù hợp nhất cho	Ví người dùng cuối, ứng dụng tiêu dùng, tạo ví với số lượng lớn	Hot wallet, lưu ký, sàn giao dịch và ví giá trị cao

Tạo ví

POST

/wallets

Để tạo ví mới, hãy gửi một request POST đến endpoint /wallets với các tham số bắt buộc.

Tham số

Name
name
Type
string
Required
required
Description
Tên mô tả cho ví.
Name
wallet_type
Type
enum: standard | mpc | hd_mpc
Required
required
Description
Loại ví cần tạo:
- standard: Hyper. Được dẫn xuất HD từ seed đã mã hóa của workspace. Một khóa duy nhất, thông lượng cao.
- mpc: MPC Cloud. Ký MPC được quản lý hoàn toàn. Chính sách và phê duyệt của bạn quyết định mọi giao dịch.
- hd_mpc: Co-signed HD MPC. Được thêm dưới HD master của bạn và đồng ký với server cosigner của bạn, nên Fystack không thể tự ký một mình. Hãy thiết lập cosigner trước.
Name
wallet_purpose
Type
string
Default
default:general
Description
Mục đích của ví. Phải là một trong các giá trị general, user, gas_tank, payment hoặc one_time_use. Nếu đặt là user, ví sẽ bị ẩn khỏi portal.
Name
gas_sponsorship_enabled
Type
boolean
Default
default:false
Description
Tài trợ gas cho các giao dịch chuyển token từ ví này trên các mạng lưới EVM, Solana và TRON, để ví không cần nắm giữ coin gốc. Gas được trả từ gas tank của workspace, xem Gas Station. Bạn cũng có thể thay đổi thiết lập này sau trong phần cài đặt ví.
Name
sweep_task_id
Type
string
Description
UUID của một sweep task hiện có để gắn vào ví này. Hãy tạo sweep task trước, sau đó sao chép ID của nó từ trang Automation trên dashboard.

Sweep task là gì? Tự động chuyển tiền ra khỏi các ví mới

Sweep task tự động chuyển tiền từ một ví sang ví hoặc địa chỉ khác khi số dư đạt đến một giá trị USD đã định, nhờ đó bạn không phải gom tiền nạp thủ công.

Để thiết lập cho các ví mới:

Tạo một sweep task tại Automation > Add Sweep Task trên dashboard. Xem Tự động hóa.
Sao chép ID của sweep task từ trang Automation.
Truyền ID đó vào sweep_task_id khi tạo mỗi ví.

Cách sweep task hoạt động

Giám sát tự động: Hệ thống liên tục theo dõi số dư ví
Kích hoạt theo ngưỡng: Khi giá trị USD của ví đạt đến giá trị kích hoạt tối thiểu của task, việc gom tiền sẽ được kích hoạt
Linh hoạt về đích đến: Tiền có thể được gom về các ví nội bộ hoặc địa chỉ bên ngoài trong sổ địa chỉ của bạn

Dùng lại một sweep task cho nhiều ví

Gắn cùng một sweep_task_id cho mọi ví cần gom tiền về cùng một đích. Khi cập nhật task đó, thay đổi sẽ được áp dụng cho tất cả các ví đã gắn.

Thiết lập server cosigner trước khi dùng hd_mpc

Ví hd_mpc được dẫn xuất từ một HD-MPC master được ký cùng server cosigner. Trước khi gọi endpoint này, hãy cài đặt và ghép nối server cosigner, sau đó tạo HD master từ modal tạo ví trên dashboard Fystack. Cosigner phải đang trực tuyến khi ví được tạo.

Phản hồi

Name
success
Type
boolean
Description
Cho biết request có thành công hay không.
Name
message
Type
string
Description
Thông điệp mô tả kết quả của thao tác.
Name
code
Type
integer
Description
Mã số cho biết trạng thái kết quả (0 nghĩa là thành công).
Name
data
Type
object
Description
Chứa thông tin chi tiết của ví.

Name: wallet_id
Type: string
Description: UUID của ví vừa được tạo.

Name: status
Type: string
Description: Trạng thái hiện tại của quá trình tạo ví.

Request: Ví cơ bản

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: Kèm 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"
  }
}

Trạng thái tạo ví

GET

/wallets/creation-status/{wallet_id}

Khi bạn tạo ví, quá trình diễn ra bất đồng bộ. Phản hồi ban đầu sẽ có trường status với một trong các giá trị sau:

pending: Quá trình tạo ví đã bắt đầu nhưng chưa hoàn tất.
success: Ví đã được tạo thành công.
error: Đã xảy ra lỗi khi tạo ví.

Với loại ví standard, trạng thái sẽ là success ngay sau khi tạo.

Với loại ví mpc, quá trình tạo có thể mất nhiều thời gian hơn vì cần tạo khóa an toàn giữa nhiều bên.

Phản hồi

Name
wallet_id
Type
string
Description
UUID của ví đang được tạo.
Name
status
Type
string
Description
Trạng thái hiện tại của quá trình tạo ví. Có thể là pending, success hoặc 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"
}

Liệt kê tất cả ví

GET

/workspaces/{workspace_id}/wallets

Endpoint này cho phép bạn lấy danh sách phân trang của tất cả ví trong workspace.

Tham số

Name
wallet_type
Type
string
Description
Lọc ví theo loại.
Name
limit
Type
integer
Description
Giới hạn số ví được trả về.
Name
offset
Type
integer
Description
Số ví cần bỏ qua trước khi bắt đầu trả về kết quả.

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

Lấy địa chỉ nạp tiền

GET

/wallets/{wallet_id}/deposit-address

Endpoint này trả về địa chỉ nạp tiền cho ví và tài sản được chỉ định.

Tham số truy vấn

Name
asset_id
Type
string
Description
UUID của tài sản cần lấy địa chỉ nạp tiền.
Name
address_type
Type
string
Description
Loại địa chỉ blockchain cần tạo. Phải là một trong các giá trị: evm, sol, tron hoặc btc.

Phản hồi

Name
success
Type
boolean
Description
Cho biết request có thành công hay không.
Name
data
Type
object
Description
Chứa thông tin chi tiết địa chỉ nạp tiền.

Name: asset_id
Type: string
Description: UUID của tài sản.

Name: address
Type: string
Description: Địa chỉ blockchain để nạp tiền.

Name: qr_code
Type: string
Description: URL đến ảnh mã QR của địa chỉ nạp tiền.

Nếu bỏ qua address_type, Fystack sẽ chọn loại địa chỉ dựa trên tài sản được yêu cầu khi có thể.

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

Lấy tổng quan tài sản của ví

GET

/wallets/{wallet_id}/overview

Endpoint này trả về các tài sản của ví kèm số dư, khoản tạm giữ đang hiệu lực, giá USD và thông tin mạng lưới. Dùng endpoint này để hiển thị danh mục tài sản của ví. Các tài sản ví bị ẩn và mạng lưới bị tắt sẽ không được bao gồm.

Tham số đường dẫn

Name
wallet_id
Type
string (uuid)
Description
UUID của ví.

Tham số truy vấn

Name
offset
Type
integer
Description
Số bản ghi cần bỏ qua. Phải nằm trong khoảng từ 0 đến 100000.
Name
limit
Type
integer
Description
Số bản ghi tối đa cần trả về. Phải nằm trong khoảng từ 0 đến 1000. Bỏ qua tham số này hoặc đặt bằng 0 để trả về tất cả bản ghi phù hợp.
Name
is_native_only
Type
boolean
Description
Đặt là true để chỉ trả về các tài sản gốc.
Name
search
Type
string
Description
Tìm kiếm theo tên hoặc ký hiệu tài sản. Tối đa 100 ký tự.
Name
sort_by
Type
string
Description
Sắp xếp theo balance, price_usd hoặc value_usd. Khi bỏ qua, tài sản được sắp xếp theo tên.
Name
sort_order
Type
string
Description
Chiều sắp xếp: asc hoặc desc. Mặc định là asc khi có sort_by.
Name
min_value_usd
Type
number
Description
Chỉ trả về các tài sản có tổng giá trị USD tối thiểu bằng số này. Phải lớn hơn hoặc bằng 0.
Name
network_ids
Type
array of strings (uuid)
Description
Lọc theo UUID mạng lưới. Lặp lại tham số truy vấn để bao gồm nhiều mạng lưới.

Phản hồi

Name
success
Type
boolean
Description
Cho biết request có thành công hay không.
Name
message
Type
string
Description
Thông điệp mô tả kết quả của thao tác.
Name
code
Type
integer
Description
Mã số cho biết trạng thái kết quả (0 nghĩa là thành công).
Name
data
Type
array
Description
Các tài sản ví phù hợp. Trả về mảng rỗng khi không có tài sản nào phù hợp.

Name: balance
Type: string
Description: Tổng số dư tài sản, trả về dưới dạng chuỗi số thập phân.

Name: on_hold
Type: string
Description: Số tiền đang bị giữ bởi các khoản tạm giữ hiệu lực, trả về dưới dạng chuỗi số thập phân.

Name: available_balance
Type: string
Description: Số dư khả dụng: tổng số dư trừ đi các khoản tạm giữ đang hiệu lực.

Name: price_usd
Type: string
Description: Giá USD trên mỗi đơn vị tài sản, trả về dưới dạng chuỗi số thập phân.

Name: value_usd
Type: string
Description: Tổng số dư nhân với giá USD, trả về dưới dạng chuỗi số thập phân.

Name: asset
Type: object
Description: Thông tin chi tiết tài sản, bao gồm UUID, tên, ký hiệu, số chữ số thập phân và ID mạng lưới. Xem Tài sản để biết các trường của tài sản.

Name: network
Type: object
Description: Thông tin mạng lưới: id, name, chain_id, logo_url và explorer_tx khi có.

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

Lấy số dư ví

GET

/wallets/{wallet_id}/balances

Endpoint này trả về danh sách phẳng số dư tài sản của ví kèm mã định danh tài sản và mạng lưới. Dùng endpoint này để tra cứu số dư theo chính xác ký hiệu, ID tài sản hoặc mạng lưới. Các tài sản ví bị ẩn và mạng lưới bị tắt sẽ không được bao gồm.

Tham số đường dẫn

Name
wallet_id
Type
string (uuid)
Description
UUID của ví.

Tham số truy vấn

Name
offset
Type
integer
Description
Số bản ghi cần bỏ qua. Phải nằm trong khoảng từ 0 đến 100000.
Name
limit
Type
integer
Description
Số bản ghi tối đa cần trả về. Phải nằm trong khoảng từ 0 đến 1000. Bỏ qua tham số này hoặc đặt bằng 0 để trả về tất cả bản ghi phù hợp.
Name
symbol
Type
array of strings
Description
Lọc theo chính xác ký hiệu tài sản, ví dụ USDC. Không phân biệt chữ hoa chữ thường. Mỗi ký hiệu phải gồm 1 đến 20 ký tự chữ và số.
Name
asset_id
Type
array of strings (uuid)
Description
Lọc theo UUID tài sản.
Name
network_id
Type
array of strings (uuid)
Description
Lọc theo UUID mạng lưới.
Name
network_code
Type
array of strings
Description
Lọc theo chính xác mã mạng lưới, ví dụ BSC_MAINNET. Không phân biệt chữ hoa chữ thường. Mỗi mã phải gồm 1 đến 50 ký tự. Dùng internal_code từ Mạng lưới.

Lặp lại một tham số truy vấn để truyền nhiều giá trị, ví dụ symbol=USDC&symbol=USDT. Các giá trị trong cùng một bộ lọc sẽ khớp với bất kỳ giá trị nào trong số đó. Các bộ lọc khác nhau được kết hợp với nhau, nên bộ lọc ký hiệu và bộ lọc mạng lưới đều phải khớp.

Phản hồi

Name
success
Type
boolean
Description
Cho biết request có thành công hay không.
Name
message
Type
string
Description
Thông điệp mô tả kết quả của thao tác.
Name
code
Type
integer
Description
Mã số cho biết trạng thái kết quả (0 nghĩa là thành công).
Name
data
Type
array
Description
Các tài sản ví phù hợp. Trả về mảng rỗng khi không có tài sản nào phù hợp.

Name: wallet_id
Type: string (uuid)
Description: UUID của ví.

Name: asset_id
Type: string (uuid)
Description: UUID của tài sản.

Name: symbol
Type: string
Description: Ký hiệu tài sản.

Name: asset_name
Type: string
Description: Tên tài sản.

Name: asset_logo
Type: string
Description: URL logo của tài sản.

Name: network_id
Type: string (uuid)
Description: UUID của mạng lưới.

Name: network_code
Type: string
Description: Mã nội bộ của mạng lưới.

Name: network_name
Type: string
Description: Tên mạng lưới.

Name: network_logo
Type: string
Description: URL logo của mạng lưới.

Name: balance
Type: string
Description: Tổng số dư tài sản, trả về dưới dạng chuỗi số thập phân.

Name: on_hold
Type: string
Description: Số tiền đang bị giữ bởi các khoản tạm giữ hiệu lực, trả về dưới dạng chuỗi số thập phân.

Name: available_balance
Type: string
Description: Số dư khả dụng: tổng số dư trừ đi các khoản tạm giữ đang hiệu lực.

Name: price_usd
Type: string
Description: Giá USD trên mỗi đơn vị tài sản, trả về dưới dạng chuỗi số thập phân.

Name: value_usd
Type: string
Description: Tổng số dư nhân với giá USD, trả về dưới dạng chuỗi số thập phân.

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

Lấy số dư ví theo ID tài sản

GET

/wallets/{wallet_id}/balance/{asset_id}

Endpoint này trả về tổng số dư của một tài sản trong ví. Để lấy các khoản tạm giữ đang hiệu lực và số dư khả dụng, hãy dùng Lấy số dư ví.

Tham số đường dẫn

Name
wallet_id
Type
string (uuid)
Description
UUID của ví.
Name
asset_id
Type
string (uuid)
Description
UUID của tài sản.

Phản hồi

Name
success
Type
boolean
Description
Cho biết request có thành công hay không.
Name
message
Type
string
Description
Thông điệp mô tả kết quả của thao tác.
Name
code
Type
integer
Description
Mã số cho biết trạng thái kết quả (0 nghĩa là thành công).
Name
data
Type
string
Description
Tổng số dư của tài sản được yêu cầu, trả về dưới dạng chuỗi số thập phân.

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