@farcaster/auth-client

A framework agnostic client library for Farcaster Auth.

Getting Started

Installation

Install the library and its peer dependency viem.

npm install @farcaster/auth-client viem

Clients

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.

App Client

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

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"

Actions

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.

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

Return Value

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

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

Return Value

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

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

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

({ 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.

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

{
    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[...]"

Auth Client

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

Parameters

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"

Actions

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.

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

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

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

Return Value

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

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

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

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"