Web3 签名

在 EVM 和 Solana 网络上签署消息、类型化数据和交易。

在使用这些 endpoint 或 SDK 之前，请先为钱包启用 Web3 签名。 该功能默认关闭；启用之前，签名请求会返回 403 Forbidden。请参阅启用 Web3 签名。

签名请求在执行前需要审批。请在控制台的 Approval → DApp Transaction 中进行审核。请参阅 Web3 签名审批。

请求会返回一个 transaction_id。请轮询状态 endpoint，直到签名完成或失败。

请求签名

POST
/web3/{wallet_id}/sign

签署 EVM 或 Solana 消息。身份认证请参阅 API key。

进行 EVM 签名时，SDK 需要一个钱包和一个 RPC provider。SDK 会自动轮询获取签名。

参数

  • Name
    wallet_id
    Type
    string
    Description

    URL 路径中的钱包 ID。

  • Name
    method
    Type
    string
    Description

    eth_sign、eth_signTypedData_v4 或 solana_signMessage。

  • Name
    message
    Type
    string
    Description

    要签署的消息。对于类型化数据，请使用空字符串。

  • Name
    chain_id
    Type
    number
    Description

    EVM 链 ID。Solana 请使用 0。

  • Name
    typed_data
    Type
    string
    Description

    签署类型化数据时必填。包含 domain、types 和 message 的 JSON 字符串。

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

    重试请求时请复用同一个 key。SDK 目前不会将 options.idempotencyKey 映射到此请求头。

响应

  • Name
    transaction_id
    Type
    string
    Description

    用于查询签名状态的请求 ID。

请求

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

获取签名状态

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

获取签名请求的状态和签名。

  • Name
    transaction_id
    Type
    string
    Description

    签名请求 ID。

  • Name
    status
    Type
    string
    Description

    pending_approval、pending、completed、confirmed、failed 或 rejected。

  • Name
    signature
    Type
    string
    Description

    签名（如有）。EVM SDK 签名器会等待带有签名的 confirmed 状态。

  • Name
    approvals
    Type
    array
    Description

    包含 user_id 和 status 的记录：pending、approved 或 rejected。

  • Name
    created_at
    Type
    string
    Description

    创建时间戳。

  • Name
    updated_at
    Type
    string
    Description

    最后更新时间戳。

如果轮询超时，请先检查现有请求，再提交新的请求。

请求

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

签署交易

POST
/web3/transaction/{wallet_id}/signRaw

不安全的签名

不建议使用原始签名。恶意请求可能诱骗你签署窃取资金的交易。只签署你已验证过的载荷。

提交交易以进行签名和处理。返回一个 transaction_id。

  • EVM：from、to、nonce、gasLimit、data、value、chainId、maxFeePerGas、maxPriorityFeePerGas 和 accessList。
  • Solana：data（base64 序列化的交易）、from、meta.tx_method（solana_signTransaction）以及 chainId（"1399811149"）。

EVM SDK 的 signTransaction 返回交易哈希。sendTransaction 会填充交易字段并返回交易响应。

请求

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

获取交易状态

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

返回 transaction_id、status、method、approvals、created_at 和 updated_at，如有还会返回 hash 和 failed_reason。

SDK 交易签名器会等待带有 hash 的 confirmed 或 completed 状态，并在 failed 或 rejected 时停止。

请求

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