Skip to content

Action Clients

Action Clients are applications that can detect Action Links, parse them, and allow users to interact with Ethereum Actions through standardized user interfaces.

Action Link Specification

An Action Link is a format for invoking Ethereum Actions, allowing users to execute these actions, including signing with their wallet.

For an application to function as an Action Client, it must:

  1. Recognize Action Links, which may be in various formats (detailed below).
  2. Extract the Action URL from the Action Link.
  3. Fetch and interpret the Action API from the extracted Action URL.
  4. Render a user interface for executing the Ethereum Action, including wallet signing.

Action Link Types

Action Links can take three main forms: 1. Direct Action Link:

Format: eth-action:<action_url>
Example: eth-action:https://actions.alice.com/donate

This is the most straightforward form. It directly specifies the Action URL prefixed with eth-action:. Only Action Clients can render these properly. Non-supporting applications will not display a preview or alternative.

2. Website URL with associated actions.json:

Format: <website_url>
Example: https://alice.com/donate

This method uses an actions.json file at the website's root to map website URLs to Action URLs.

For example:

  • Website URL: https://alice.com/donate
  • Corresponding actions.json entry:
{
  "/donate": "https://actions.alice.com/donate"
}

The actions.json file allows Action Clients to discover the actual Action URL https://actions.alice.com/donate when given the website URL https://alice.com/donate.

3. Wrapper Action Link:

Format: https://<wrapper_domain>/?action=<encoded_action_url>
Example: https://ethlink.io/?action=eth-action%3Ahttps%3A%2F%2Factions.alice.com%2Fdonate

This method wraps the Action URL within a standard URL format. It allows Action Links to be used in contexts that only accept standard web URLs.

Handling Action Links

Action Clients should process all types of Action Links as follows:

  1. Direct Action Links: Extract the Action URL, then render the full Ethereum Action interface.
  2. Website URLs with actions.json: Fetch the actions.json, find the corresponding Action URL, then render the Ethereum Action interface.
  3. Wrapper Action Links: Extract the embedded Action URL, then render the Ethereum Action interface.

Non-Action Clients (like standard web browsers) should handle these URLs in this manner:

  1. Direct Action Links: May display an error or blank page, as there's no built-in fallback.
  2. Website URLs with actions.json: Display the regular web page at that URL.
  3. Wrapper Action Links: The wrapper service should redirect to a relevant web page.

When using an Action Client, if a user interacts with parts of the interface not directly related to executing the Ethereum Action (like clicking outside of action buttons), the client should redirect the user to the fallback web page for that Action. This ensures users can always access more information or alternative methods if needed.

Testing and Verification

While the Ethereum Actions protocol is open, Action Clients and wallets must ensure secure transaction signing.

Action Clients may have different criteria for automatically displaying Ethereum Actions, especially on social media platforms. Some may require verification before displaying an Action.

Public Action Registry

A public registry of verified Action URLs from known sources is maintained as a community resource at https://ethlink.io/registry.

Action Clients can opt to use this registry or alternative solutions for security. Unverified Action URLs will typically be treated as standard web URLs.

Developers can apply for verification at: https://ethlink.io/register