# @farcaster/auth-client 中文文档

规范地址：https://npmcn.com/package/%40farcaster/auth-client/

版本：0\.7\.1
npm 元数据更新时间：2026-10-26T13:52:13.059Z
中文译文更新时间：2026-11-14T10:11:38.148Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40farcaster/auth-client
原文对照：https://npmcn.com/package/%40farcaster/auth-client/?lang=original
项目主页：https://github.com/farcasterxyz/auth-monorepo#readme
源码仓库：https://github.com/farcasterxyz/auth-monorepo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：157 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2024-01-11T15:13:51.624Z
- 最新版本发布：2026-02-05T00:23:05.479Z
- 近 30 天下载量：31430（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 5 个）

## 中文简介

Farcaster Auth 的框架不可知客户端库.

## 安装

```sh
npm install @farcaster/auth-client
```

也可以使用：`pnpm add @farcaster/auth-client`、`yarn add @farcaster/auth-client`、`bun add @farcaster/auth-client`

## README

# `@farcaster/auth-client`

Farcaster Auth 的框架不可知客户端库.

## 开始

### 安装

安装库及其对等依赖 [维姆](https://viem.sh/)。 。 。 .

```sh
npm install @farcaster/auth-client viem
```

## 客户

如果你正在建造一个 [连接的应用程序](https://docs.farcaster.xyz/learn/what-is-farcaster/apps#connected-apps),使用一个 [_应用程序客户端_](https://npmcn.com/package/%40farcaster/auth-client/#readme-app-client). 应用程序客户端可以连接到中继服务器,在"有法克斯特"链接中生成一个Sign,并验证用户的签名.

如果你正在建造一个 [钱包应用程序](https://docs.farcaster.xyz/learn/what-is-farcaster/apps#wallet-apps) 并收到签名请求,使用a [_钱包客户端_](https://npmcn.com/package/%40farcaster/auth-client/#readme-wallet-client)。钱包客户端可以在 Farcaster URL 中解析一个符号,构建一个消息以提交用户,并将所签名的消息提交中继服务器.

## 应用程序客户端

您可以使用应用客户端创建Farcaster Auth中继通道,生成URL以请求用户的Farcaster钱包应用签名,并验证返回的签名.

```ts
import { createAppClient, viemConnector } from "@farcaster/auth-client";

const appClient = createAppClient({
  relay: "https://relay.farcaster.xyz",
  ethereum: viemConnector(),
});
```

#### 参数

##### 醚

一个Ethereum连接器,用于查询Farcaster合同并验证智能合同钱包签名. `@farcaster/auth-client` 目前只提供 `viemConnector` 连接器类型 .

要使用自定义的 RPC, 请将 RPC URL 传递给viem 连接器 .

类型 : `Ethereum`

示例 `viemConnector("http://mainnet.optimism.io")`

##### 中继( 可选的)

中继服务器 URL. 公众中继器默认值 `https://relay.farcaster.xyz`。 。 。 .

类型 : `string`

示例 `"https://relay.farcaster.xyz"`

##### 版本( 可选)

法克斯特·奥特版本. 默认为 `"v1"`

类型 : `string`

示例 `"v1"`

### 行动

#### `createChannel`

创建 Farcaster Auth 中继通道 .

返回用于识别频道的密令,并返回作为链接或QR代码向最终用户显示的URI.

```ts
const channel = await appClient.createChannel({
  siweUri: "https://example.com/login",
  domain: "example.com",
});
```

##### 返回值

```ts
{
  response: Response;
  data: {
    channelToken: string;
    url: string;
  }
  isError: boolean;
  error: Error;
}
```

##### 参数

##### 西维乌里

登录应用程序的 URL .

类型 : `string`

示例 `"https://example.com/login"`

##### 域名

您的应用程序域 。 值应当与请求SIWE签名的域相匹配.

类型 : `string`

示例 `"example.com"`

##### 非ce( 可选)

一个自定义的非ce。 必须是至少8个字母数字字符 .

类型 : `string`

示例 `"ESsxs6MaFio7OvqWb"`

##### 未在( 可选)

SIWE 签名生效的开始时间 。 ISO 8601 日期时间.

类型 : `string`

示例 `"2023-12-20T23:21:24.917Z"`

##### 到期 时间( 可选)

SIWE签名失效的过期时间. ISO 8601 日期时间.

类型 : `string`

示例 `"2023-12-20T23:21:24.917Z"`

##### 请求Id( 可选)

在请求中,一个系统特定的ID您的应用程序可以用来指代标志.

类型 : `string`

示例 `"8d0494d9-e0cf-402b-ab0a-394ac7fe07a0"`

#### `status`

获取 Farcaster Auth 请求的当前状态 .

返回请求的当前状态, 任意 `'pending'` 如果用户的 Farcaster 钱包应用程序尚未发回签名,或 `'completed'` 一旦钱包应用程序返回了响应.

单位 `'completed'` 状态,响应包括生成的带有Farcaster消息的Sign,来自用户监护地址的签名,用户经过验证的fid,以及用户配置信息.

```ts
const status = await appClient.status({
  channelToken: "210f1718-427e-46a4-99e3-2207f21f83ec",
});
```

##### 返回值

```ts
{
    response: Response
    data: {
        state: 'pending' | 'completed'
        nonce: string
        message?: string
        signature?: Hex
        fid?: number
        username?: string
        bio?: string
        displayName?: string
        pfpUrl?: string
        custody?: Hex
        verifications?: Hex[]
    }
    isError: boolean
    error: Error
}
```

##### 参数

###### 频道脚本

Farcaster Auth 中继频道符号, 由 `createChannel`。 。 。 .

类型 : `string`

示例 `"210f1718-427e-46a4-99e3-2207f21f83ec"`

#### `watchStatus`

对Farcaster Auth请求的当前状态进行投票.

当状态改变到 `'complete'` 此动作以最终的频道值解决, 包括“ Sign In With Farcaster” 消息、签名和用户配置信息.

```ts
const status = await appClient.watchStatus({
  channelToken: "210f1718-427e-46a4-99e3-2207f21f83ec",
  timeout: 60_000,
  interval: 1_000,
  onResponse: ({ response, data }) => {
    console.log("Response code:", response.status);
    console.log("Status data:", data);
  },
});
```

##### 返回值

```ts
{
    response: Response
    data: {
        state: 'completed'
        nonce: string
        message?: string
        signature?: Hex
        fid?: number
        username?: string
        bio?: string
        displayName?: string
        pfpUrl?: string
        custody?: Hex
        verifications?: Hex[]
    }
    isError: boolean
    error: Error
}
```

##### 参数

###### 频道脚本

Farcaster Auth 中继频道符号, 由 `createChannel`。 。 。 .

类型 : `string`

示例 `"210f1718-427e-46a4-99e3-2207f21f83ec"`

###### 超时( 可选)

投票暂停,以毫秒计。 如果认证请求在超时前没有完成, `watchStatus` 返回错误.

类型 : `number`

示例 `300_000`

###### 间隔( 可选)

投票间隔,以毫秒计. 客户端将在此频率检查更新 .

类型 : `number`

示例 `1_000`

###### 答复( 可选)

每次客户端民调时都会引用回调功能进行更新并收到中继服务器的答复. 接收最新的返回值 `status` 请求.

类型 : `({ response, data }) => void`

示例

```ts
({ response, data }) => {
  console.log("Response code:", response.status);
  console.log("Status data:", data);
};
```

#### `verifySignInMessage`

校验带有 Farcaster 信件的标志 。 您的应用程序应该调用此功能, 并检查它在读取用户的 Farcaster 钱包在 Auth 中继通道上提供的消息和签名后是否成功 .

返回使用 Farcaster 信件的解析符号、 用户的fid 以及校验是否成功 .

```ts
const { data, success, fid } = await appClient.verifySignInMessage({
  nonce: "abcd1234",
  domain: "example.com",
  message: "example.com wants you to sign in with your Ethereum account: [...]",
  signature: "0x9335c3055d47780411a3fdabad293c68c84ea350a11794cdc811fd51b[...]",
});
```

##### 返回值

```ts
{
    data: SiweMessage,
    success: boolean,
    fid: number
    isError: boolean
    error: Error
}
```

##### 参数

##### 无

您的应用程序生成的非ce 。 必须与 SIWE 消息中的非ce 匹配 .

类型 : `string`

示例 `"ESsxs6MaFio7OvqWb"`

##### 域名

您的应用程序域 。 值必须匹配SIWE消息中的域.

类型 : `string`

示例 `"example.com"`

###### 消息

写着法克斯特的消息 这可能是字符串或解析 `SiweMessage`。您的应用程序应当在请求完成后从 Auth 中继通道读取此值 .

类型 : `string | SiweMessage`

示例 `"example.com wants you to sign in with your Ethereum account: [...]"`

###### 签名

用户的Farcaster钱包提供的签名. 您的应用程序应该在请求完成后从 Auth 中继频道读取此内容 .

类型 : `0x${string}`

示例 `"0x9335c3055d4778013fdabad293c68c84ea350a11794cdc121c71fd51b[...]"`

## Auth 客户端

如果你正在建造一个 [钱包应用程序](https://docs.farcaster.xyz/learn/what-is-farcaster/apps#wallet-apps) 并收到签名请求,使用a _钱包客户端_。 。 。 .

您可以使用一个钱包客户端来解析一个带有 Farcaster 请求 URL 的信号, 在 Farcaster 信件中构建一个信号以提交用户, 并将签名的消息提交 Farcaster Auth 中继通道 .

```ts
import { createWalletClient, viemConnector } from "@farcaster/auth-client";

const walletClient = createWalletClient({
  relay: "https://relay.farcaster.xyz",
  ethereum: viemConnector(),
});
```

### 参数

##### 醚

一个Ethereum连接器,用于查询Farcaster合同并验证智能合同钱包签名. `@farcaster/auth-client` 目前只提供 `viem` 连接器类型 .

要使用自定义的 RPC,将一个 RPC URl 传递给viem 连接器.

类型 : `Ethereum`

示例 `viem("http://mainnet.optimism.io")`

##### 中继( 可选的)

中继服务器 URL. 公众中继器默认值 `https://relay.farcaster.xyz`。 。 。 .

类型 : `string`

示例 `"https://relay.farcaster.xyz"`

##### 版本( 可选)

法克斯特·奥特版本. 默认为 `"v1"`

类型 : `string`

示例 `"v1"`

### 行动

#### `parseSignInURI`

用 Farcaster URI 解析由连接的应用程序用户提供的标志 .

返回解析参数。 您的应用程序应该用这些来构建一个带有Farcaster消息的标志 .

如果 URI 无效, 返回错误 .

```ts
const params = walletClient.parseSignInURI({
  uri: "farcaster://connect?channelToken=76be6229-bdf7-4ad2-930a-540fb2de1e08&nonce=ESsxs6MaFio7OvqWb&siweUri=https%3A%2F%2Fexample.com%2Flogin&domain=example.com",
});
```

##### 返回值

```ts
{
  channelToken: string
  params: {
    domain: string
    uri: string
    nonce: string
    notBefore?: string
    expirationTime?: string
    requestId?: string
  }
  isError: boolean
  error: Error
}
```

##### 参数

##### 乌里

在 Farcaster 协议处理器 URI 中签名 .

类型 : `string`

示例 `"farcaster://connect?channelToken=76be6229-bdf7-4ad2-930a-540fb2de1e08&nonce=ESsxs6MaFio7OvqWb&siweUri=https%3A%2F%2Fexample.com%2Flogin&domain=example.com"`

#### `buildSignInMessage`

在 Farcaster 信件中构建一个标志, 以提交最终用户 .

在任何提供的参数中添加所需的带有 Farcaster 信件属性的签名 。 您应该从提供的协议 URI 中解析其中的大部分参数 。 您的钱包应用必须提供用户的监护地址并查找 .

回返a `SiweMessage` 对象和消息作为字符串.

```ts
const { siweMessage, message } = walletClient.buildSignInMessage({
  address: "0x63C378DDC446DFf1d831B9B96F7d338FE6bd4231",
  fid: 1,
  uri: "https://example.com/login",
  domain: "example.com",
  nonce: "ESsxs6MaFio7OvqWb",
});
```

##### 返回值

```ts
{
  siweMessage: SiweMessage;
  message: string;
  isError: boolean;
  error: Error;
}
```

##### 参数

##### 地址

钱包用户的保管地址. 此地址必须在生成的 Sign In With Farcaster 消息上签名 。 您的钱包应用应该提供认证用户的保管地址 .

类型 : `0x${string}`

示例 `"0x63C378DDC446DFf1d831B9B96F7d338FE6bd4231"`

##### 无数据

钱包用户fid. 您的钱包应用程序应该提供认证用户的fid .

类型 : `number`

示例 `1`

##### 乌里

依赖连接的应用程序的登录 URL。 从提供的 Sign In With Farcaster URI 中解析此内容 .

类型 : `string`

示例 `"https://example.com/login"`

##### 域名

依赖连接的应用程序域 。 解析从提供的标志 在与Farcaster URI.

类型 : `string`

示例 `"example.com"`

##### 无

随机非ce 将包含在 Sign In With Farcaster 信件中 。 必须是至少8个字母数字字符 。 解析从提供的标志 在与Farcaster URI.

类型 : `string`

示例 `"ESsxs6MaFio7OvqWb"`

##### 未在( 可选)

SIWE 签名生效的开始时间 。 ISO 8601 日期时间. 解析从提供的标志 在与Farcaster URI.

类型 : `string`

示例 `"2023-12-20T23:21:24.917Z"`

##### 到期 时间( 可选)

SIWE签名失效的过期时间. ISO 8601 日期时间. 解析从提供的标志 在与Farcaster URI.

类型 : `string`

示例 `"2023-12-20T23:21:24.917Z"`

##### 请求Id( 可选)

依赖应用程序提供的系统特定ID. 解析从提供的标志 在与Farcaster URI.

类型 : `string`

示例 `"8d0494d9-e0cf-402b-ab0a-394ac7fe07a0"`

#### `authenticate`

向 Auth 中继服务器提交 Sign In With Farcaster 消息、用户签名和配置数据 .

```ts
const params = walletClient.authenticate({
  message: "example.com wants you to sign in with your Ethereum account: [...]",
  signature: "0x9335c3055d47780411a3fdabad293c68c84ea350a11794cdc811fd51b[...]",
  fid: 1,
  username: "alice",
  bio: "I'm a little teapot who didn't fill out my bio",
  displayName: "Alice Teapot",
  pfpUrl: "https://images.example.com/profile.png",
});
```

##### 返回值

```ts
{
  response: Response
  data: {
      state: 'completed'
      nonce: string
      message?: string
      signature?: `0x${string}`
      fid?: number
      username?: string
      bio?: string
      displayName?: string
      pfpUrl?: string
  }
  isError: boolean
  error: Error
}
```

##### 参数

###### 消息

由您的钱包应用程序制作并由用户签名的 Farcaster 信件签名 .

类型 : `string`

示例 `"example.com wants you to sign in with your Ethereum account: [...]"`

###### 签名

钱包用户账户创建的 SIWE 签名 .

类型 : `0x${string}`

示例 `"0x9335c3055d4778013fdabad293c68c84ea350a11794cdc121c71fd51b[...]"`

##### 无数据

钱包用户fid.

类型 : `number`

示例 `1`

##### 用户名

钱包用户法克斯特用户名.

类型 : `string`

示例 `"alice"`

##### 生物

钱包用户生物.

类型 : `string`

示例 `"I'm a little teapot who didn't fill out my bio"`

##### 显示Name

钱包用户的显示名 .

类型 : `string`

示例 `"Alice Teapot"`

##### pfpUrl 语录

钱包用户的配置图片 URL.

类型 : `string`

示例 `"https://images.example.com/profile.png"`

## 常见问题

### @farcaster/auth-client 是什么？

Farcaster Auth 的框架不可知客户端库\.

### 如何安装 @farcaster/auth-client？

在项目目录运行 npm install @farcaster/auth-client，或使用 pnpm add / yarn add / bun add。

### @farcaster/auth-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @farcaster/auth-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @farcaster/auth-client 可以商用吗？

@farcaster/auth-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @farcaster/auth-client 的下载量有多少？

根据 npm 官方下载统计，@farcaster/auth-client 在 2026/10/15 – 2026/11/13 这 30 天内被下载 31,430 次，日均约 1,048 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @farcaster/auth-client 还在维护吗？

最新版本 0\.7\.1 发布于 2026/02/05（9 个月前）；至今共发布 19 个版本，其中过去 12 个月发布了 5 个；首次发布于 2024/01/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。