> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.litprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Lit Actions are immutable JavaScript programs identified by their IPFS CID and executed inside the Lit network's TEE. They can sign with PKP wallets or with their own code-bound key, encrypt and decrypt secrets, and make HTTP requests — all verifiably.

How can a smart contract trust a price that came from an HTTP API? A contract can't make HTTP requests, and a server that fetches the price for it is one more party you have to trust. A Lit Action fetches the price inside the TEE and signs it with a key that only that exact code can use. The contract checks the signature, so it knows which code produced the price.

## A minimal example

```javascript theme={null}
// Fetch ETH price from an API and sign it with the action's own key.
// No PKP, no js_params, no setup beyond enrolling the CID in a group.
async function main() {
  const res = await fetch("https://api.example.com/eth-price");
  const { price } = await res.json();

  const wallet = new ethers.Wallet(await Lit.Actions.getLitActionPrivateKey());
  const payload = `ETH price: ${price}`;
  const signature = await wallet.signMessage(payload);

  return { payload, signature, signer: wallet.address };
}
```

Anyone can verify the output with `ethers.utils.verifyMessage(payload, signature)` and compare the recovered address to the address of this CID, obtained through `getLitActionWalletAddress` from any other action. Swap `getLitActionPrivateKey()` for `getPrivateKey({ pkpId })` if you want the proof bound to a wallet you manage instead.

## What is a Lit Action?

A Lit Action is an immutable JavaScript program identified by its IPFS CID and executed inside the Lit network's TEE. The CID is both the action's address and a commitment to its code: change one byte and you have a different action.

