actions.json

The actions.json file serves as a guide for Action Clients, indicating which website URLs support Ethereum Actions and providing a mapping for making GET requests to an Action API. This file helps translate regular website URLs into Action URLs that can be used to interact with Ethereum Actions.

The actions.json file should be stored and accessible at the root of the domain.

For example, if your web application is at my-site.com, the actions.json file should be accessible at https://my-site.com/actions.json. This file must be Cross-Origin accessible from any browser by including an Access-Control-Allow-Origin header with a value of *.

Rules

The rules field allows mapping a set of website's relative route paths to corresponding Action API paths.

Type: Array of ActionRuleObject.

interface ActionRuleObject {
  /** relative (preferred) or absolute path for rule mapping */
  pathPattern: string;
  /** relative (preferred) or absolute path supporting Action requests */
  apiPath: string;
}

• pathPattern: A pattern matching incoming pathnames.
• apiPath: The destination path for Action requests, defined as an absolute pathname or external URL.

pathPattern

This pattern matches incoming pathnames and can be an absolute or relative path. It supports the following formats:

1. Exact Match: Matches the exact URL path.

   • Example: /exact-path
   • Example: https://website.com/exact-path

2. Wildcard Match: Uses wildcards to match character sequences in the URL path.

   • Single segment (*): /trade/* matches /trade/123 and /trade/abc
   • Multiple segments (**): /category/*/item/** matches /category/123/item/456 and /category/abc/item/def
   • Mixed: /api/actions/trade/*/confirm matches /api/actions/trade/123/confirm

apiPath

The destination path for Action requests, defined as an absolute pathname or external URL.

Examples:

• /api/exact-path
• https://api.example.com/v1/donate/*
• /api/category/*/item/*
• /api/swap/**

Query parameters

Query parameters from the original URL are always preserved and appended to the mapped URL.

Path Matching

Path matching patterns use the following syntax:

Rules Examples

1. Exact match rule: Maps requests to /buy from your site's root to /api/buy relative to your site's root:

{
  "rules": [
    {
      "pathPattern": "/buy",
      "apiPath": "/api/buy"
    }
  ]
}

2. Wildcard path matching: Maps requests to any path (excluding subdirectories) under /actions/ from your site's root to a corresponding path under /api/actions/:

{
  "rules": [
    {
      "pathPattern": "/actions/*",
      "apiPath": "/api/actions/*"
    }
  ]
}

3. Wildcard path matching with external API: Maps requests to any path (excluding subdirectories) under /donate/ from your site's root to a corresponding absolute path on an external site:

{
  "rules": [
    {
      "pathPattern": "/donate/*",
      "apiPath": "https://api.example.com/api/v1/donate/*"
    }
  ]
}

4. Idempotent rule with wildcard path matching: Maps requests to any path (including subdirectories) under /api/actions/ from your site's root to itself:

{
  "rules": [
    {
      "pathPattern": "/api/actions/**",
      "apiPath": "/api/actions/**"
    }
  ]
}