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.

CORS Headers

The actions.json file response must include valid CORS Headers for the GET & OPTIONS requests especially a Access-Control-Allow-Origin header value of *

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:

Operator	Matches
*	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/**"
    }
  ]
}

Open Graph Meta Tags

For a blink to render when the URL of your action website is pasted, a couple of Open Graph meta tags or X (Twitter) meta tags need to be included in the <head> of your webpage. For example:

<head>
<title>The Rock (1996)</title>
<meta property="og:title" content="The Rock" />
<meta property="og:type" content="video.movie" />
<meta property="og:url" content="https://www.imdb.com/title/tt0117500/" />
<meta property="og:image" content="https://ia.media-imdb.com/images/rock.jpg" />
...
</head>