A framework agnostic client library for Farcaster Auth.
npm install @farcaster/auth-client@farcaster/auth-clientA framework agnostic client library for Farcaster Auth.
Install the library and its peer dependency viem.
``sh`
npm install @farcaster/auth-client viem
If 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.
`ts
import { createAppClient, viemConnector } from "@farcaster/auth-client";
const appClient = createAppClient({
relay: "https://relay.farcaster.xyz",
ethereum: viemConnector(),
});
`
#### Parameters
##### ethereum
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 (optional)
Relay server URL. Defaults to the public relay at https://relay.farcaster.xyz.
Type: string
Example: "https://relay.farcaster.xyz"
##### version (optional)
Farcaster Auth version. Defaults to "v1"
Type: string
Example: "v1"
#### createChannel
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.
`ts`
const channel = await appClient.createChannel({
siweUri: "https://example.com/login",
domain: "example.com",
});
##### Return Value
`ts`
{
response: Response;
data: {
channelToken: string;
url: string;
}
isError: boolean;
error: Error;
}
##### Parameters
##### siweUri
Login URL for your application.
Type: string
Example: "https://example.com/login"
##### domain
Domain of your application. Value should match the domain requesting the SIWE signature.
Type: string
Example: "example.com"
##### nonce (optional)
A custom nonce. Must be at least 8 alphanumeric characters.
Type: string
Example: "ESsxs6MaFio7OvqWb"
##### notBefore (optional)
Start time at which the SIWE signature becomes valid. ISO 8601 datetime.
Type: string
Example: "2023-12-20T23:21:24.917Z"
##### expirationTime (optional)
Expiration time at which the SIWE signature is no longer valid. ISO 8601 datetime.
Type: string
Example: "2023-12-20T23:21:24.917Z"
##### requestId (optional)
A system specific ID your app can use to refer to the sign in request.
Type: string
Example: "8d0494d9-e0cf-402b-ab0a-394ac7fe07a0"
#### status
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.
`ts`
const status = await appClient.status({
channelToken: "210f1718-427e-46a4-99e3-2207f21f83ec",
});
##### Return Value
`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
}
##### Parameters
###### channelToken
Farcaster Auth relay channel token, returned by createChannel.
Type: string
Example: "210f1718-427e-46a4-99e3-2207f21f83ec"
#### watchStatus
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.
`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);
},
});
##### Return Value
`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
}
##### Parameters
###### channelToken
Farcaster Auth relay channel token, returned by createChannel.
Type: string
Example: "210f1718-427e-46a4-99e3-2207f21f83ec"
###### timeout (optional)
Polling timeout, in milliseconds. If the auth request is not completed before the timeout, watchStatus returns an error.
Type: number
Example: 300_000
###### interval (optional)
Polling interval, in milliseconds. The client will check for updates at this frequency.
Type: number
Example: 1_000
###### onResponse (optional)
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:
`ts`
({ response, data }) => {
console.log("Response code:", response.status);
console.log("Status data:", data);
};
#### verifySignInMessage
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.
`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[...]",
});
##### Return Value
`ts`
{
data: SiweMessage,
success: boolean,
fid: number
isError: boolean
error: Error
}
##### Parameters
##### nonce
The nonce generated by your application. Must match the nonce in the SIWE message.
Type: string
Example: "ESsxs6MaFio7OvqWb"
##### domain
Domain of your application. Value must match the domain in the SIWE message.
Type: string
Example: "example.com"
###### message
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
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.
`ts
import { createWalletClient, viemConnector } from "@farcaster/auth-client";
const walletClient = createWalletClient({
relay: "https://relay.farcaster.xyz",
ethereum: viemConnector(),
});
`
##### ethereum
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 (optional)
Relay server URL. Defaults to the public relay at https://relay.farcaster.xyz.
Type: string
Example: "https://relay.farcaster.xyz"
##### version (optional)
Farcaster Auth version. Defaults to "v1"
Type: string
Example: "v1"
#### parseSignInURI
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.
`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",
});
##### Return Value
`ts`
{
channelToken: string
params: {
domain: string
uri: string
nonce: string
notBefore?: string
expirationTime?: string
requestId?: string
}
isError: boolean
error: Error
}
##### Parameters
##### uri
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"
#### buildSignInMessage
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.
`ts`
const { siweMessage, message } = walletClient.buildSignInMessage({
address: "0x63C378DDC446DFf1d831B9B96F7d338FE6bd4231",
fid: 1,
uri: "https://example.com/login",
domain: "example.com",
nonce: "ESsxs6MaFio7OvqWb",
});
##### Return Value
`ts`
{
siweMessage: SiweMessage;
message: string;
isError: boolean;
error: Error;
}
##### Parameters
##### address
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"
##### fid
Wallet user's fid. Your wallet app should provide the fid of the authenticated user.
Type: number
Example: 1
##### uri
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
Domain of the relying connected app. Parse this from the provided Sign In With Farcaster URI.
Type: string
Example: "example.com"
##### nonce
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"
##### notBefore (optional)
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"
##### expirationTime (optional)
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"
##### requestId (optional)
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"
#### authenticate
Submit a Sign In With Farcaster message, user signature, and profile data to the Auth relay server.
`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",
});
##### Return Value
`ts0x${string}
{
response: Response
data: {
state: 'completed'
nonce: string
message?: string
signature?:
fid?: number
username?: string
bio?: string
displayName?: string
pfpUrl?: string
}
isError: boolean
error: Error
}
##### Parameters
###### message
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: [...]"
###### signature
SIWE signature created by the wallet user's account.
Type: 0x${string}
Example: "0x9335c3055d4778013fdabad293c68c84ea350a11794cdc121c71fd51b[...]"
##### fid
Wallet user's fid.
Type: number
Example: 1
##### username
Wallet user's Farcaster username.
Type: string
Example: "alice"
##### bio
Wallet user's bio.
Type: string
Example: "I'm a little teapot who didn't fill out my bio"
##### displayName
Wallet user's display name.
Type: string
Example: "Alice Teapot"
##### pfpUrl
Wallet user's profile photo URL.
Type: string
Example: "https://images.example.com/profile.png"`