Guides

Farcaster Actions Spec

Suggest Edits

📘

Related API reference here

Introduction

Farcaster Actions is a spec that allows Farcaster applications to securely communicate and perform actions on behalf of users across different apps. It enables an app (referred to as App A) to send data or trigger actions in another app (App B) on behalf of a mutual user (e.g., Carol) by signing messages using the user's Farcaster signer.

This document provides an overview of how Farcaster Actions works and guides developers in implementing this functionality within their Neynar applications.

Overview of Farcaster Actions

  • Purpose: Facilitate secure cross-app interactions on behalf of users.
  • Participants:
    • User: The individual (e.g., Carol) who authorizes actions between apps.
    • App A: The initiating app requesting to perform an action in App B.
    • App B: The receiving app that processes the action from App A.
    • Neynar API: The intermediary that assists in signing and forwarding the action securely.

Workflow

1. Requesting Signer Access

App A requests a Farcaster signer from the user (Carol)

  • User Authorization: Carol approves the signer.
  • Signer UUID: Upon approval, App A receives a unique identifier (UUID) for Carol's signer.

2. Making an API Call with Signer UUID and Metadata

App A prepares to send an action to App B by making an API call to the Neynar API, including:

  • Signer UUID: The unique identifier for Carol's signer.
  • Destination base URL: The base URL of App B where the action should be sent.
  • Action Payload: An object containing the type of action and any necessary payload data.

3. Neynar API Produces a Signature

The Neynar API processes the request from App A:

  • Signature Generation: Neynar uses Carol's signer to generate a cryptographic signature
  • Bearer Token Creation: A bearer token is created, encapsulating the signature and additional metadata, which will be used for authentication.

4. Forwarding the Signed Message to App B

Neynar forwards the signed action to App B:

  • HTTP Request: An HTTP POST request is sent to App B's specified endpoint.
  • Headers: The request includes an Authorization header containing the bearer token.
  • Body: The action payload is included in the request body.

5. App B Verifies the Signature

Upon receiving the request, App B performs the following:

  • Signature Verification: App B verifies the bearer token using Carol's public key and ensures the signature is valid.
  • Farcaster ID (fid): The token includes Carol's fid, confirming her identity.
  • Action Processing: If verification succeeds, App B processes the action and updates its state accordingly.

Implementation Details

For App A Developers

  1. Request Signer Access:

  2. Prepare the Action Request:

    • Define the action payload, including the type and any necessary data.
    • Specify the destination base URL of App B.

  3. Call the Neynar API:

    • Make a POST request to the Neynar API endpoint (POST - /v2/farcaster/action) with the following structure:

      {
  "signer_uuid": "uuid-of-the-signer",
  "url": "https://appb.xyz",
  "action": {
    "type": "actionType",
    "payload": {
      // Action-specific data
    }
  }
}

  4. Handle the Response:

    • The Neynar API will forward the action to App B and return the response from App B.
    • Ensure proper error handling for cases where the action fails or the signature is invalid.

For App B Developers

  1. Set Up an Endpoint to Receive Actions:

    • Create an HTTP endpoint to receive POST /api/farcaster/actionrequests from the Neynar API.
    • Ensure the endpoint URL is accessible and secured via HTTPS.

  2. Extract and Verify the Bearer Token:

    • Extract the Authorization header from incoming requests.
    • Decode the bearer token to retrieve the header, payload, and signature.
    • Use the fid and public key from the token header to verify the signature against the payload.

  3. Process the Action:

    • Once the signature is verified, extract the action payload from the request body.
    • Perform the necessary operations based on the action type and payload.
    • Update your application's state or database as required.

  4. Respond to the Request:

    • Return an appropriate HTTP response indicating success or failure.
    • Include any necessary data in the response body for App A to process.

Security Considerations

  • Token Expiration: The bearer token has a short expiration time (5 minutes) to enhance security.
  • Signer Confidentiality: Private keys are managed securely by Neynar and are never exposed to apps.
  • Data Integrity: Signatures ensure that the action payload cannot be tampered with during transit.

Conclusion

Farcaster Actions provides a secure and efficient way for Neynar apps to interact on behalf of users. By leveraging cryptographic signatures and Neynar's API, apps can ensure that cross-app actions are authenticated and authorized by the user, enhancing trust and interoperability within the Neynar ecosystem.

Example

Action Schema

The action request sent to the Neynar API follows this schema:

{
  "signer_uuid": "string (UUID format)",
  "url": "string (valid URL)",
  "action": {
    "type": "string",
    "payload": {
      // Object containing action-specific data
    }
  }
}

Sample Request from App A to Neynar API

POST /v2/farcaster/action
Content-Type: application/json

{
  "signer_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://appb.example.com",
  "action": {
    "type": "sendMessage",
    "payload": {
      "message": "Hello from App A!"
    }
  }
}

Forwarded Request from Neynar API to App B

POST /api/farcaster/action
Content-Type: application/json
Authorization: Bearer Token

{
  "action": {
    "type": "sendMessage",
    "payload": {
      "message": "Hello from App A!"
    }
  }
}

App B would then verify the bearer token and process the action accordingly.

Updated about 2 months ago