createLitClient

Functions

createLitClient({ network })

Parameters

param.network · NagaNetworkModule · required

The network to connect to.

import { nagaDev } from "@lit-protocol/networks";
const litClient = await createLitClient({ network: nagaDev });

Returns

litClient · object

Complete litClient object with all returned methods.

chain.raw.pkpSign

Signs arbitrary bytes with a PKP using the specified signing scheme on the chosen chain.

Parameters

params · object

Show properties

pubKey · string · required

0x‑prefixed PKP public key.

toSign · Uint8Array | ArrayLike<number> · required

Bytes to sign. If hashing is enabled, the hash of this payload is signed.

signingScheme · enum · required

Signing scheme to use.

Show allowed values

EcdsaK256Sha256 · string

ECDSA over secp256k1 with SHA‑256 prehash.

EcdsaP256Sha256 · string

ECDSA over P‑256 with SHA‑256 prehash.

EcdsaP384Sha384 · string

ECDSA over P‑384 with SHA‑384 prehash.

SchnorrEd25519Sha512 · string

Schnorr over Ed25519 with SHA‑512 prehash.

SchnorrK256Sha256 · string

Schnorr over secp256k1 with SHA‑256 prehash.

SchnorrP256Sha256 · string

Schnorr over P‑256 with SHA‑256 prehash.

SchnorrP384Sha384 · string

Schnorr over P‑384 with SHA‑384 prehash.

SchnorrRistretto25519Sha512 · string

Schnorr over Ristretto25519 with SHA‑512 prehash.

SchnorrEd448Shake256 · string

Schnorr over Ed448 with SHAKE‑256 prehash.

SchnorrRedJubjubBlake2b512 · string

Schnorr over Jubjub (red) with BLAKE2b‑512 prehash.

SchnorrK256Taproot · string

Schnorr over secp256k1 (Taproot) variant.

SchnorrRedDecaf377Blake2b512 · string

Schnorr over Decaf377 (red) with BLAKE2b‑512 prehash.

SchnorrkelSubstrate · string

Schnorrkel (Substrate) variant.

Show chain compatibility

ethereum · default

Defaults to EcdsaK256Sha256.

bitcoin · supported

Supports EcdsaK256Sha256, SchnorrK256Sha256, SchnorrK256Taproot.

chain · enum · required

Target chain; determines hashing (e.g. keccak256 for ethereum, sha256 for bitcoin).

Show allowed values

ethereum · string

Uses keccak256 prehashing when hashing is enabled.

bitcoin · string

Uses SHA‑256 prehashing when hashing is enabled.

cosmos · string

Reserved in schema.

solana · string

Reserved in schema.

authContext · AuthenticationContext · required

Authorisation/session context

userMaxPrice · bigint

Optional maximum price the user is willing to pay for this request.

bypassAutoHashing · boolean

Optional. Controls message pre‑hashing before signing.

Show behaviour

true · boolean

Do not transform toSign; the payload is signed as‑is. Use when you already computed the digest (e.g. EIP‑712 typed data, pre‑computed tx/message hash).

false (default) · boolean

Auto‑hash toSign according to signingScheme and chain via LitMessageSchema.

Show auto‑hash mapping (ECDSA)

ethereum.EcdsaK256Sha256 · keccak256

Hash function used before signing.

ethereum.EcdsaP256Sha256 · keccak256

Hash function used before signing.

ethereum.EcdsaP384Sha384 · keccak384

Hash function used before signing.

bitcoin.EcdsaK256Sha256 · sha256

Hash function used before signing.

bitcoin.EcdsaP256Sha256 · sha256

Hash function used before signing.

bitcoin.EcdsaP384Sha384 · sha384

Hash function used before signing.

Show auto‑hash mapping (FROST)

all FROST variants · none

No hashing is applied; toSign is signed as‑is.

Show notes

cosmos / solana · experimental

Auto‑hash mapping is not defined; avoid relying on auto‑hash with these chains.

EIP‑712 / typed data · guidance

Compute the EIP‑712 digest client‑side and set bypassAutoHashing=true to sign the digest directly.

Returns

result · LitNodeSignature Object

Show properties

signature · string

The final signature for the request.

verifyingKey · string

0x‑prefixed verifying (compressed) public key used to produce the signature.

signedData · string

0x‑prefixed hex of the exact payload that was signed (post‑hashing if applicable).

recoveryId · number | null

Recovery identifier when applicable to the scheme (0 or 1; may be null).

publicKey · string

0x‑prefixed PKP public key associated with the signature.

