Picket Docs
Search…
Javascript Library - picket-js
Getting started with picket-js

Installation

npm install --save "@picketapi/picket-js"

Usage - Quick Start

The Picket constructor creates a new instance of the Picket class. It takes a publishable API key as a parameter.
import Picket from "@picketapi/picket-js";
const picket = new Picket("YOUR_PUBLISHABLE_KEY_HERE");
We’ve placed a placeholder publishable API key in this example. Replace it with your actual publishable API key.
import Picket from "@picketapi/picket-js";
const picket = new Picket("YOUR_PUBLISHABLE_KEY_HERE");
​
const { accessToken, user } = await picket.login();
login optionally takes in token ownership requirements parameter. You can use this if you only want to allow users to login if they have a specific token, commonly referred to as token gating.

Login

login is the easiest way to use Picket with your web, mobile, or native application. This enables you to securely login users via their wallet with a single line of code.

Wallet Authentication

Ethereum (Mainnet)
Solana
// default chain is Ethereum
await picket.login();
// or specifiy it explicitly
await picket.login({ chain: "ethereum" });
await picket.login({ chain: "solana" });

Token Gating

EVM-Compatible Chains
Solana
await picket.login({
// any supported EVM-compatible chain
// if omitted, defaults to "ethereum"
chain: "ethereum",
// restrict access to token holders
contractAddress: "0xCONTRACT_ADDRESS",
// omit if any number of tokens are acceptable
minTokenBalance: 1
});
await picket.login({
chain: "solana",
// Replace this the tokens you want to verify ownership for
// the token ID is the mint associated with a SPL token
// user needs to own the minTokenBalance of at least one of the listed token
tokenIds: ["78AZe2223PknLYT9mn2VCJPAsdvuB6LzFAhgQeVoxddW", "2dQG4YYunFrbJjzW6UTcUmePs8UDy5jz43H6uSCZSAcS"],
// Replace with minimum balance you want to verify users' currently hold across all token IDs,
// or omit if any number of tokens is sufficient
minTokenBalance: 1
});

Logout

logout deletes the cached user's access token.
await picket.logout();

AuthState

authState returns the user's current authorization state.
If the user is logged in, this includes the user's accessToken and information. If the user is logged out, the authState will be null.
// assumes user is logged in
const { accessToken, user } = await picket.authState();

Connect

connect is a convenience function for connecting to a wallet provider.
Ethereum
Solana
// Ethereum is the default chain
const { walletAddress, signature, provider } = await picket.connect();
// it can also be passed in explicitly
const { walletAddress, signature, provider } = await picket.connect({ chain: "ethereum" });
const { walletAddress, signature, provider } = await picket.connect({ chain: "solana" });
Under the hood, Picket use Web3Modal to prompt users with a selection of wallet providers for EVM chains and Phantom wallet for Solana chains.

Signature Message Format

connect supports two different message formats
  1. 1.
    Simple
  2. 2.
    Sign-In with Ethereum (abbreviated SIWE)
Simple is the default message format. To change the message format to SIWE, you can use the messageFormat parameter.
EVM
Solana
import { SigningMessageFormat } from "picketapi/picket-js";
​
const { walletAddress, signature, provider, context } = await picket.connect({
chain: "ethereum",
messageFomat: SigningMessageFormat.SIWE
});
import { SigningMessageFormat } from "picketapi/picket-js";
​
const { walletAddress, signature, provider, context } = await picket.connect({
chain: "solana",
messageFomat: SigningMessageFormat.SIWE
});
Notice the additional context field in the function result. Unlike the the simple signing message format, in SIWE the browser adds information to the message. The context field provides the additional client-side information for the SIWE message, so the server can re-create the message and verify the signature.

Customize Connect Wallet Provider Options

For EVM chains, the default connect is configured to allow user to connect via inject providers (Metamask, Brave, etc), WalletConnect, and Coinbase Wallet with a public Ethereum node provider. If you want to modify the Web3Modal providers option, then you can pass through a ConnectProviderOptions configuration when you instantiate Picket.
import Picket from "@picketapi/picket-js";
import MewConnect from "@myetherwallet/mewconnect-web-client";
​
// use infura as your Eth node provider
const infuraID = "MY_INFURA_ID";
​
// add MewConnect provider
// See Web3Modal for configuration options
// https://github.com/Web3Modal/web3modal#projects-using-web3modal
const additionalProviderOptions = {
mewconnect: {
package: MewConnect,
options: {
infuraId,
},
},
};
​
const connectProviderOptions = {
infuraId,
// See Web3Modal for options
providerOptions: additionalProviderOptions,
// merge with existing providers
// Note: You can use "override" to overide and remove the Picket defaults
behavior: "merge",
};
​
const picket = new Picket("YOUR_PUBLISHABLE_KEY_HERE", {
connectProviderOptions,
});
​
// call to connect will show the MewConnect as a wallet provider option
// const { walletAddress, signature, provider } = await picket.connect();

