Skip to content

Ethereum Actions

The Ethereum Actions specification defines a set of standard APIs to deliver transaction parameters (and in the future, message parameters) from an Action API to an Action Client. These Ethereum Actions are accessible via Action Links, allowing any Action Client to interact with the corresponding Action API endpoints.

The Action API involves making simple GET and POST requests to an Action URL and handling the responses that conform to the Ethereum Actions interface.

  1. The GET request returns metadata that provides human-readable information about what actions are available at this URL and may include an optional list of related actions.
  2. The POST request returns transaction parameters that the Action Client uses to construct a transaction. The Action Client then prompts the user to review, approve, and sign this transaction with wallet before sending it to the blockchain.

Action Execution and Lifecycle

Interacting with Ethereum Actions is similar to interacting with a typical REST API:

  • An Action Client initiates a GET request to an Action URL to fetch metadata about the available Actions.
  • The Action API returns a response with metadata about itself (such as the application's title and icon) and a list of available actions.
  • The Action Client (which could be a mobile wallet, chatbot, or website) displays a UI for the user to perform one of the actions.
  • Once the user chooses an action (by clicking a button), the Action Client makes a POST request to the Action API to get the transaction for the user to sign.
  • The wallet component of the Action Client helps the user sign the transaction and ultimately sends it to the blockchain for confirmation.
Action Lifecycle

When receiving transactions from an Action URL, Action Clients should handle the submission of these transactions to the blockchain and manage their state lifecycle.

Actions also support some level of validation before execution. The GET and POST requests may return metadata indicating whether the action can be taken (such as with the disabled field).

For example, if there is an Action API for voting on a DAO governance proposal whose voting period has ended, the initial GET request may return an error message stating "This proposal is no longer open for voting" and mark the "Vote Yes" and "Vote No" buttons as "disabled".

Key Concepts Recap

  • Ethereum Actions: Standardized API specifications for creating and executing Ethereum blockchain transactions.

  • Action URL: The direct URL to an Ethereum Action API endpoint. This is where Action Clients send their GET and POST requests. Example: https://api.example.com/actions/vote

  • Action Link: A special URL format that encapsulates an Action URL, designed for easy sharing and initiation of blockchain interactions. It typically starts with the eth-action: protocol identifier. Example: eth-action:https://api.example.com/actions/vote

  • Action API: The server-side implementation that responds to requests made to Action URLs.

  • Action Client: Applications (like wallets or browser extensions) that can interpret Action Links, extract the Action URLs, and interact with Action APIs.

This framework allows for a seamless flow from user-friendly sharing (via Action Links) to actual API interactions (via Action URLs), all interpreted and executed by Action Clients.