sigType · string

The signature type/scheme used

executeJs

Execute a Lit Action (JS) on the network.

Parameters

Request · object

Show properties

code · string

Inline JS code to run. Either code or ipfsId must be provided.

ipfsId · string

IPFS CID of a Lit Action to run. Either code or ipfsId must be provided.

jsParams · any | { publicKey?: string; sigName?: string; ... }

Parameters injected into the Lit Action runtime before execution.

authContext · AuthenticationContext · required

Authorisation/session context for node authorisation.

userMaxPrice · bigint

Optional maximum price the user is willing to pay.

Returns

result · ExecuteJsResponse Object

Show properties

success · boolean

response · string | object

The action-defined response payload.

logs · string

Aggregated logs from nodes.

signatures · object | any

Signature map when action performs signing.

claims · record

Optional claim results when present.

debug · object

Optional debug info (allNodeResponses, allNodeLogs, rawNodeHTTPResponses).

encrypt

Encrypt data with access control conditions using BLS.

Parameters

Request · object

Show properties

dataToEncrypt · string | object | any[] | Uint8Array · required

The data to encrypt. Strings/objects/arrays are internally converted to bytes. Objects/arrays are JSON-stringified first.

chain · string · required

Target chain context for condition evaluation.

accessControlConditions · ACC[]

Standard access control conditions (ACC). Provide one of ACC, evmContractConditions, solRpcConditions, or unifiedAccessControlConditions.

evmContractConditions · EVM ACC[]

EVM-specific contract conditions (mutually exclusive with other condition types).

solRpcConditions · Solana ACC[]

Solana RPC conditions (mutually exclusive with other condition types).

unifiedAccessControlConditions · Unified ACC[]

Unified access control conditions (mutually exclusive with other condition types).

metadata · object

Optional metadata to describe the data being encrypted.

Show properties

dataType · 'uint8array' | 'string' | 'json' | 'buffer' | 'image' | 'video' | 'file'

Expected data type for downstream conversion on decrypt.

mimeType · string

MIME type for file-like data.

filename · string

Original filename for file-like data.

size · number

File size in bytes.

custom · record

Arbitrary custom metadata.

Returns

result · EncryptResponse Object

Show properties

ciphertext · string

Base64-encoded ciphertext.

dataToEncryptHash · string

SHA-256 hash (hex) of the plaintext data.

metadata · object

Echo of provided metadata or inferred data type where applicable.

decrypt

Decrypt data previously encrypted with access control conditions.

Parameters

Request · object

Show properties

data · EncryptResponse

Optional. Pass the full encrypted object from encrypt(). If omitted, provide fields below individually.

ciphertext · string

Base64-encoded ciphertext (required if data is not provided).

dataToEncryptHash · string

SHA-256 hash (hex) of the original plaintext (required if data is not provided).

accessControlConditions · ACC[]

One of ACC, evmContractConditions, solRpcConditions, or unifiedAccessControlConditions (must match encryption).

evmContractConditions · EVM ACC[]

solRpcConditions · Solana ACC[]

unifiedAccessControlConditions · Unified ACC[]

chain · string

Target chain context for condition evaluation.

authContext · AuthenticationContext

Authorisation/session context for node authorisation.

userMaxPrice · bigint

Optional maximum price the user is willing to pay for this request.

Returns

result · DecryptResponse Object

Show properties

decryptedData · Uint8Array

The raw decrypted bytes.

convertedData · string | object | Buffer | Blob | File

Present when metadata.dataType was provided and conversion is applicable.

metadata · object

Metadata echo including dataType and optional file info.

mintWithEoa

Mint a PKP using an EOA.

Parameters

Request · object

Show properties

account · Account | WalletClient | Signer · required

The signing account that will perform the mint on-chain.

Returns

result · AuthServerTx<PKPData>

Show properties

txHash · string

Transaction hash of the mint.

data · PKPData Object

Show properties

tokenId · bigint

PKP token ID.

pubkey · string

0x-hex uncompressed public key.

ethAddress · string

Derived 0x-hex Ethereum address.

mintWithAuth

Mint a PKP using an authentication method.

Parameters

Request · object

Show properties

account · Account | WalletClient | Signer · required

The signing account that will perform the mint on-chain.

authData · AuthData · required

Auth method payload (e.g., from ViemAccountAuthenticator): includes authMethodType, authMethodId, optional accessToken.

scopes · string[] | number[] · required

Permission scopes to attach to the minted PKP.

Returns

result · AuthServerTx<PKPData>

