`@farcaster/auth-client`

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

开始

安装

安装库及其对等依赖维姆。。。 .

npm install @farcaster/auth-client viem

客户

如果你正在建造一个连接的应用程序,使用一个 应用程序客户端. 应用程序客户端可以连接到中继服务器,在"有法克斯特"链接中生成一个Sign,并验证用户的签名.

如果你正在建造一个钱包应用程序并收到签名请求,使用a 钱包客户端。钱包客户端可以在 Farcaster URL 中解析一个符号,构建一个消息以提交用户,并将所签名的消息提交中继服务器.

应用程序客户端

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

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.

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

返回值

{
  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,以及用户配置信息.

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

返回值

{
    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” 消息、签名和用户配置信息.

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);
  },
});

返回值

{
    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

示例

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

`verifySignInMessage`

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

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

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[...]",
});

返回值

{
    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 客户端

如果你正在建造一个钱包应用程序并收到签名请求,使用a 钱包客户端。。。 .

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

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 无效, 返回错误 .

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",
});

返回值

{
  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 对象和消息作为字符串.

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

返回值

{
  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 消息、用户签名和配置数据 .

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",
});

返回值

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

版本	发布日期	距今
`0.7.1`latest	2026/02/05	9 个月前
`0.0.0-canary-20260205001520`canary	2026/02/05	9 个月前
`0.0.0-canary-20260205000610`	2026/02/05	9 个月前
`0.0.0-canary-20260204234901`	2026/02/05	9 个月前
`0.0.0-canary-20260204233204`	2026/02/05	9 个月前
`0.7.0`	2025/06/06	1.4 年前

@farcaster/auth-client

@farcaster/auth-client

开始

安装

客户

应用程序客户端

参数

醚

中继( 可选的)

版本( 可选)

行动

createChannel

返回值

参数

西维乌里

域名

非ce( 可选)

未在( 可选)

到期 时间( 可选)

请求Id( 可选)

status

返回值

参数

频道脚本

watchStatus

返回值

参数

频道脚本

超时( 可选)

间隔( 可选)

答复( 可选)

verifySignInMessage

返回值

参数

无

域名

消息

签名

Auth 客户端

参数

醚

中继( 可选的)

版本( 可选)

行动

parseSignInURI

返回值

参数

乌里

buildSignInMessage

返回值

参数

地址

无数据

乌里

域名

无

未在( 可选)

到期 时间( 可选)

请求Id( 可选)

authenticate

返回值

参数

消息

签名

无数据

用户名

生物

显示Name

pfpUrl 语录

版本与发布记录

关于 @farcaster/auth-client 的常见问题