# Managing Policy Engines
Source: https://docs.chain.link/ace/guides/policy-manager/manage-engines
Last Updated: 2026-09-23

> For the complete documentation index, see [llms.txt](/llms.txt).

A **policy engine** is the on-chain orchestrator that evaluates policies whenever a protected function is called. Each policy engine is deployed as a smart contract on one or more chains, and all your targets, policies, and protections are scoped to a specific engine. For a deeper explanation of how policy engines fit into the architecture, see [Architecture](/ace/concepts/architecture) and [Policy Management](/ace/concepts/policy-management).

> **NOTE**
>
> Before creating a policy engine, make sure you have completed [Account Setup](/ace/getting-started/account-setup) and
> have a [CRE Connect Wallet](/ace/getting-started/account-setup#4-set-up-cre-connect-wallets) deployed on each chain
> where you want the engine to operate.

## Create a policy engine

**Platform UI**

1. In the [Chainlink Platform](https://app.chain.link), go to **Compliance > Policy Manager**.
2. Click **Create a new engine**.
3. Complete the three-step wizard:
   - **Basic details** — enter an engine name and optional description. This metadata is internal and is not written onchain.
   - **Networks** — select every chain where you want this engine deployed. Only networks enabled in your CRE account appear. If you do not see a network, contact your admin to ensure it is enabled in your CRE account first. Deploy a [CRE Connect Wallet](/ace/getting-started/account-setup#4-set-up-cre-connect-wallets) on each selected chain before creating the engine.
   - **Contract types** — select **ERC-20**, **ERC-3643**, and/or **CCIP-AdvancedPoolHooks**. ACE attaches the pre-built extractors for the selected types automatically. For the CCIP-specific setup, see [Protect CCIP Token Pools with ACE](/ace/guides/policy-manager/ccip-token-pools).
4. Submit the wizard and wait for onchain deployment to complete. The engine starts in `creation_pending` status until deployment finishes.
5. Open the engine in Policy Manager and confirm its status is **Active**. Click the **gear icon** to view the onchain contract addresses and attached extractors.

For verification and troubleshooting during deployment, see [Create a PolicyEngine](/ace/getting-started/policy-manager#3-create-a-policyengine) in the Policy Manager Quick Start.

> **NOTE: Mainnet access**
>
> Mainnet networks are not enabled for all organizations by default. If you do not see mainnet networks in the
> **Networks** step, contact your Chainlink contact to request access.

**API**

Create a policy engine with a `POST` request. Each entry in `onchain_policy_engines` specifies a `chain_selector` for a target chain (see [Supported Networks](/ace/supported-networks) for available chain selectors):

```bash
curl -X POST https://ace.api.chain.link/v1/policy-engines \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "name": "Production Policy Engine",
    "description": "Main policy engine for compliance enforcement",
    "onchain_policy_engines": [
      { "chain_selector": "16015286601757825753" },
      { "chain_selector": "3478487238524512106" },
      { "chain_selector": "14767482510784806043" },
      { "chain_selector": "16281711391670634445" },
      { "chain_selector": "10344971235874465080" }
    ]
  }'
```

| Field                    | Required | Description                                                             |
| ------------------------ | -------- | ----------------------------------------------------------------------- |
| `name`                   | Yes      | Human-readable name                                                     |
| `description`            | No       | Description of the engine's purpose                                     |
| `extractor_ids`          | No       | Array of extractor UUIDs to register with the engine                    |
| `contract_type_ids`      | No       | Array of contract type UUIDs to register on the engine                  |
| `onchain_policy_engines` | Yes      | Array of objects with `chain_selector` values for each deployment chain |

> **TIP: Attach extractors at creation time**
>
> Include the `extractor_ids` field when creating your engine so extractors are registered immediately. For ERC-20
> and ERC-3643 contracts, see the [Policy Manager Quick
> Start](/ace/getting-started/policy-manager#extractor-ids-for-api-creation) for the pre-built extractor IDs. For
> `CCIP-AdvancedPoolHooks`, see [Protect CCIP Token Pools with
> ACE](/ace/guides/policy-manager/ccip-token-pools). For a custom contract type, register your extractor first. See
> [Custom Contract Types & Extractors](/ace/guides/policy-manager/contracts/custom-contract-types).

Each on-chain engine starts in `creation_pending` status until deployment completes. The response includes the engine `id` and the on-chain contract addresses.

## View policy engines

**Platform UI**

1. In the [Chainlink Platform](https://app.chain.link), go to **Compliance > Policy Manager** in the left sidebar. You see all the policy engines in your organization.

2. Click on a policy engine to open it. The detail view has two tabs:
   - **Contracts** — lists the target contracts protected by this policy engine.
   - **Policy instances** — lists all deployed policy instances associated with this policy engine.

3. To view the engine's on-chain details, click the **gear icon** to open the settings page. There you can see:

   - The **PolicyEngine contract addresses** on each network the engine is deployed to.
   - The **Extractors** currently attached to this policy engine.

   ![Image](/images/ace/policy-engines/policy-engine-settings-2.webp)

**API**

List all policy engines:

```bash
curl https://ace.api.chain.link/v1/policy-engines \
  -H "Authorization: Apikey <API_KEY>"
```

| Parameter          | Description                                         |
| ------------------ | --------------------------------------------------- |
| `page`             | Page number (default: 1)                            |
| `page_size`        | Results per page (max: 100)                         |
| `include_onchains` | Include on-chain deployment details (default: true) |

To retrieve a specific engine by ID:

```bash
curl https://ace.api.chain.link/v1/policy-engines/<POLICY_ENGINE_ID> \
  -H "Authorization: Apikey <API_KEY>"
```

## Update a policy engine

You can update a policy engine's name, description, and extractor associations.

**Platform UI**

> **NOTE**
>
> Updating a policy engine is not yet available through the Platform UI. Use the **API** tab to update one via the Coordinator API.

**API**

Update a policy engine with a `PUT` request. Both `name` and `onchain_policy_engines` are required:

```bash
curl -X PUT https://ace.api.chain.link/v1/policy-engines/<POLICY_ENGINE_ID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "name": "Production Policy Engine (Updated)",
    "description": "Updated description",
    "extractor_ids": ["<EXTRACTOR_ID>"],
    "onchain_policy_engines": [
      { "chain_selector": "16015286601757825753" },
      { "chain_selector": "3478487238524512106" },
      { "chain_selector": "14767482510784806043" },
      { "chain_selector": "16281711391670634445" },
      { "chain_selector": "10344971235874465080" }
    ]
  }'
```

## Add or remove extractors

Extractors decode transaction calldata into named parameters (sender, recipient, amount, etc.) so policies can evaluate them. If you forgot to attach an extractor during engine creation or need to remove one, use the `PUT /policy-engines/{id}` endpoint.

> **CAUTION: Full replacement**
>
> The `extractor_ids` field in a PUT request **replaces all current extractors** — it is not additive. Always include
> every extractor you want to keep. Omitting an extractor from the list detaches it from the engine.

### Add a missing extractor

First, retrieve your engine to see which extractors are currently attached:

```bash
curl https://ace.api.chain.link/v1/policy-engines/<POLICY_ENGINE_ID> \
  -H "Authorization: Apikey <API_KEY>"
```

Check the `extractor_registrations` array in the response. Then send a PUT request that includes the existing extractor IDs plus the new one:

```bash
curl -X PUT https://ace.api.chain.link/v1/policy-engines/<POLICY_ENGINE_ID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "name": "My Policy Engine",
    "extractor_ids": [
      "d4b8cd51-7d5a-487a-9ba5-bb7236e3184c",
      "572201bb-170b-4fda-ab89-a65b5bbc594b",
      "f17bbe8b-8462-4dd7-8fb7-a4973dff04fc"
    ],
    "onchain_policy_engines": [
      { "chain_selector": "16015286601757825753" },
      { "chain_selector": "3478487238524512106" },
      { "chain_selector": "14767482510784806043" },
      { "chain_selector": "16281711391670634445" },
      { "chain_selector": "10344971235874465080" }
    ]
  }'
```

In this example, `f17bbe8b-8462-4dd7-8fb7-a4973dff04fc` is the new extractor being added alongside two that were already attached.

### Remove an extractor

Send a PUT request with the `extractor_ids` array that **omits** the extractor you want to detach:

```bash
curl -X PUT https://ace.api.chain.link/v1/policy-engines/<POLICY_ENGINE_ID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "name": "My Policy Engine",
    "extractor_ids": [
      "d4b8cd51-7d5a-487a-9ba5-bb7236e3184c",
      "572201bb-170b-4fda-ab89-a65b5bbc594b"
    ],
    "onchain_policy_engines": [
      { "chain_selector": "16015286601757825753" },
      { "chain_selector": "3478487238524512106" },
      { "chain_selector": "14767482510784806043" },
      { "chain_selector": "16281711391670634445" },
      { "chain_selector": "10344971235874465080" }
    ]
  }'
```

> **TIP: Available extractors**
>
> See the [Policy Manager Quick Start](/ace/getting-started/policy-manager#extractor-ids-for-api-creation) for ERC-20
> and ERC-3643 extractor IDs. For `CCIP-AdvancedPoolHooks`, see [Protect CCIP Token Pools with
> ACE](/ace/guides/policy-manager/ccip-token-pools). You can retrieve every available extractor with `GET
>   https://ace.api.chain.link/v1/extractors`.

## Archive a policy engine

Archiving a policy engine deactivates it and prevents any further operations. All policy instances associated with the engine must be archived first.

**Platform UI**

> **NOTE**
>
> Archiving a policy engine is not yet available through the Platform UI. Use the **API** tab to archive one via the Coordinator API.

**API**

Archive a policy engine with a `PATCH` request:

```bash
curl -X PATCH https://ace.api.chain.link/v1/policy-engines/<POLICY_ENGINE_ID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "status": "archived"
  }'
```

> **CAUTION**
>
> All policy instances must be archived before the engine itself can be archived. Attempting to archive an engine with
> active policies returns an error.

## Related pages

- [Architecture](/ace/concepts/architecture) — how PolicyEngine contracts fit into the ACE system
- [Policy Management](/ace/concepts/policy-management) — how policy chains and evaluation work
- [Managing Targets](/ace/guides/policy-manager/manage-targets) — detect or register contracts to protect under an engine
- [Managing Policies](/ace/guides/policy-manager/manage-policies) — create and configure policy instances
- [Protect CCIP Token Pools with ACE](/ace/guides/policy-manager/ccip-token-pools) — configure a policy engine for CCIP AdvancedPoolHooks
- [Coordinator API Reference](/api/ace/coordinator/docs) — full API schema