How to add wallets to your app with an API

On Lit Protocol you can add a wallet to your app with six REST calls and no SDK. You create a wallet, create a group, write a signing rule, connect them, make an API key for your server, and sign. The key is created and stored inside a secure enclave. The rule that decides when it signs is a JavaScript function that runs in the same enclave. The record of which rules can use which wallets is stored on Base.

I will walk through the six calls, and then say a little about when Lit is the right choice and when it is not.

The six calls

Go to the Lit dashboard and click New to Lit? Create an account. Choose API key, fill in your email and an account name, and copy the account API key it gives you. The base URL for everything below is https://api.chipotle.litprotocol.com/core/v1.

First, create a wallet. You get back an address.

curl -s -X POST "$LIT/create_wallet" -H "X-Api-Key: $ACCOUNT_KEY"
# {"wallet_address":"0x..."}

Second, create a group. A group is how Lit connects wallets, rules, and API keys.

curl -s -X POST "$LIT/add_group" -H "X-Api-Key: $ACCOUNT_KEY" -H "Content-Type: application/json" \
  -d '{"group_name":"payouts","group_description":"","pkp_ids_permitted":[],"cid_hashes_permitted":[]}'
# {"success":true,"group_id":"1"}

Third, write the signing rule. This is a Lit Action. This one checks an allowlist service before it signs.

// rule.js
async function main({ pkpId, to, valueWei }) {
  const allow = await fetch(`https://policy.example.com/allow?to=${to}`).then(r => r.json());
  if (!allow.ok) return { signed: false, reason: allow.reason };
  const wallet = new ethers.Wallet(await Lit.Actions.getPrivateKey({ pkpId }));
  return { signed: true, tx: await wallet.signTransaction({ to, value: valueWei, chainId: 8453 }) };
}

Lit identifies the rule by the IPFS hash of its code. You do not have to upload it anywhere. You can compute the hash yourself, or send the code to the get_lit_action_ipfs_id endpoint and it will return the hash.

Fourth, add the rule and the wallet to the group.

curl -s -X POST "$LIT/add_action_to_group" -H "X-Api-Key: $ACCOUNT_KEY" -H "Content-Type: application/json" \
  -d '{"group_id":1,"action_ipfs_cid":"Qm..."}'
curl -s -X POST "$LIT/add_pkp_to_group" -H "X-Api-Key: $ACCOUNT_KEY" -H "Content-Type: application/json" \
  -d '{"group_id":1,"pkp_id":"<pkp id>"}'

Fifth, make an API key for your server. This key can only execute rules in group 1.

curl -s -X POST "$LIT/add_usage_api_key" -H "X-Api-Key: $ACCOUNT_KEY" -H "Content-Type: application/json" \
  -d '{"name":"payout-service","description":"","can_create_groups":false,"can_delete_groups":false,"can_create_pkps":false,
       "manage_ipfs_ids_in_groups":[],"add_pkp_to_groups":[],"remove_pkp_from_groups":[],"execute_in_groups":[1]}'
# {"usage_api_key":"..."}

Sixth, sign.

jq -n --rawfile code rule.js '{code: $code, js_params: {pkpId: "<pkp id>", to: "0xabc...", valueWei: "1000000000000000"}}' \
  | curl -s -X POST "$LIT/lit_action" -H "X-Api-Key: $USAGE_KEY" -H "Content-Type: application/json" -d @-

The enclave hashes the code, checks that your key is allowed to run it against that wallet, runs it, and returns the signed transaction. If you would rather not write curl, there is a JavaScript client that wraps these same calls, and we publish an OpenAPI spec if you want to generate your own.

Owning the permissions yourself

By default, Lit holds the account credential and relays your changes. If you switch to ChainSecured mode, a wallet you control owns the account on Base. It can be a regular wallet or a Safe. After that, every change to a group is a transaction you sign, and anyone can read the current permissions from the contract. Your server's key can still run rules. It cannot change them.

When Lit is not the right tool

If you need a login flow and a fiat onramp in one SDK, you want an embedded wallet product. If you have a custody obligation and a treasury team, you want a custody platform. Lit is for wallets that your application controls, like hot wallets, vaults, payout services, solvers, and agents. It fits when the signing rule needs real data and when someone outside your company should be able to read what the rule is.

Get started

To create an account, go to the Lit dashboard and click New to Lit? Create an account. The quickstart is at developer.litprotocol.com/quickstart.

This is part 4 of a five-part series on building with Lit. Part 5 comes out on Wednesday, October 7, and is about verifying the code that signs your transactions.