Skip to main content


The Paywall is a simple JavaScript library which can track state and emits events based on ownership of keys to specified locks. It can be used to display a Checkout for purchasing keys.

The Paywall is available on npm as @unlock-protocol/paywall. Its README contains usage examples.


The Paywall shares a configuration object with the Checkout and you can find everything you need to know in Checkout / Configuration about how to build out the JSON object you're going use.

Loading from a CDN

You can also easily add it to any webpage with the following:

(function(d, s) {
var js = d.createElement(s),
sc = d.getElementsByTagName(s)[0];
sc.parentNode.insertBefore(js, sc); }(document, "script"));

Then assign a configiration to a global variable unlockProtocolConfig to configure it:

var unlockProtocolConfig =
// paywallConfig object


When loaded asOnce loaded the script will trigger events on the page’s ​window​ object.

Registering event listeners.

window.addEventListener('unlockProtocol.eventName', handler)


event unlockProtocol.status

Triggered when unlockProtocol status changes.


Handler event object properties.

stateRepresenting whether or not the connected wallet has a valid key.locked or unlocked string

User info

event unlockProtocol.authenticated

Triggered when a user authenticates.

addressEthereum address of the connected userstring
signedMessagethe signature perform by the user if your configuration includes a messageToSignoptionstring

Note: if the event is triggered without any payload, please consider that the user has "logged out".

Transaction status

event unlockProtocol.transactionSent

hashthe Ethereum transactionstring
lockthe Ethereum address of the lockstring

User metadata

event unlockProtocol.metadata

Sent collected metadata about all the recipients. This is triggered on confirmation of the transaction.

Pessimistic Unlocking

One of the features of the paywall application is that it optimistically unlocks the page. This feature improves the customer experience by immediately emitting the unlocked event when a transaction is sent, as long as the transaction is likely enough to eventually succeed.

In some cases, your application may want to not unlock until the transaction is fully confirmed. For this you should add pessimistic: true to the paywall configuration.

When doing this, you should ensure that your application handles the events such as unlockProtocol.authenticated and unlockProtocol.transactionSent to show valuable feedback to the user. See the "Events" section on this page.