API Mode vs ChainSecured Mode

Documentation Index

Fetch the complete documentation index at: https://developer.litprotocol.com/llms.txt

Use this file to discover all available pages before exploring further.

• API mode (managed) — POST /core/v1/new_account generates a fresh random secret server-side and returns it once as a base64 API key, along with the wallet address derived from that secret. You hold the key; that key is the account credential. Admin writes are sent as HTTP calls and the server submits the on-chain transaction on your behalf.
• ChainSecured mode (unmanaged) — A wallet you control (an EOA, a Safe, or any contract account on Base) is the account owner directly on-chain. Admin writes are wallet-signed transactions you submit yourself. There is no account-level API key.

​

Side-by-side

​

When to pick which

​

Pick API mode if:

• You want to ship today and don’t want to manage gas, an RPC, or a wallet popup in your admin tooling.
• Your client is a server, a cron job, or a CI pipeline that needs a single shared credential.
• You’re prototyping or iterating quickly — onboarding is fast, usage API keys are rotatable (mint and revoke at will), and the dashboard reflects every change immediately.
• You don’t have a strong requirement that every configuration change be visible on-chain.

​

Pick ChainSecured mode if:

• You want self-custody of the account: no third party (including Lit) can unilaterally create groups, add actions, or mint usage keys on your behalf.
• A multisig (Safe) or DAO governs configuration changes — every action upgrade, every PKP added to a group, becomes a Safe proposal that signers can review.
• You want a fully on-chain audit trail of every admin operation, signed by your governance wallet.
• You’re integrating with a wallet-native dApp where the user’s connected wallet is already the natural source of authority.

​

How the wiring differs

​

API mode (mode: 'api', default)

import { createClient } from './core_sdk.js';

const client = createClient('https://api.chipotle.litprotocol.com');

const res = await client.newAccount({
  accountName: 'My App',
  accountDescription: 'Optional',
  email: 'optional@example.com',
});
console.log('API key:', res.api_key);          // store this
console.log('Wallet:', res.wallet_address);

​

ChainSecured mode (mode: 'sovereign')

import { LitNodeSimpleApiClient } from './core_sdk.js';
import { ethers } from 'ethers';

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const client = new LitNodeSimpleApiClient({
  baseUrl: 'https://api.chipotle.litprotocol.com',
  mode: 'sovereign',
  rpcUrl: 'https://mainnet.base.org',
  contractAddress: '0xYourAccountConfigDiamond',
  signer,
});

// Creates an unmanaged account whose admin is the connected wallet.
const res = await client.newChainSecuredAccount({
  accountName: 'My App',
  accountDescription: 'Optional',
});
console.log('Admin wallet:', res.wallet_address);
console.log('Tx hash:', res.transaction_hash);

client.connectSigner(signer);
const apiKeyHash = ethers.solidityPackedKeccak256(
  ['address'],
  [await signer.getAddress()],
);
const exists = await client.accountExistsByHash(apiKeyHash);

​

Using the dashboard

• Sign in tab → “API mode” card (paste your API key) or “ChainSecured mode” card (Connect wallet).
• Create account tab → “API mode” card (email + name) or “ChainSecured mode” card (Connect wallet & create).

​

Converting an API account to ChainSecured

​

What’s preserved

• The on-chain apiKeyHash (so all child resources stay attached).
• Groups (permitted PKP IDs and CID hashes).
• PKPs (derivation paths, names, descriptions).
• Action metadata (registered IPFS CID names and descriptions).
• Usage API keys — they continue to authorize Lit Action execution exactly as before.
• Stripe credit balance — the wallet_cache entry is invalidated on conversion so billing routes to the new admin wallet’s customer record immediately.

​

What changes

• account.adminWalletAddress becomes the new wallet you signed with.
• account.managed flips from true to false.
• Admin write authority moves entirely to the connected wallet. The original master API key can no longer authorize writes on this account (the contract rejects api_payer relays for unmanaged accounts).
• Read endpoints that key off apiKeyHash continue to resolve to the same account.

​

Step-by-step (dashboard)

1. Sign in to the dashboard in API mode with your existing master API key.
2. Open the account dropdown and click Convert to ChainSecured. Confirm the irreversible-action prompt.
3. Connect the wallet that will become the new admin. EOA only — the server verifies the EIP-712 signature via plain ECDSA recover() and does not yet validate ERC-1271 contract-account signatures, so Safes and other contract wallets are not supported in this flow today. The dashboard prompts a chain switch if your wallet isn’t on the chain reported by GET /get_node_chain_config.
4. Sign the EIP-712 ownership-transfer typed data. The dashboard composes a typed-data envelope with primaryType: "ConvertAccount" — wallet UIs surface it as a labelled struct (address, issuedAt) under the Lit ChainSecured domain rather than a free-form message. The full canonical envelope is:
   {
     "types": {
       "EIP712Domain": [
         { "name": "name",    "type": "string"  },
         { "name": "version", "type": "string"  },
         { "name": "chainId", "type": "uint256" }
       ],
       "ConvertAccount": [
         { "name": "address",  "type": "address" },
         { "name": "issuedAt", "type": "uint256" }
       ]
     },
     "primaryType": "ConvertAccount",
     "domain":  { "name": "Lit ChainSecured", "version": "1", "chainId": "<chain id>" },
     "message": { "address":  "<new admin address>", "issuedAt": "<unix seconds>" }
   }
   
   types is part of the EIP-712 type hash and the server schema validator rejects payloads where it differs by even one field — field declaration order matters. Your wallet produces an EIP-712 signature (eth_signTypedData_v4).
5. The dashboard POSTs /core/v1/convert_to_chain_secured_account with { new_admin_wallet_address, typed_data, signature } and your existing API key in the header. The server verifies the typed-data digest recovers to the new admin address, the chainId matches the node, the primaryType matches ConvertAccount (preventing cross-flow replay against the secret-emitting endpoints), and the issuedAt timestamp is within ±300 seconds, then has the api_payer submit the on-chain conversion.
6. On success, the dashboard switches mode to sovereign, clears the stored API key, persists the wallet + preserved apiKeyHash to the ChainSecured session, and reloads.

​

Step-by-step (SDK)

import { createClient } from './core_sdk.js';
import { ethers } from 'ethers';

// Sign in with API mode (default) and your existing master API key.
const client = createClient('https://api.chipotle.litprotocol.com');

// Connect the wallet that will become the new on-chain admin.
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Look up the chain id the server expects so the EIP-712 domain matches.
const cfg = await client.getNodeChainConfig();

const res = await client.convertToChainSecuredAccount({
  apiKey: existingApiKey,
  signer,
  chainId: Number(cfg.chain_id),
});
console.log('New admin wallet:', res.wallet_address);
console.log('Preserved apiKeyHash:', res.api_key_hash);

​

Things to verify after conversion

• accountExistsByHash(api_key_hash) returns true from the wallet context, where api_key_hash is the value returned by convertToChainSecuredAccount (the preserved on-chain hash).
• An admin write attempted with the original API key (e.g. addUsageApiKey) fails — the contract rejects it now that the account is unmanaged.
• An admin write signed by the new wallet succeeds.
• All groups, PKPs, action CIDs, and existing usage API keys are visible in the dashboard under the new wallet session, and a Lit Action run with one of those usage keys still succeeds.
• The Stripe credit balance is unchanged.

​

Reverse direction

​

Further reading

• Auth Model — owner / API key / scope model in detail.
• Architecture diagram — how the TEE, contracts, and dashboard fit together.
• Using the API directly — endpoint-by-endpoint reference (API mode).
• Pricing — credit model, identical in both modes.