​
Overview

This document explains how to authenticate with Wield to access protected endpoints such as submitting messages. There are two authentication methods:

  1. Farcaster L1 Authentication (using FID)
  2. Signature-based Authentication (using wallet signature)

Use BASE_URL="https://build.wield.xyz" for Farcaster L1 and Wield L2.

​
Authentication Flow

​
1. Get Signin Message

First, request a signin message that needs to be signed:

const getSigninMessage = async (address) => {
  const response = await fetch(
    `${BASE_URL}/auth/v1/get-account-signin-message?address=${address}&chainId=1`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        "API-KEY": "your-api-key",
      },
    }
  );

  const data = await response.json();
  return data.signature; // This is the message to sign
};

​
2. Authentication Methods

​
Method A: Signature Authentication

This method provides access to all endpoints but messages stay on Wield L2:

  • No FID required
  • Works with any Ethereum wallet
  • Messages won’t be broadcasted to Farcaster L1
const authenticateWithSignature = async (signature, address) => {
  const response = await fetch(`${BASE_URL}/auth/v2/authenticate`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "API-KEY": "your-api-key",
    },
    body: JSON.stringify({
      signature,
      address,
      chainId: 1,
      type: "SIGNATURE", // Specify signature authentication
    }),
  });

  const data = await response.json();
  return data.accessToken;
};

​
Method B: Farcaster L1 Authentication (FID)

This method allows you to broadcast messages to Farcaster L1. You need:

  • A registered Farcaster ID (FID)
  • A signer key added to your FID on-chain
const authenticateWithFID = async (signature, address, signerId) => {
  const response = await fetch(`${BASE_URL}/auth/v2/authenticate`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "API-KEY": "your-api-key",
    },
    body: JSON.stringify({
      signature,
      address,
      chainId: 1,
      id: signerId, // Your signer ID registered on Farcaster
      type: "FID", // Specify FID authentication
    }),
  });

  const data = await response.json();
  return data.accessToken;
};

Important: The signer ID must be previously registered on-chain with your FID. See Farcaster documentation for details on signer registration.

​
Complete Authentication Example

// Here's a complete example using ethers.js:
const authenticateUser = async (wallet, type = "signature") => {
  try {
    // Step 1: Get the address
    const address = await wallet.getAddress();

    // Step 2: Get message to sign
    const message = await getSigninMessage(address);

    // Step 3: Sign the message
    const signature = await wallet.signMessage(message);

    // Step 4: Authenticate
    if (type === "FID") {
      return await authenticateWithFID(signature, address, YOUR_SIGNER_ID);
    } else {
      return await authenticateWithSignature(signature, address);
    }
  } catch (error) {
    console.error("Authentication failed:", error);
    throw error;
  }
};

​
Using the Access Token

Once authenticated, use the access token in subsequent requests:

const makeAuthenticatedRequest = async (accessToken) => {
  const response = await fetch(`${BASE_URL}/your/protected/endpoint`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "API-KEY": "your-api-key",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      // Your request data
    }),
  });

  return await response.json();
};

​
Security Considerations

  1. Never expose your private keys or mnemonics
  2. Store access tokens securely
  3. Implement token refresh mechanisms
  4. Use environment variables for sensitive data

​
Common Error Scenarios

  1. Invalid Signer ID

    • Error: “Signer not found”
    • Solution: Ensure signer is registered on-chain for your FID

  2. Invalid Signature

    • Error: “Invalid signature”
    • Solution: Verify the message being signed matches the one returned by the signing endpoint

  3. Expired Token

    • Error: “Token expired”
    • Solution: Re-authenticate to get a new token

​
API Endpoints Reference

​
Authentication Endpoints

  1. Get Signin Message
    GET /auth/v1/get-account-signin-message Query Parameters:

    • address: Ethereum address
    • chainId: Chain ID (1 for Ethereum mainnet)

  2. Authenticate
    POST /auth/v2/authenticate Body Parameters:

    • signature: Signed message
    • address: Ethereum address
    • chainId: Chain ID
    • type: “FID” or “signature”
    • id: Signer ID (required for FID authentication)

​
References