Ký Web3

Ký thông điệp, dữ liệu có cấu trúc (typed data) và giao dịch trên các mạng lưới EVM và Solana.

Hãy bật Web3 Signing cho ví trước khi sử dụng các endpoint này hoặc SDK. Tính năng này bị tắt theo mặc định; các yêu cầu ký sẽ trả về 403 Forbidden cho đến khi được bật. Xem Bật ký Web3.

Các yêu cầu ký cần được phê duyệt trước khi thực thi. Xem xét chúng tại Approval → DApp Transaction trên dashboard. Xem Phê duyệt ký Web3.

Các yêu cầu trả về một transaction_id. Hãy polling endpoint trạng thái cho đến khi việc ký hoàn tất hoặc thất bại.

Yêu cầu chữ ký

POST
/web3/{wallet_id}/sign

Ký một thông điệp EVM hoặc Solana. Xem Khóa API để biết cách xác thực.

SDK yêu cầu một ví và một RPC provider để ký EVM. SDK tự động polling để lấy chữ ký.

Tham số

  • Name
    wallet_id
    Type
    string
    Description

    ID ví trong đường dẫn URL.

  • Name
    method
    Type
    string
    Description

    eth_sign, eth_signTypedData_v4 hoặc solana_signMessage.

  • Name
    message
    Type
    string
    Description

    Thông điệp cần ký. Dùng chuỗi rỗng đối với typed data.

  • Name
    chain_id
    Type
    number
    Description

    Chain ID của EVM. Dùng 0 cho Solana.

  • Name
    typed_data
    Type
    string
    Description

    Bắt buộc khi ký typed data. Chuỗi JSON chứa domain, types và message.

  • Name
    X-Idempotency-Key
    Type
    string
    Recommended
    recommended
    Description

    Dùng lại cùng một khóa khi thử lại request. SDK hiện chưa ánh xạ options.idempotencyKey sang header này.

Phản hồi

  • Name
    transaction_id
    Type
    string
    Description

    ID yêu cầu để kiểm tra trạng thái ký.

Request

POST
/web3/:wallet_id/sign
import { EtherSigner, Environment } from '@fystack/sdk'
import { JsonRpcProvider } from 'ethers'

const provider = new JsonRpcProvider(process.env.RPC_URL!)
const signer = new EtherSigner(
  {
    apiKey: process.env.API_KEY!,
    apiSecret: process.env.API_SECRET!,
  },
  Environment.Production,
  provider,
)

signer.setWallet('YOUR_WALLET_ID')
const signature = await signer.signMessage('Authorize this session')

Response data

200
{
  "transaction_id": "0de79230-a820-4bd4-b020-883d395faa87"
}

Lấy trạng thái ký

GET
/web3/{wallet_id}/sign/{transaction_id}

Lấy trạng thái và chữ ký của một yêu cầu ký.

  • Name
    transaction_id
    Type
    string
    Description

    ID yêu cầu ký.

  • Name
    status
    Type
    string
    Description

    pending_approval, pending, completed, confirmed, failed hoặc rejected.

  • Name
    signature
    Type
    string
    Description

    Chữ ký, khi đã có. Các signer EVM trong SDK chờ trạng thái confirmed kèm chữ ký.

  • Name
    approvals
    Type
    array
    Description

    Các bản ghi gồm user_id và status: pending, approved hoặc rejected.

  • Name
    created_at
    Type
    string
    Description

    Thời điểm tạo.

  • Name
    updated_at
    Type
    string
    Description

    Thời điểm cập nhật gần nhất.

Nếu polling hết thời gian chờ, hãy kiểm tra yêu cầu hiện có trước khi gửi yêu cầu khác.

Request

GET
/web3/:wallet_id/sign/:transaction_id
import { APIService, Environment } from '@fystack/sdk'

const api = new APIService(
  { apiKey: process.env.API_KEY!, apiSecret: process.env.API_SECRET! },
  Environment.Production,
)

const status = await api.getSignStatus('YOUR_WALLET_ID', 'TRANSACTION_ID')
console.log(status.signature)

Response data

200
{
  "transaction_id": "0de79230-a820-4bd4-b020-883d395faa87",
  "status": "pending_approval",
  "approvals": [],
  "created_at": "2026-10-03T00:00:00Z",
  "updated_at": "2026-10-03T00:00:00Z"
}

Ký giao dịch

POST
/web3/transaction/{wallet_id}/signRaw

Ký không an toàn

Không khuyến nghị ký dữ liệu thô. Một yêu cầu độc hại có thể lừa bạn ký một giao dịch đánh cắp tiền. Chỉ ký những payload bạn đã xác minh.

Gửi một giao dịch để ký và xử lý. Trả về một transaction_id.

  • EVM: from, to, nonce, gasLimit, data, value, chainId, maxFeePerGas, maxPriorityFeePerGas và accessList.
  • Solana: data (giao dịch đã serialize dạng base64), from, meta.tx_method (solana_signTransaction) và chainId ("1399811149").

Hàm signTransaction của EVM SDK trả về mã băm giao dịch. sendTransaction tự điền các trường giao dịch và trả về một transaction response.

Request

POST
/web3/transaction/:wallet_id/signRaw
import { EtherSigner, Environment } from '@fystack/sdk'
import { JsonRpcProvider, parseEther } from 'ethers'

const provider = new JsonRpcProvider(process.env.RPC_URL!)
const signer = new EtherSigner(
  {
    apiKey: process.env.API_KEY!,
    apiSecret: process.env.API_SECRET!,
  },
  Environment.Production,
  provider,
)

signer.setWallet('YOUR_WALLET_ID')
const tx = await signer.sendTransaction({
  to: '0x7c2BbE2e02af09F1cf9aFd4A79EC201DC841675a',
  value: parseEther('0.01'),
})

console.log(tx.hash)

Response data

200
{
  "transaction_id": "0de79230-a820-4bd4-b020-883d395faa87"
}

Lấy trạng thái giao dịch

GET
/web3/transaction/{wallet_id}/{transaction_id}

Trả về transaction_id, status, method, approvals, created_at và updated_at, kèm hash và failed_reason khi có.

Các signer giao dịch trong SDK chờ trạng thái confirmed hoặc completed kèm hash, và dừng lại khi gặp failed hoặc rejected.

Request

GET
/web3/transaction/:wallet_id/:transaction_id
import { APIService, Environment } from '@fystack/sdk'

const api = new APIService(
  { apiKey: process.env.API_KEY!, apiSecret: process.env.API_SECRET! },
  Environment.Production,
)

const status = await api.getTransactionStatus('YOUR_WALLET_ID', 'TRANSACTION_ID')
console.log(status.hash)

Response data

200
{
  "transaction_id": "0de79230-a820-4bd4-b020-883d395faa87",
  "status": "pending",
  "method": "solana_signTransaction",
  "approvals": [],
  "created_at": "2026-10-03T00:00:00Z",
  "updated_at": "2026-10-03T00:00:00Z"
}