Show properties

txHash · string

data · PKPData

mintWithCustomAuth

Mint a PKP using custom authentication (Lit Action validator or IPFS CID).

Parameters

Request · object

Show properties

account · Account | WalletClient | Signer · required

The signing account for on-chain operations.

authData · AuthData (without accessToken) · required

Authentication method details used alongside the validation Lit Action.

validationIpfsCid · string · required

Lit Action IPFS CID (must start with “Qm” and be ≥ 46 chars).

scope · 'no-permissions' | 'sign-anything' | 'personal-sign' · required

Initial permission scope to grant.

addPkpEthAddressAsPermittedAddress · boolean · default: "false"

If true, add the PKP’s own address as a permitted address.

sendPkpToItself · boolean · default: "true"

If true, transfers the PKP to itself after minting.

Returns

result · object

Show properties

validationIpfsCid · string

Echo of the provided Lit Action CID.

pkpData · PKPData | any

Mint result and PKP details from the chain API.

authService.mintWithAuth

Mint a PKP via the Auth Service. Parameters and returns mirror mintWithAuth.

Parameters

Request · object

Show properties

account · Account | WalletClient | Signer

authData · AuthData

scopes · string[] | number[]

authServiceBaseUrl · string

Optional. Override the Auth Service base URL; defaults to the network’s configured value.

Returns

result · AuthServerTx<PKPData>

getPKPPermissionsManager

Create a PKP permissions manager instance.

Parameters

Request · object

Hide properties

pkpIdentifier · object · required

PKP identifier. Exactly one of the following must be provided.

Show one of

tokenId · string

PKP token ID (stringified bigint).

pubkey · string

0x‑prefixed uncompressed PKP public key.

address · string

0x‑prefixed PKP Ethereum address.

account · Account | WalletClient | Signer · required

Account used for permission transactions and reads.

Returns

result · PKPPermissionsManager Object

Hide properties

addPermittedAction(params) · Promise<LitTxVoid>

Add a permitted Lit Action.

Show params

ipfsId · string · required

Lit Action IPFS CID.

scopes · ScopeString[] · required

Permission scopes (e.g., ‘sign-anything’).

Show example

await manager.addPermittedAction({ ipfsId: "Qm...", scopes: ["sign-anything"] });

addPermittedAddress(params) · Promise<LitTxVoid>

Add a permitted address.

Show params

address · string · required

0x‑prefixed address to permit.

scopes · ScopeString[] · required

Permission scopes.

Show example

await manager.addPermittedAddress({ address: "0xUser...", scopes: ["sign-anything"] });

addPermittedAuthMethod(params) · Promise<LitTxVoid>

Permit an authentication method.

Show params

authMethodType · string | number | bigint · required

authMethodId · string · required

userPubkey · string · required

scopes · ScopeString[] · required

Show example

await manager.addPermittedAuthMethod({ authMethodType: 1, authMethodId: "0x...", userPubkey: "0x...", scopes: ["sign-anything"] });

addPermittedAuthMethodScope(params) · Promise<LitTxVoid>

Permit a scope for an auth method.

Show params

authMethodType · string | number | bigint · required

authMethodId · string · required

scopeId · string | number | bigint · required

Show example

await manager.addPermittedAuthMethodScope({ authMethodType: 1, authMethodId: "0x...", scopeId: 0 });

removePermittedAction(params) · Promise<LitTxVoid>

Show params

ipfsId · string · required

Show example

await manager.removePermittedAction({ ipfsId: "Qm..." });

removePermittedAddress(params) · Promise<LitTxVoid>

Show params

address · string · required

Show example

await manager.removePermittedAddress({ address: "0xUser..." });

removePermittedAuthMethod(params) · Promise<LitTxVoid>

Show params

authMethodType · string | number | bigint · required

authMethodId · string · required

Show example

await manager.removePermittedAuthMethod({ authMethodType: 1, authMethodId: "0x..." });

removePermittedAuthMethodScope(params) · Promise<LitTxVoid>

Show params

authMethodType · string | number | bigint · required

authMethodId · string · required

scopeId · string | number | bigint · required

Show example

await manager.removePermittedAuthMethodScope({ authMethodType: 1, authMethodId: "0x...", scopeId: 0 });

isPermittedAction(params) · Promise<boolean>

Show params

ipfsId · string · required

Show example

const ok = await manager.isPermittedAction({ ipfsId: "Qm..." });

isPermittedAddress(params) · Promise<boolean>

Show params

address · string · required

Show example

