Overview

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 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.

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	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”. The identity key also unlocks a factory: stamp a small config constant into an audited template and each instance is a new immutable action with a new key. See Derived Actions.

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.

Trustless data ingestion. The action fetches and signs; the contract verifies.
Verifiable computation. The signature is tied either to a PKP you registered or to the exact CID that ran.
No trusted intermediary. 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.

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, are actually built from.

Derived Actions

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.

Signed Data in Untrusted Storage

Have an action sign the records you store. Consumers verify at runtime, so your database can never forge a permission.

Patterns

Gating logic as code, hostname-pinned RPCs, multi-source consensus, action-identity signing, PKP vaults.

Secrets

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 with pinned versions. Key operations are limited to ten per execution and outbound fetch calls to fifty; see Limits. Full reference: Lit Actions SDK.

A minimal example

// 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.

Next steps

Derived Actions — per-user and per-secret immutable actions from one template
Signed Data in Untrusted Storage — verifiable off-chain state for stateless actions
Examples — working code for common patterns and links to full runnable projects
Module Imports — third-party packages with integrity verification
Lit Actions SDK — full API reference
Migration from Naga — mapping deprecated Naga actions to current equivalents

Management

Lit Actions

Lit Triggers

Architecture

Actions Reference

What is a Lit Action?

Two kinds of keys

What is a proof?

How actions fit into Chipotle

Patterns that make Chipotle easier

Derived Actions

Signed Data in Untrusted Storage

Patterns

Secrets

The action runtime

A minimal example

Next steps

​What is a Lit Action?

​Two kinds of keys

​What is a proof?

​How actions fit into Chipotle

​Patterns that make Chipotle easier

Derived Actions

Signed Data in Untrusted Storage

Patterns

Secrets

​The action runtime

​A minimal example

​Next steps

What is a Lit Action?

Two kinds of keys

What is a proof?

How actions fit into Chipotle

Patterns that make Chipotle easier

The action runtime

A minimal example

Next steps