POST

A POST route supports both a request and a response. We'll cover each below and discuss how these relate to Actions.

POST Request

Actions support HTTP POST JSON requests to their URL with this body payload:

{
  "account": "<account>"
}

Here, account is a base58-encoded representation of the public key of the user making the request.

To facilitate HTTP compression, clients should use Accept-Encoding headers when requesting, and the Action service should use a Content-Encoding header when responding.

Post Response

Actions services should respond to POST requests with an HTTP OK response in a payload formatted like this:

/**
 * Response body payload returned from the Action POST Request
 */

export type PostActionType = LinkedActionType;

/**
 * Generic response from an Action API request
 */
export interface ActionResponse {
  type?: PostActionType;
  message?: string;
  links?: {
    next: NextActionLink;
  };
}

/**
 * Response body payload returned from the Action POST Request if the action is a transaction
 */
export interface TransactionResponse extends ActionResponse {
  type?: Extract<PostActionType, "transaction">;
  transaction: string;
}

/**
 * Response body payload returned from the Action POST Request if the action is a POST request
 */
export interface PostResponse extends ActionResponse {
  type: Extract<PostActionType, "post">;
}

/**
 * Response body payload returned from the Action POST Request if the action is an External Link
 */
export interface ExternalLinkResponse extends ActionResponse {
  type: Extract<PostActionType, "external-link">;
  externalLink: string;
}

/**
 * Response body payload returned from the Action POST Request
 */
export type ActionPostResponse =
  | TransactionResponse
  | PostResponse
  | ExternalLinkResponse;

The links.next parameter in ActionPostResponse is related to the Action Chaining spec and is currently not supported by all Blinks-enabled wallets. We're working on bringing Blinks support for it as soon as possible.

• The client must handle HTTP client errors, server errors, and redirect responses.

• The endpoint should respond with an application/json Content-Type header.

The POST request also accepts ActionError responses. This can be found in the GET specification and is useful in cases where you want to have custom input validation in the request and return an error when requirements haven't been satisfied.

New POST types supported

• type - If this is of type

  • transaction then client will pop-up the user to sign the transaction and then after confirmation render links.next.

  • post then client will skip the pop-up and render the links.next.

• transaction - The value must be a base64-encoded serialized transaction. The client must base64-decode the transaction anddeserialize it.

• message - The value must be a UTF-8 string that describes the nature of the transaction included in the response. The client should display this value to the user. For example, this might be the name of an item being purchased, a discount applied to a purchase, or a thank you note.

• links.next - An optional value use to "chain" multiple Actions together in series. After the included transaction has been confirmed on-chain, the client can fetch and render the next action. See Action Chaining for more details.

• The client and application should allow additional fields in the request body and response body, which may be added by future specification updates.