---
title: "Web3 签名"
description: "使用 Fystack 钱包签署消息、类型化数据和交易。"
url: https://docs.fystack.io/zh/web3-sign
last_updated: 2026-11-13
---

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

# Web3 签名

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

**在使用这些 endpoint 或 SDK 之前，请先为钱包启用 Web3 签名。** 该功能默认关闭；启用之前，签名请求会返回 **403 Forbidden**。请参阅[启用 Web3 签名](https://docs.fystack.io/product/web3-sign.md#enable-web3-signing)。

签名请求在执行前需要审批。请在控制台的 **Approval → DApp Transaction** 中进行审核。请参阅 [Web3 签名审批](https://docs.fystack.io/product/web3-sign.md#review-pending-requests)。

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

---

## 请求签名

**Endpoint:** `POST /web3/:wallet_id/sign`

签署 EVM 或 Solana 消息。身份认证请参阅 [API key](https://docs.fystack.io/api-keys.md)。

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

### 参数

- `wallet_id` (string): URL 路径中的钱包 ID。
- `method` (string): `eth_sign`、`eth_signTypedData_v4` 或 `solana_signMessage`。
- `message` (string): 要签署的消息。对于类型化数据，请使用空字符串。
- `chain_id` (number): EVM 链 ID。Solana 请使用 `0`。
- `typed_data` (string): 签署类型化数据时必填。包含 `domain`、`types` 和 `message` 的 JSON 字符串。
- `X-Idempotency-Key` (string, recommended): 重试请求时请复用同一个 key。SDK 目前不会将 `options.idempotencyKey` 映射到此请求头。

### 响应

- `transaction_id` (string): 用于查询签名状态的请求 ID。

**请求** `POST /web3/:wallet_id/sign`

```typescript
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')
```

```typescript
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 network = await provider.getNetwork()

const signature = await signer.signTypedData(
  {
    name: 'Example App',
    version: '1',
    chainId: network.chainId,
  },
  {
    Session: [
      { name: 'account', type: 'address' },
      { name: 'nonce', type: 'string' },
    ],
  },
  {
    account: await signer.getAddress(),
    nonce: crypto.randomUUID(),
  },
)

console.log('Typed data signature:', signature)
```

```typescript
import { SolanaSigner, Environment } from '@fystack/sdk'

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

solanaSigner.setWallet('YOUR_WALLET_ID')

const signature = await solanaSigner.signMessage('Authorize this session')

console.log('Signature:', signature)
```

```json
{
  "method": "eth_sign",
  "message": "Authorize this session",
  "chain_id": 11155111
}
```

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

---

## 获取签名状态

**Endpoint:** `GET /web3/:wallet_id/sign/:transaction_id`

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

- `transaction_id` (string): 签名请求 ID。
- `status` (string): `pending_approval`、`pending`、`completed`、`confirmed`、`failed` 或 `rejected`。
- `signature` (string): 签名（如有）。EVM SDK 签名器会等待带有签名的 `confirmed` 状态。
- `approvals` (array): 包含 `user_id` 和 `status` 的记录：`pending`、`approved` 或 `rejected`。
- `created_at` (string): 创建时间戳。
- `updated_at` (string): 最后更新时间戳。

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

**请求** `GET /web3/:wallet_id/sign/:transaction_id`

```typescript
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)
```

```json
{
  "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"
}
```

---

## 签署交易

**Endpoint:** `POST /web3/transaction/:wallet_id/signRaw`

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

提交交易以进行签名和处理。返回一个 `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`

```typescript
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)
```

```typescript
import { SolanaSigner, Environment } from '@fystack/sdk'

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

solanaSigner.setWallet('YOUR_WALLET_ID')

// Base64 serialized transaction from @solana/web3.js.
const signature = await solanaSigner.signTransaction(serializedTransaction)
console.log(signature)
```

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

---

## 获取交易状态

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

```typescript
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)
```

```json
{
  "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"
}
```