# MsgSetIncomingApproval

A helper message to set a single incoming approval for token transfers. This is a developer-friendly wrapper around `MsgUpdateUserApprovals` that simplifies setting individual incoming approvals. For more information, we refer to the [MsgUpdateUserApprovals](/token-standard/messages/msg-update-user-approvals.md) documentation.

## Overview

This message allows you to set or update a single incoming approval without having to construct the full `MsgUpdateUserApprovals` message. It automatically handles version management and validation.

## Proto Definition

```protobuf
message MsgSetIncomingApproval {
  string creator = 1; // User setting the approval
  string collectionId = 2; // Target collection for approval
  UserIncomingApproval approval = 3; // The incoming approval to set
}

message MsgSetIncomingApprovalResponse {
  string action = 1; // "created" or "edited"
  string version = 2; // The new version of the approval
  repeated string reviewItems = 3; // Advisory review items about the transaction
}
```

## Response

The response includes:

* **`action`**: Whether the approval was `"created"` or `"edited"`
* **`version`**: The new version number of the approval after the operation
* **`reviewItems`**: Advisory strings about the transaction (see [Review Items](https://github.com/trevormil/bitbadges-docs/blob/master/x-tokenization/concepts/approval-change-events.md#review-items))

## Usage Example

```bash
# CLI command
bitbadgeschaind tx tokenization set-incoming-approval [collection-id] '[approval-json]' --from user-key
```

## Behavior

* **New Approval**: If the approval ID doesn't exist, a new approval is created with version 0
* **Update Existing**: If the approval ID already exists, the approval is updated and the version is incremented
* **No Change**: If the approval content hasn't changed, the version remains the same
* **Validation**: The approval is validated according to the collection's permissions and user's approval update permissions

## Authorization & Permissions

Users can only set their own incoming approvals. The operation must be performed according to the permissions set (i.e. the `userPermissions` previously set for that user).

## Related Messages

* [MsgUpdateUserApprovals](/token-standard/messages/msg-update-user-approvals.md) - Full approval management
* [MsgDeleteIncomingApproval](/token-standard/messages/msg-delete-incoming-approval.md) - Delete an incoming approval
* [MsgSetOutgoingApproval](/token-standard/messages/msg-set-outgoing-approval.md) - Set an outgoing approval


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitbadges.io/token-standard/messages/msg-set-incoming-approval.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.