const ok = await manager.isPermittedAddress({ address: "0xUser..." });

getPermittedActions() · Promise<readonly 0x-hex[]>

getPermittedAddresses() · Promise<readonly 0x-hex[]>

getPermittedAuthMethods() · Promise<readonly AuthMethod[]>

getPermittedAuthMethodScopes(params) · Promise<readonly boolean[]>

Show params

authMethodType · number · required

authMethodId · string · required

scopeId · number

getPermissionsContext() · Promise<PermissionsContext>

Returns consolidated permissions (actions, addresses, authMethods).

batchUpdatePermissions(operations) · Promise<void>

Batch perform add/remove operations.

Show operations (array of)

{ type: 'addAction'; ipfsId; scopes } · object

{ type: 'addAddress'; address; scopes } · object

{ type: 'addAuthMethod'; authMethodType; authMethodId; userPubkey; scopes } · object

{ type: 'addAuthMethodScope'; authMethodType; authMethodId; scopeId } · object

{ type: 'removeAction'; ipfsId } · object

{ type: 'removeAddress'; address } · object

{ type: 'removeAuthMethod'; authMethodType; authMethodId } · object

{ type: 'removeAuthMethodScope'; authMethodType; authMethodId; scopeId } · object

Show example

await manager.batchUpdatePermissions([
  { type: 'addAddress', address: '0xUser...', scopes: ['sign-anything'] },
  { type: 'addAction', ipfsId: 'Qm...', scopes: ['sign-anything'] },
]);

revokeAllPermissions() · Promise<void>

Remove all addresses, auth methods, and known test actions.

getPaymentManager

Get a Payment Manager for Ledger contract operations.

Parameters

Request · object

Show properties

account · Account | WalletClient | Signer · required

The account used for deposits, withdrawals, and queries.

Returns

result · PaymentManager Object

Hide properties

deposit(params) · Promise<LitTxVoid>

Deposit funds to your own account.

Show params

amountInEth · string · required

Amount to deposit in ETH (string), internally converted to Wei.

Show example

await paymentManager.deposit({ amountInEth: "0.1" });

depositForUser(params) · Promise<LitTxVoid>

Deposit funds for another user.

Show params

userAddress · string · required

amountInEth · string · required

Show example

await paymentManager.depositForUser({ userAddress: "0x...", amountInEth: "0.25" });

getBalance(params) · Promise<PaymentBalance>

Get total and available balances for a user.

Show params

userAddress · string · required

Show example

const bal = await paymentManager.getBalance({ userAddress: "0x..." });
console.log(bal.totalBalance, bal.availableBalance);

requestWithdraw(params) · Promise<LitTxVoid>

Request withdrawal (starts delay period).

Show params

amountInEth · string · required

Show example

await paymentManager.requestWithdraw({ amountInEth: "0.05" });

withdraw(params) · Promise<LitTxVoid>

Execute withdrawal after delay.

Show params

amountInEth · string · required

Show example

await paymentManager.withdraw({ amountInEth: "0.05" });

getWithdrawRequest(params) · Promise<WithdrawRequestInfo>

Get current withdrawal request for a user.

Show params

userAddress · string · required

Show example

const info = await paymentManager.getWithdrawRequest({ userAddress: "0x..." });

getWithdrawDelay() · Promise<{ delaySeconds: string; raw: bigint }>

Get global withdrawal delay in seconds.

Show example

const delay = await paymentManager.getWithdrawDelay();

canExecuteWithdraw(params) · Promise<{ canExecute: boolean; timeRemaining?: number; withdrawRequest: WithdrawRequestInfo }>

Check whether a user’s withdrawal can be executed now.

Show params

userAddress · string · required

Show example

const { canExecute, timeRemaining } = await paymentManager.canExecuteWithdraw({ userAddress: "0x..." });

delegatePayments(params) · Promise<LitTxVoid>

Delegate payments to a user.

Show params

userAddress · string · required

Show example

await paymentManager.delegatePayments({ userAddress: "0xUser..." });

undelegatePayments(params) · Promise<LitTxVoid>

Undelegate payments from a user.

Show params

userAddress · string · required

Show example

await paymentManager.undelegatePayments({ userAddress: "0xUser..." });

delegatePaymentsBatch(params) · Promise<LitTxVoid>

Delegate payments to multiple users.

Show params

userAddresses · string[] · required

Show example

await paymentManager.delegatePaymentsBatch({ userAddresses: ["0xA...","0xB..."] });

undelegatePaymentsBatch(params) · Promise<LitTxVoid>

