Developers · v1.0

Build with LOCKRA.
Timelock in a few lines.

Add capsules that nobody can open before a date to any app, bot or dApp with lockra-sdk. Give AI agents the same power with lockra-mcp. Open source, zero servers, zero API keys, and every capsule opens on lockra.buzz.

prediction.js
import { seal, open } from 'lockra-sdk';

// Lock it until June 1st 2027
const capsule = await seal('BTC 150k by summer', {
  unlockAt: '2027-06-01T00:00:00Z',
  label: 'My call',
});

console.log(capsule.link);
// https://lockra.buzz/#l=My+call&c=...

const r = await open(capsule.link);
// before the date → { status: 'sealed', secondsLeft }
// after the date  → { status: 'opened', message }
0dependencies
35automated tests
100%compatible with lockra.buzz
MITopen source license
02

Install the SDK

View on npm
  1. 1

    Install it

    Requires Node.js 20 or newer, or any modern browser bundler (Vite, Next.js, webpack…). ESM only.

    terminal
    npm install lockra-sdk
  2. 2

    Import what you need

    Everything is a named export with full TypeScript types.

    js
    import { seal, open, inspect, sealFile, openFile } from 'lockra-sdk';
  3. 3

    No keys, no accounts

    There is nothing to configure. Encryption runs locally and the SDK only talks to the public drand relays when you open a capsule.

03

Seal & open

Seal a message
const capsule = await seal('I will ship v2 before March', {
  unlockAt: '2027-03-01T00:00:00Z', // or a Date, or epoch ms
  // unlockIn: 3600,                // …or seconds from now
  label: 'Promise',                 // public title, tamper-proof
  by: '@lockra',                    // public author, tamper-proof
});

capsule.link;     // share this
capsule.unlockAt; // Date
capsule.round;    // drand round that unlocks it
Open it
const r = await open(capsule.link); // a link, a token or the capsule object

if (r.status === 'sealed') {
  console.log(`Still sealed, ${r.secondsLeft}s left`);
} else {
  console.log(r.message, r.sealedAt);
}

// Or wait until it unlocks
const opened = await open(capsule.link, { wait: true, timeoutMs: 60_000 });
Read public details, offline
inspect(link);
// { round, unlockAt, unlocked, label, by, wallet }
OptionWhat it does
unlockAtUnlock time: a Date, an ISO 8601 string or epoch milliseconds.
unlockInOr: seconds from now. Pass exactly one of the two.
labelPublic title shown before opening, up to 80 characters.
byPublic author name, up to 40 characters.
waitOn open(): keep waiting until the capsule unlocks.

Messages can be up to 10,000 characters. The label and author are bound to the encryption: change one character and the capsule refuses to open.

04

Sealed files

up to 25 MB
Node.js
import { readFile, writeFile } from 'node:fs/promises';
import { sealFile, openFile } from 'lockra-sdk';

const { capsule, file } = await sealFile(await readFile('report.pdf'), {
  name: 'report.pdf',
  type: 'application/pdf',
  unlockAt: '2027-01-01T00:00:00Z',
});
await writeFile('report.pdf.lockra', file);

// Later
const r = await openFile(await readFile('report.pdf.lockra'));
if (r.status === 'opened') await writeFile(r.file.name, r.file.data);
Keep the .lockra file. It carries the encrypted bytes. Anyone can open it with the SDK or on lockra.buzz once the date arrives. The file name stays hidden until then.
05

Wallet signatures

Prove which wallet sealed a capsule. The SDK never touches private keys: sign the message with your own wallet library and attach the signature.

ethers · viem · wagmi
import { walletMessage, attachSignature } from 'lockra-sdk';

const signature = await signer.signMessage(walletMessage(capsule));
const signed = attachSignature(capsule, {
  address: await signer.getAddress(),
  signature,
});

signed.link; // shows "Wallet-signed by 0x…" on lockra.buzz
Never ask users for a seed phrase or private key. A normal message signature is all LOCKRA needs. No transaction, no gas.
06

Errors

Every error is a LockraError with a stable code, so you can handle each case cleanly.

CodeMeaning
INVALID_CAPSULENot a LOCKRA link, token or .lockra file.
INVALID_ARGUMENTA parameter is missing or out of range.
TAMPEREDThe capsule, its label, author or file was changed.
BAD_SIGNATUREA signature does not match this capsule.
BEACON_UNREACHABLENo drand relay could be reached. Retry later.
TIMEOUTopen({ wait: true }) gave up before the unlock.
js
import { open, LockraError } from 'lockra-sdk';

try {
  await open(link);
} catch (err) {
  if (err instanceof LockraError && err.code === 'TAMPERED') {
    console.warn('Someone edited this capsule.');
  }
}
07

MCP for AI agents

lockra-mcpView on npm

Connect LOCKRA to Claude, Cursor or any MCP client and just ask, in plain words:

"Seal my prediction that ETH flips 10k before June, unlock it on June 1st, and give me the link."
terminal
claude mcp add lockra -- npx -y lockra-mcp
seal_capsuleEncrypts a message until a date or for a number of seconds, and returns the link.
open_capsuleOpens a capsule, or says how long is left. Can wait up to 5 minutes.
inspect_capsuleShows the unlock time, label, author and wallet without opening it.

Requires Node.js 20+. Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

08

What to build

Provable callsPredictions that can't be edited after the fact. Perfect for KOLs, analysts and trading bots.
Commit-reveal gamesSealed bids, raffles, votes and guesses, with no trusted party holding the secret.
Timed dropsAnnouncements, alpha, keys, answers and puzzle solutions released on schedule.
Telegram & Discord bots/seal and /open commands for any community, in a few lines.
Agent memoryAI agents that commit to a decision now and prove it later.
Messages to the futureNotes, letters and voice messages for a future date inside any app.
09

How it works

Full specification
01 · Encrypt

The message is encrypted locally with a fresh AES-256-GCM key.

02 · Lock the key

The key is locked to a future drand round with identity-based encryption on BLS12-381.

03 · Wait

The key to open it doesn't exist yet. The League of Entropy publishes it at the scheduled time.

04 · Verify & open

The SDK checks the beacon signature against drand's public key, then decrypts.

  • Zero dependencies. The SDK bundles the audited noble cryptography, the same code that runs on lockra.buzz.
  • Untrusted relays. Every drand signature is verified before use, so no server can fake an unlock.
  • Signed builds. Packages are published from GitHub Actions with npm provenance, so anyone can check where they came from.
  • Links are the secret. After the unlock time, anyone with the link can read the capsule. Share accordingly.
10

FAQ

Does it cost anything or need $LOCKRA?

No. The SDK and the MCP server are free and open source. No wallet, no gas, no API key.

Does it run in the browser?

Yes. It uses the standard Web Crypto API, so it works in every modern browser and in Node.js 20+.

Can I open a capsule early if I sealed it?

No. Nobody can, including the author and LOCKRA. The key simply doesn't exist until the drand round is published.

What if drand is down when I open?

The SDK tries several public relays. If none answers you get BEACON_UNREACHABLE; retry later, the capsule stays valid forever.

Is it audited?

The cryptography libraries it uses (noble-curves and noble-hashes) are independently audited. The SDK itself is open source and covered by automated tests, including live tests against drand.

Where do I report a bug or a security issue?

Open an issue on GitHub. For security issues, DM @LockraRH privately first.

Ship something
nobody can open early.

Open source. Zero servers. Built on drand.

Star on GitHub