Actions have access to a small [SDK](https://docs.dev.litprotocol.com/lit-actions/chipotle.md) that lets them:

* **Sign data** with the private key of a Programmable Key Pair (PKP) or with the action's own identity key
* **Encrypt and decrypt** data with a symmetric key derived from a PKP, or with keys derived from the action's identity
* **Make HTTP requests** to APIs, oracles, and blockchains
* **Return a value** to the caller

Because the code is immutable and the keys never leave the enclave, an action's signed output is a proof that *this exact code* produced *this exact result*.

## How a request reaches your code

You run an action by sending its code to `POST /core/v1/lit_action` with a usage key. The server passes `js_params` to your `main` function as its argument, and whatever `main` returns comes back as `response`:

```bash theme={null}
curl -s -X POST "https://api.chipotle.litprotocol.com/core/v1/lit_action" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_USAGE_KEY" \
  -d '{"code":"async function main({ symbol }) { return { symbol }; }","js_params":{"symbol":"ETH"}}'
# Response: {"response":{"symbol":"ETH"},"logs":"","has_error":false}
```

Two rules follow from this, and the patterns in this section build on both:

* **The source is trusted and `js_params` is not.** The source is fixed by its CID, so anything written in it is part of the action's identity. Anyone who can call the action can put anything in `js_params`, so check those values before you act on them. [Derived Actions](https://docs.dev.litprotocol.com/lit-actions/derived-actions.md) builds on this rule.
* **Actions are stateless.** Each run starts fresh and remembers nothing from earlier calls. To keep state, store it outside the action and verify it when you read it back, as [Signed Data in Untrusted Storage](https://docs.dev.litprotocol.com/lit-actions/signed-storage.md) shows.

## What will this action sign with?

Start from what the signature has to mean. A price proof should mean "this exact code produced this price", so it should be signed with a key that belongs to the code itself. A treasury should keep its address when you ship a new version of its logic, so it should be signed with a wallet you manage. Those two needs map to the two kinds of keys below.

## Two kinds of keys

Every action can reach two different kinds of key. Knowing which to use is most of the design work.

| | PKP key | Action identity key |
| - | - | - |
| Get it with | `Lit.Actions.getPrivateKey({ pkpId })` | `Lit.Actions.getLitActionPrivateKey()` |
| Identity is bound to | A wallet you minted and manage in a [group](https://docs.dev.litprotocol.com/architecture/groups.md) | The action's code (its CID) |
| Who can use it | Any action whose CID is in the same group as the PKP | Only this action |
| Public key discovery | `list_wallets`, the Dashboard | `Lit.Actions.getLitActionPublicKey({ ipfsId })` from any action, for any CID |
| Setup | Mint the PKP, add it and the action to a group | None. Enroll the CID in a group. |
| Best for | Long-lived accounts whose code will evolve: treasuries, user wallets, vaults that several actions share | Anything that should be operable by exactly one piece of code: proofs, per-user wallets, per-secret encryption keys |

A PKP outlives its code. When you ship a new version of an action, you add the new CID to the group and the PKP keeps its address. An identity key dies with its code. Ship a new version and you have a new key, which is exactly what you want when the key's whole meaning is "this code approved it".

Because the identity key depends on every byte of the source, changing one constant in an audited template gives you a new immutable action with its own key. One template can then serve many users or secrets. See [Derived Actions](https://docs.dev.litprotocol.com/lit-actions/derived-actions.md).

## What is a proof?

When an action fetches external data (a price, a weather reading, another chain's state) and signs the result, that signed output is a **proof**. Anyone holding the signer's public key can verify that the specific computation produced it. Smart contracts cannot make HTTP requests; a Lit Action can, and can deliver the result on-chain with a signature the contract checks with `ecrecover`.

* **Data from outside the chain.** The action fetches the data and signs it, and the contract checks the signature.
* **Computation you can check.** The signature is tied either to a PKP you registered or to the exact CID that ran.
* **No intermediary to trust.** Neither the action author nor a single node can forge a result, because the code is immutable and the key never leaves the TEE.

## How actions fit into Chipotle

Actions are organized within **groups**. A group binds PKPs to the action CIDs allowed to use them, and usage API keys are scoped to execute within groups.

```
Account
 └── Group
      ├── PKP (wallet)            ← optional: identity-key actions need none
      ├── IPFS CID (action)
      └── Usage API Key (execute_in_groups)
```

When you call `/core/v1/lit_action`, the server hashes the submitted code to its CID, checks that the API key may execute in a group containing that CID, and only then runs it. Inside the action, every `getPrivateKey` / `Encrypt` / `Decrypt` call is checked again: the named PKP must be in a group with the running CID. There is no IPFS upload step. You send the source and the server derives the CID.

The usage key appears in the tree above because it points at the group through `execute_in_groups`. The permission is stored on the key, and the group itself doesn't list keys. Here is the whole path a request takes:

```mermaid theme={null}
%%{init: {"flowchart": {"useMaxWidth": false}}}%%
flowchart TD
    A["Request: usage key,<br/>code, js_params"] --> C(["Can this key run<br/>this code's CID?"])
    C -->|no| X["Refused with 403"]
    C -->|yes| D["Run main(js_params)<br/>in the TEE"]
    D -->|asks for a PKP| F(["Is the PKP in a group<br/>with this CID that<br/>the key can use?"])
    F -->|no| Y["The PKP call fails"]
    F -->|yes| G["Derive the PKP key<br/>in the TEE"]
    G --> R["Response: whatever<br/>main returned"]
    D -->|no PKP| R
```

Every request takes this path. A group answers "Can this action use this PKP?" A usage key's scopes answer "Can this caller use this group?" A wildcard key (`execute_in_groups: [0]`) passes the first check for any code, but it still needs a group to use a PKP.

## Patterns that make Chipotle easier

These four pages describe the load-bearing design patterns. They are what production apps on Chipotle, including the [Lit Agent Keychain](https://github.com/LIT-Protocol/chipotle/tree/main/lit-agent-keychain), are actually built from.

> [card] [Derived Actions](https://docs.dev.litprotocol.com/lit-actions/derived-actions.md)
>
> One audited template, a stamped-in constant, and a new immutable action with its own key per user, secret, or tenant. No PKP to mint.

> [card] [Signed Data in Untrusted Storage](https://docs.dev.litprotocol.com/lit-actions/signed-storage.md)
>
> Have an action sign the records you store. Consumers verify at runtime, so your database can never forge a permission.

> [card] [Patterns](https://docs.dev.litprotocol.com/lit-actions/patterns.md)
>
> Gating logic as code, hostname-pinned RPCs, multi-source consensus, action-identity signing, PKP vaults.

> [card] [Secrets](https://docs.dev.litprotocol.com/lit-actions/secrets.md)
>
> API keys and credentials inside actions: PKP vaults, encrypt-to-action, storage, rotation.

## The action runtime

Inside an action, the `Lit.Actions` namespace exposes the SDK. The most used functions:

| Function | Description |
| - | - |
| `return value` (from `main`) | Return a value to the caller. Preferred over `setResponse`. |
| `Lit.Actions.getPrivateKey({ pkpId })` | Retrieve a PKP private key for signing |
| `Lit.Actions.getLitActionPrivateKey()` | Retrieve this action's own identity key (0x-prefixed secp256k1 hex) |
| `Lit.Actions.getLitActionPublicKey({ ipfsId })` | Public key of any action by CID. No permission needed. |
| `Lit.Actions.getLitActionWalletAddress({ ipfsId })` | EVM address of any action by CID |
| `Lit.Actions.Encrypt({ pkpId, message })` | Encrypt a string with a PKP-derived AES key |
| `Lit.Actions.Decrypt({ pkpId, ciphertext })` | Decrypt with a PKP-derived AES key |

`ethers` v5 is a global. Third-party ESM packages can be [imported from jsDelivr](https://docs.dev.litprotocol.com/lit-actions/imports.md) with pinned versions. Key operations are limited to ten per execution and outbound `fetch` calls to fifty; see [Limits](https://docs.dev.litprotocol.com/lit-actions/limits.md).

Full reference: [Lit Actions SDK](https://docs.dev.litprotocol.com/lit-actions/chipotle.md).

## Next steps

To read this section in order, follow the sidebar: [Module Imports](https://docs.dev.litprotocol.com/lit-actions/imports.md), [WebAssembly](https://docs.dev.litprotocol.com/lit-actions/wasm.md), [Examples](https://docs.dev.litprotocol.com/lit-actions/examples.md), [Patterns](https://docs.dev.litprotocol.com/lit-actions/patterns.md), [Derived Actions](https://docs.dev.litprotocol.com/lit-actions/derived-actions.md), [Signed Data in Untrusted Storage](https://docs.dev.litprotocol.com/lit-actions/signed-storage.md), [Secrets](https://docs.dev.litprotocol.com/lit-actions/secrets.md), and [Limits](https://docs.dev.litprotocol.com/lit-actions/limits.md). These pages are also useful on their own:

* [Derived Actions](https://docs.dev.litprotocol.com/lit-actions/derived-actions.md) — per-user and per-secret immutable actions from one template
* [Signed Data in Untrusted Storage](https://docs.dev.litprotocol.com/lit-actions/signed-storage.md) — verifiable off-chain state for stateless actions
* [Examples](https://docs.dev.litprotocol.com/lit-actions/examples.md) — working code for common patterns and links to full runnable projects
* [Module Imports](https://docs.dev.litprotocol.com/lit-actions/imports.md) — third-party packages with integrity verification
* [Lit Actions SDK](https://docs.dev.litprotocol.com/lit-actions/chipotle.md) — full API reference
* [Migration from Naga](https://docs.dev.litprotocol.com/lit-actions/migration/changes.md) — mapping deprecated Naga actions to current equivalents


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.