Nonce

A nonce is random value generated by the Picket API to that user must sign to prove ownership a wallet address. The login function handles nonce generation and signature verification for you. You'll only need to use nonce if you'd like to implement your own wallet authentication flow.
A nonce is unique to a project and wallet address. If a nonce doesn't exist for the project and wallet address, Picket will generate a new nonce; otherwise, Picket will return the existing nonce. A nonce is valid for two minutes before self-destructing.
const { nonce } = await picket.nonce({
chain: "ethereum",
walletAddress: "0x_WALLET_ADDRESS"
});

Validate

validate validates an access token. This is helpful to ensure that cached local token is still valid when the app loads. The picket-js library automatically validates access tokens when they are loaded from the local storage cache.
If the access token is valid, validate returns the decoded claims of the access token.
const payload = await picket.validate("ACCESS_TOKEN");

Login with Redirect

picket.loginWithRedirect implements the PKCE flow. In this flow the user is redirected back to a whitelisted redirect URI after authentication, so there are two steps the process 1) authenticate the user 2) handle the login redirect, also known as the login callback.
EVM
Solana
import { defaultLoginRedirectCallback } from "@picketapi/picket-js";
​
// login will redirect user to Picket authorization server
document.getElementById("login").addEventListener("click", async () => {
try {
await picket.loginWithRedirect();
} catch (err) {
console.log("failed to login", err)
}
});
​
// in your callback route (defaults to the same route as your login page)
window.addEventListener("load", async () => {
try {
const { appState } = await picket.handleLoginRedirect();
defaultLoginRedirectCallback(appState);
}
// if successful, get user info and access token
const { accessToken, user } = await picket.authState();
console.log(user);
});
import { defaultLoginRedirectCallback } from "@picketapi/picket-js";
​
// login will redirect user to Picket authorization server
document.getElementById("login").addEventListener("click", async () => {
try {
await picket.loginWithRedirect({ chain: "solana" });
} catch (err) {
console.log("failed to login", err)
}
});
​
// in your callback route (defaults to the same route as your login page)
window.addEventListener("load", async () => {
try {
const { appState } = await picket.handleLoginRedirect();
defaultLoginRedirectCallback(appState);
}
// if successful, get user info and access token
const { accessToken, user } = await picket.authState();
console.log(user);
});
By default, picket.loginWithRedirect will redirect back to the same location (window.location.href) as the initial login request. If you'd like your user to be redirected to a different page, you can pass in additional options
EVM
Solana
await picket.loginWithRedirect({
// restrict access to token holders
contractAddress: "0xCONTRACT_ADDRESS",
minTokenBalance: 1
}, {
// change redirect location
redirectURI: "https://my-app.com/login/callback",
});
await picket.loginWithRedirect({
// restrict access to token holders
tokenIds: ["TOKEN_ID_MINT"],
minTokenBalance: 1
}, {
// change redirect location
redirectURI: "https://my-app.com/login/callback",
});

Login with Popup

Popup windows are often blocked by browsers. For a consistent user experience, prefer login or loginWithRedirect
picket.loginWithPopup is an alternative implementation of the PKCE flow that uses a popup rather than a redirect to securely authenticate users. The lack of redirects is convenient from a user experience perspective, but popups are often blocked by browsers, especially on mobile browsers. If you use this method, warn your users to enable popups on their browser if the flow fails.
EVM
Solana
await picket.loginWithPopup({
// restrict access to token holders
contractAddress: "0xCONTRACT_ADDRESS",
minTokenBalance: 1
});
await picket.loginWithPopup({
// restrict access to token holders
tokenIds: ["TOKEN_ID_MINT"],
minTokenBalance: 1
});
​
Copy link
On this page
Installation
Usage - Quick Start
Login
Logout
AuthState
Connect
Nonce
Validate
Login with Redirect
Login with Popup