actions.json

As described in the URL Scheme section, an actions.json file may be used at the root URL of a website to create a mapping between pages on that website and their associated actions. Clients that render Blinks, when provided with a website URL, may check for the presence of this file at the site's root URL

For example, my-site.com would store its actions.json file at https://my-site.com/actions.json, and this single file would be responsible for the mapping rules for all my-site.com pages.

Rules

The rules field allows the application to map a set of a website's relative route paths to a set of other paths.

Type: Array of ActionRuleObject.

interface ActionRuleObject {
  /** relative (preferred) or absolute path to perform the rule mapping from */
  pathPattern: string;
  /** relative (preferred) or absolute path that supports Action requests */
  apiPath: string;
}
  • pathPattern - A pattern that matches each incoming pathname.

  • apiPath - A location destination defined as an absolute pathname or external URL.

Rules - pathPattern

A pattern that matches each incoming pathname. It can be an absolute or relative path and supports the following formats:

  • Exact Match: Matches the exact URL path.

    • Example: /exact-path

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

  • Wildcard Match: Uses wildcards to match any sequence of characters in the URL path. This can match single (using *) or multiple segments (using **). (see Path Matching below).

    • Example: /trade/* will match /trade/123 and /trade/abc, capturing only the first segment after /trade/.

    • Example: /category/*/item/** will match /category/123/item/456 and /category/abc/item/def.

    • Example: /api/actions/trade/*/confirm will match /api/actions/trade/123/confirm.

Rules - apiPath

The destination path for the action request. It can be defined as an absolute pathname or an external URL.

  • Example: /api/exact-path

  • Example: https://api.example.com/v1/donate/*

  • Example: /api/category/*/item/*

  • Example: /api/swap/**

Rules - Query Parameters

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

Rules - Path Matching

The following table outlines the syntax for path matching patterns:

OperatorMatches

*

A single path segment, not including the surrounding path separator / characters.

**

Matches zero or more characters, including any path separator / characters between multiple path segments. If other operators are included, the ** operator must be the last operator.

?

Unsupported pattern.

Rules Examples

The following example demonstrates an exact match rule to map requests requests to /buy from your site's root to the exact path /api/buy relative to your site's root:

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

The following example uses wildcard path matching to map requests to any path (excluding subdirectories) under /actions/ from your site's root to a corresponding path under /api/actions/ relative to your site's root:

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

The following example uses wildcard path matching to map requests to any path (excluding subdirectories) under /donate/ from your site's root to a corresponding absolute path https://api.dialect.com/api/v1/donate/ on an external site:

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

The following example uses wildcard path matching for an idempotent rule to map requests to any path (including subdirectories) under /api/actions/ from your site's root to itself:

Idempotent rules allow blink clients to more easily determine if a given path supports Action API requests without having to be prefixed with the solana-action: URI or performing additional response testing.

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

actions.json vs. Open Graph meta tags

Open Graph meta tags are an alternative solution for mapping websites to associated actions, but are not used for performance reasons.

Loading meta tags requires loading full page HTML, which can be costly. A single actions.json file at a website's root URL can specify all necessary is light to load, does not change often, and so can be cached.

Last updated