A framework agnostic client library for Farcaster Auth.
Install the library and its peer dependency viem.
npm install @farcaster/auth-client viemIf you're building a connected app, use an app client. An app client can connect to the relay server, generate a Sign in With Farcaster link, and verify the user's signature.
If you're building a wallet app and receiving signature requests, use a wallet client. A wallet client can parse a Sign in With Farcaster URL, build a message to present to the user, and submit the signed message to the relay server.
You can use an app client to create a Farcaster Auth relay channel, generate a URL to request a signature from the user's Farcaster wallet app, and verify the returned signature.
import { createAppClient, viemConnector } from "@farcaster/auth-client";
import { JsonRpcProvider } from "ethers";
const appClient = createAppClient({
relay: "https://relay.farcaster.xyz",
ethereum: viemConnector(),
});An Ethereum connector, used to query the Farcaster contracts and verify smart contract wallet signatures. @farcaster/auth-client currently provides only the viemConnector connector type.
To use a custom RPC, pass an RPC URL to the viem connector.
Type: Ethereum
Example: viemConnector("http://mainnet.optimism.io")
Relay server URL. Defaults to the public relay at https://relay.farcaster.xyz.
Type: string
Example: "https://relay.farcaster.xyz"
Farcaster Auth version. Defaults to "v1"
Type: string
Example: "v1"
Create a Farcaster Auth relay channel.
Returns a secret token identifying the channel, and a URI to display to the end user as a link or QR code.
const channel = await appClient.createChannel({
siweUri: "https://example.com/login",
domain: "example.com",
});{
response: Response;
data: {
channelToken: string;
url: string;
}
isError: boolean;
error: Error;
}Login URL for your application.
Type: string
Example: "https://example.com/login"
Domain of your application. Value should match the domain requesting the SIWE signature.
Type: string
Example: "example.com"
A custom nonce. Must be at least 8 alphanumeric characters.
Type: string
Example: "ESsxs6MaFio7OvqWb"
Start time at which the SIWE signature becomes valid. ISO 8601 datetime.
Type: string
Example: "2023-12-20T23:21:24.917Z"
Expiration time at which the SIWE signature is no longer valid. ISO 8601 datetime.
Type: string
Example: "2023-12-20T23:21:24.917Z"
A system specific ID your app can use to refer to the sign in request.
Type: string
Example: "8d0494d9-e0cf-402b-ab0a-394ac7fe07a0"
Get current status of a Farcaster Auth request.
Returns the current state of the request, either 'pending' if the user's Farcaster wallet app has not yet sent back a signature, or 'completed' once the wallet app has returned a response.
In 'completed' state, the response includes the generated Sign in With Farcaster message, a signature from the user's custody address, the user's verified fid, and user profile information.
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 relay channel token, returned by createChannel.
Type: string
Example: "210f1718-427e-46a4-99e3-2207f21f83ec"
Poll for the current status of a Farcaster Auth request.
When the status changes to 'complete' this action resolves with the final channel value, including the Sign In With Farcaster message, signature, and user profile information.
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 relay channel token, returned by createChannel.
Type: string
Example: "210f1718-427e-46a4-99e3-2207f21f83ec"
Polling timeout, in milliseconds. If the auth request is not completed before the timeout, watchStatus returns an error.
Type: number
Example: 300_000
Polling interval, in milliseconds. The client will check for updates at this frequency.
Type: number
Example: 1_000
Callback function invoked each time the client polls for an update and receives a response from the relay server. Receives the return value of the latest status request.
Type: ({ response, data }) => void
Example:
({ response, data }) => {
console.log("Response code:", response.status);
console.log("Status data:", data);
};Verify a Sign In With Farcaster message. Your app should call this function and check that it succeeds after reading the message and signature provided by the user's Farcaster wallet over the Auth relay channel.
Returns the parsed Sign in With Farcaster message, the user's fid, and whether the verification succeeded.
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
}The nonce generated by your application. Must match the nonce in the SIWE message.
Type: string
Example: "ESsxs6MaFio7OvqWb"
Domain of your application. Value must match the domain in the SIWE message.
Type: string
Example: "example.com"
The Sign in With Farcaster message to verify. This may be either a string or a parsed SiweMessage. Your app should read this value from the Auth relay channel once the request is completed.
Type: string | SiweMessage
Example: "example.com wants you to sign in with your Ethereum account: [...]"
Signature provided by the user's Farcaster wallet. Your app should read this from the Auth relay channel once the request is completed.
Type: 0x${string}
Example: "0x9335c3055d4778013fdabad293c68c84ea350a11794cdc121c71fd51b[...]"
If you're building a wallet app and receiving signature requests, use a wallet client.
You can use an wallet client to parse an incoming Sign In With Farcaster request URL, build a Sign In With Farcaster message to present to the user, and submit the signed message to a Farcaster Auth relay channel.
import { createWalletClient, viemConnector } from "@farcaster/auth-client";
const walletClient = createWalletClient({
relay: "https://relay.farcaster.xyz",
ethereum: viemConnector(),
});An Ethereum connector, used to query the Farcaster contracts and verify smart contract wallet signatures. @farcaster/auth-client currently provides only the viem connector type.
To use a custom RPC, pass an RPC URl to the viem connector.
Type: Ethereum
Example: viem("http://mainnet.optimism.io")
Relay server URL. Defaults to the public relay at https://relay.farcaster.xyz.
Type: string
Example: "https://relay.farcaster.xyz"
Farcaster Auth version. Defaults to "v1"
Type: string
Example: "v1"
Parse the Sign In With Farcaster URI provided by a connected app user.
Returns the parsed parameters. Your app should use these to construct a Sign In With Farcaster message.
Returns an error if URI is invalid.
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
}Sign In With Farcaster protocol handler URI.
Type: string
Example: "farcaster://connect?channelToken=76be6229-bdf7-4ad2-930a-540fb2de1e08&nonce=ESsxs6MaFio7OvqWb&siweUri=https%3A%2F%2Fexample.com%2Flogin&domain=example.com"
Build a Sign In With Farcaster message to present to the end user.
Adds required Sign In With Farcaster message attributes to any provided parameters. You should parse most of these parameters from the provided protocol URI. Your wallet app must provide the user's custody address and fid.
Returns a SiweMessage object and the message as a string.
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;
}Wallet user's custody address. This address must sign the generated Sign In With Farcaster message. Your wallet app should provide the custody address of the authenticated user.
Type: 0x${string}
Example: "0x63C378DDC446DFf1d831B9B96F7d338FE6bd4231"
Wallet user's fid. Your wallet app should provide the fid of the authenticated user.
Type: number
Example: 1
Login URL of the relying connected app. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "https://example.com/login"
Domain of the relying connected app. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "example.com"
Random nonce to include in the Sign In With Farcaster message. Must be at least 8 alphanumeric characters. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "ESsxs6MaFio7OvqWb"
Start time at which the SIWE signature becomes valid. ISO 8601 datetime. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "2023-12-20T23:21:24.917Z"
Expiration time at which the SIWE signature is no longer valid. ISO 8601 datetime. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "2023-12-20T23:21:24.917Z"
A system specific ID provided by the relying app. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "8d0494d9-e0cf-402b-ab0a-394ac7fe07a0"
Submit a Sign In With Farcaster message, user signature, and profile data to the Auth relay server.
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
}The Sign in With Farcaster message produced by your wallet app and signed by the user.
Type: string
Example: "example.com wants you to sign in with your Ethereum account: [...]"
SIWE signature created by the wallet user's account.
Type: 0x${string}
Example: "0x9335c3055d4778013fdabad293c68c84ea350a11794cdc121c71fd51b[...]"
Wallet user's fid.
Type: number
Example: 1
Wallet user's Farcaster username.
Type: string
Example: "alice"
Wallet user's bio.
Type: string
Example: "I'm a little teapot who didn't fill out my bio"
Wallet user's display name.
Type: string
Example: "Alice Teapot"
Wallet user's profile photo URL.
Type: string
Example: "https://images.example.com/profile.png"