Undelegate payments from multiple users.

Show params

userAddresses · string[] · required

Show example

await paymentManager.undelegatePaymentsBatch({ userAddresses: ["0xA...","0xB..."] });

setRestriction(params) · Promise<LitTxVoid>

Set payment restriction for caller.

Show params

totalMaxPrice · string · required

requestsPerPeriod · string · required

periodSeconds · string · required

Show example

await paymentManager.setRestriction({ totalMaxPrice: "1000000000000000000", requestsPerPeriod: "100", periodSeconds: "86400" });

getPayers(params) · Promise<string[]>

List payers for a user.

Show params

userAddress · string · required

Show example

const payers = await paymentManager.getPayers({ userAddress: "0xUser..." });

getUsers(params) · Promise<string[]>

List users for a payer.

Show params

payerAddress · string · required

Show example

const users = await paymentManager.getUsers({ payerAddress: "0xPayer..." });

getRestriction(params) · Promise<{ totalMaxPrice: string; requestsPerPeriod: string; periodSeconds: string; raw: Restriction }>

Get restriction for a payer.

Show params

payerAddress · string · required

Show example

const r = await paymentManager.getRestriction({ payerAddress: "0xPayer..." });

getPayersAndRestrictions(params) · Promise<{ payers: string[][]; restrictions: { totalMaxPrice: string; requestsPerPeriod: string; periodSeconds: string; }[][]; raw: { payers: string[][]; restrictions: Restriction[][] } }>

Batch get payers and restrictions for users.

Show params

userAddresses · string[] · required

Show example

const res = await paymentManager.getPayersAndRestrictions({ userAddresses: ["0xA...","0xB..."] });

viewPKPPermissions

View current permissions context for a PKP.

Parameters

pkpIdentifier · { tokenId?: string; pubkey?: string; address?: string } · required

Returns

result · object

Show properties

actions · readonly 0x-hex[]

addresses · readonly 0x-hex[]

authMethods · readonly object[]

viewPKPsByAddress

List PKPs owned by an address.

Parameters

Request · object

Show properties

ownerAddress · string · required

Address whose PKPs to fetch.

pagination · { limit?: number; offset?: number }

storageProvider · PKPStorageProvider

Returns

result · PaginatedPKPsResponse

Show properties

pkps · PKPInfo[]

pagination · { limit: number; offset: number; total: number; hasMore: boolean }

getPkpViemAccount

Create a Viem-compatible account backed by a PKP.

Parameters

Request · object

Show properties

pkpPublicKey · string | Hex · required

0x-prefixed PKP public key.

authContext · AuthenticationContext · required

Authorisation context used for signing sessions.

chainConfig · Chain · required

Viem chain configuration used by the returned account.

Returns

result · Viem Account Object

Show properties

signMessage / signTypedData / sendTransaction · functions

Standard Viem account methods that route to PKP signing under the hood.

Returns

result · LitNodeSignature Object

Show properties

signature · string

The final signature for the request.

verifyingKey · string

0x‑prefixed verifying (compressed) public key used to produce the signature.

signedData · string

0x‑prefixed hex of the exact payload that was signed (post‑hashing if applicable).

recoveryId · number | null

Recovery identifier when applicable to the scheme (0 or 1; may be null).

publicKey · string

0x‑prefixed PKP public key associated with the signature.

sigType · string

The signature type/scheme used (e.g. ECDSA, Schnorr).

utils.getDerivedKeyId

Resolve the uncompressed PKP public key for a given derived key identifier.

Parameters

derivedKeyId · string · required

0x-prefixed bytes32 identifier (for example, keccak256(stringToBytes(lit_action_${ipfsCid}))).

Returns

result · Promise<string>

0x-prefixed uncompressed public key as returned by the PubkeyRouter contract.

Example

import { keccak256, stringToBytes } from "viem";

const derivedKeyId = keccak256(stringToBytes(`lit_action_${ipfsCid}`));
const derivedPubkey = await litClient.utils.getDerivedKeyId(derivedKeyId);

Note: this helper currently calls PubkeyRouter.getDerivedPubkey with the default Naga key set (naga-keyset1). See the Derive Lit Action Public Keys guide for an end-to-end workflow.

getChainConfig

Returns the chain configuration for the current network.

Parameters

none

Returns

result · ChainConfig

Show properties

viemConfig · Chain

Viem chain configuration used by the returned account.

rpcUrl · string

RPC URL for the chain.

disconnect

Stop background state updates and release resources.

Parameters

none

Returns

void