# Token Policy

*[Documentation index](/llms.txt) · [Full index](/llms-full.txt)*

`TokenPolicy` is a shared object that a token owner can create using the `TreasuryCap`. Having a publicly available `TokenPolicy` enables onchain discovery of allowed actions and their conditions. This is useful for wallets and other services that want to provide a better user experience for token holders.

## Create and share

You create a new `TokenPolicy` using the `token::new_policy` function. The function takes the `TreasuryCap` as an argument and returns a `TokenPolicy` object and a managing capability.

```move
// module: sui::token
public fun new_policy<T>(
    treasury_cap: &TreasuryCap<T>,
    ctx: &mut TxContext
): (TokenPolicy<TokenType>, TokenPolicyCap<TokenType>);
```

You must use the `token::share_policy` function to share the `TokenPolicy` object.

## Allow and disallow

To allow methods without any conditions, use the `token::allow` function. The function takes a `TokenPolicy` and `TokenPolicyCap` as arguments. If allowed, the action can be confirmed in the `TokenPolicy` using the `token::confirm_request` function (see [`ActionRequest`](/onchain-finance/closed-loop-token/action-request#confirming-with-tokenpolicy)).

```move
// module sui::token
public fun allow<T>(
    policy: &mut TokenPolicy<T>,
    policy_cap: &TokenPolicyCap<T>,
    action: String,
    ctx: &mut TxContext
);
```

Similarly, you can use the `token::disallow` function to completely disable an action; it takes the same arguments as `token::allow`.

## Adding rules

`TokenPolicy` can specify custom conditions for each action. These conditions are called rules and are typically implemented as separate Move modules. The identifier of the rule is its type. See [Rules](/onchain-finance/closed-loop-token/rules) for more information.

The pseudo-code structure of the `TokenPolicy` is as follows. Each action can have multiple rules associated with it.

```yaml
TokenPolicy
  rules:
    - action: "transfer"
      rules:
        - 0x0...::denylist::Denylist
    - action: "to_coin"
      rules:
        - 0x0...::limiter::Limiter
        - 0x0...::allowlist::Allowlist
    ...
```

To add a rule for an action, use the `token::add_rule_for_action` function. The function takes a `TokenPolicy` and `TokenPolicyCap` as arguments. The rule is specified by its type (for example, `0x0...::denylist::Denylist`).

```move
// module: sui::token
public fun add_rule_for_action<T, Rule: drop>(
    policy: &mut TokenPolicy<T>,
    policy_cap: &TokenPolicyCap<T>,
    action: String,
    ctx: &mut TxContext
);
```

Signature for the reverse operation `token::remove_rule_for_action` is symmetrical to `token::add_rule_for_action`.

## Consume spent balance

Spent balance can be consumed from the `TokenPolicy` using the `token::flush` function. It requires a `TreasuryCap`.

```move
// module sui::token
public fun flush<T>(
    policy: &mut TokenPolicy<T>,
    treasury_cap: &mut TreasuryCap<T>,
    ctx: &mut TxContext
);
```

## Cheat sheet: TokenPolicy API

| Function                    | Note                                                                 |
|-----------------------------|----------------------------------------------------------------------|
| new_policy                  | Create a new `TokenPolicy` using the `TreasuryCap`                       |
| allow                       | Allow an action in the `TokenPolicy`                                   |
| disallow                    | Disallow an action in the `TokenPolicy`                                |
| add_rule_for_action         | Add a rule for an action in the `TokenPolicy`                          |
| remove_rule_for_action      | Remove a rule for an action in the `TokenPolicy`                       |
| confirm_request             | Confirm an `ActionRequest` with a `TokenPolicy`                          |
| confirm_request_mut         | Similar to `confirm_request` but only works for `spend` action       |
| flush                       | Flush the spent balance from the `TokenPolicy` (see [Spending](/onchain-finance/closed-loop-token/spending)) |