Picket Docs
Search…
β›”
Restrict Access to Specific Wallets
A guide to restricting access based on a list of allowed wallet addresses

Get your API Key

An API key is required to authorize your requests when interacting with the Picket API. Requests without an API key will result in an error.
To get your API key, go to the account dashboard. API keys are associated with projects to make key management easy.
Within each project there are two types of API keys
  • Publishable keys: These keys are used client-side and are meant for client-side libraries, like picket-js.
  • Secret keys: As the name suggests, these must be kept secret. They are meant for server-side libraries, like picket-node​
Authorization to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password. When using Picket SDKs, API Authorization is handled for you.
Javascript
Curl
import Picket from "@picketapi/picket-js";
const picket = new Picket('YOUR_PUBLISHABLE_KEY_HERE');
curl https://picketapi.com/v1/{any_endpoint}
-u YOUR_SECRET_KEY

Install the Picket SDK

The best way to interact with our API is to use one of our official libraries.
As a first step after ensuring you have your API keys, install one of the picket libraries for the easiest integration. Type the following into your command line
Javascript
React
Node
# Install via NPM
npm install --save "@picketapi/picket-js"
# Install via NPM
npm install --save "@picketapi/picket-react"
# Install via NPM
npm install --save "@picketapi/picket-node"
Want to use Picket with other web-frameworks? Let us know at [email protected]​

Restrict Access to Specific Wallets

You can use Picket to gate access by a list of allowed wallets. All you need to do is pass the allowedWallets requirements to the login() function.

Login User w/ a Allowed Wallet List

Javascript
React
Curl
import Picket from "@picketapi/picket-js";
​
const picket = new Picket('YOUR_PUBLISHABLE_KEY_HERE');
​
// Restrict access to a set of predefined wallets
const requirements = {
allowedWallets: ["0xYOUR", "0xWALLET", "0xADDRESSES","0xHERE"]
}
​
const { accessToken, user } = await picket.login(requirements);
console.log(user);
import { PicketProvider, usePicket } from "@picketapi/picket-react";
​
function MyApp({ children }) {
return (
<PicketProvider apiKey="YOUR_PUBLISHABLE_KEY_HERE">
{children}
</PicketProvider>
);
}
​
// Restrict access to a set of predefined wallets
const requirements = {
allowedWallets: ["0xYOUR", "0xWALLET", "0xADDRESSES","0xHERE"]
}
​
​
function MySecurePage() {
const {
isAuthenticating,
isAuthenticated,
authState,
logout,
login
} = usePicket();
// user is logging in
if (isAuthenticating) return "Loading";
​
// user is not logged in
if (!isAuthenticated) {
return (
<div>
<p>You are not logged in!</p>
<button onClick={() => login(requirements)}>Login with Wallet</button>
</div>
)
}
​
// user is logged in πŸŽ‰
const { user } = authState;
const { walletAddress } = user;
return (
<div>
<p>You are logged in as {walletAddress} </p>
<button onClick={() => logout()}>Logout</button>
</div>
)
}
curl https://picketapi.com/api/v1/auth \
-X POST \
-u PROJECT_SECRET_KEY \
-H 'Content-Type: application/json' \
-d '{
"walletAddress": "0xWALLET_ADDRESS",
"signature": "SUPER_SECRET_SIGNATURE",
"allowedWallets": ["0xYOUR", "0xWALLET", "0xADDRESSES","0xHERE"]
}'
You successfully restricted access to specific wallets
The returned access token can now act as secure proof of wallet ownership until expiration. It can be passed server side and verified there in order to restrict resources to specific wallets

Allowed Wallets and Token Ownership Requirements

Allowed wallet lists can be used in combination with token ownership requirements.
If both allowedWallets and token ownership requirements are passed to the login function, then the user will be granted access if they either are on the allowed wallets list or meet the token ownership requirements.
Testing Tip
Using both allowedWallets and token ownership requirements can be helpful for testing a token-gating page, which you are developing, but don't own the necessary tokens for.
Javascript
React
Curl
import Picket from "@picketapi/picket-js";
​
const picket = new Picket("YOUR_PUBLISHABLE_KEY_HERE");
​
// Restrict access to a set of predefined wallets or token holders
const requirements = {
// optional. The default chain is the Ethereum Mainnet
chain: "ethereum",
// Replace this example address with whichever contract you are verifying ownership for
contractAddress: "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
// Replace with minimum balance you want to verify users' currently hold,
// or omit if any number of tokens is sufficient
minTokenBalance: 1,
allowedWallets: ["0xYOUR", "0xWALLET", "0xADDRESSES","0xHERE"]
}
​
const { accessToken, user } = await picket.login(requirements);
console.log(user);
import { PicketProvider, usePicket } from "@picketapi/picket-react";
​
function MyApp({ children }) {
return (
<PicketProvider apiKey="YOUR_PUBLISHABLE_KEY_HERE">
{children}
</PicketProvider>
);
}
​
// Restrict access to a set of predefined wallets
// Restrict access to a set of predefined wallets or token holders
const requirements = {
// optional. The default chain is the Ethereum Mainnet
chain: "ethereum",
// Replace this example address with whichever contract you are verifying ownership for
contractAddress: "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
// Replace with minimum balance you want to verify users' currently hold,
// or omit if any number of tokens is sufficient
minTokenBalance: 1,
allowedWallets: ["0xYOUR", "0xWALLET", "0xADDRESSES","0xHERE"]
}
​
​
function MySecurePage() {
const {
isAuthenticating,
isAuthenticated,
authState,
logout,
login
} = usePicket();
// user is logging in
if (isAuthenticating) return "Loading";
​
// user is not logged in
if (!isAuthenticated) {
return (
<div>
<p>You are not logged in!</p>
<button onClick={() => login(requirements)}>Login with Wallet</button>
</div>
)
}
​
// user is logged in πŸŽ‰
const { user } = authState;
const { walletAddress } = user;
return (
<div>
<p>You are logged in as {walletAddress} </p>
<button onClick={() => logout()}>Logout</button>
</div>
)
}
curl https://picketapi.com/api/v1/auth \
-X POST \
-u PROJECT_SECRET_KEY \
-H 'Content-Type: application/json' \
-d '{
"walletAddress": "0xWALLET_ADDRESS",
"signature": "SUPER_SECRET_SIGNATURE",
"chain": "ethereum",
"contractAddress": "0xCONTRACT_ADDRESS",
"minTokenBalance": 1
"allowedWallets": ["0xYOUR", "0xWALLET", "0xADDRESSES","0xHERE"]
}'

Re-Validate an Authenticated User

Once you have received an access token via picket.login() or the /auth endpoint, you can re-validate the authenticated user's access token as needed. If you are using a client-side Picket library, it will automatically re-validate a users access token every-time it fetches a cached access token.
To validate an access token manually, call the /validate endpoint
Javascript
try {
await picket.validate(accessToken, {
// use the same requirements from login()
allowedWallets,
});
// Do anything or present any content
// that you want to restrict to verified token holders
}
catch (err) {
console.error("Access token expired, invalid, or doesn't meet the token ownership requirements.");
}

Using Access Tokens

Once you've successfully authenticated a wallet you will have an access token. An access token acts as a secure guarantee of an authenticated wallet until expiration without the need for additional user interactions.
This allows you build and interact with APIs that restrict content based on a user's wallet address. On the client-side, you can include a user's access token API requests, and server-side, you can validate any received access tokens to ensure the request came from a user who owns the wallet address.

1. Include the Access Token in API Requests

Javascript
curl
import Picket from "@picketapi/picket-js";
const picket = new Picket("YOUR_PUBLISHABLE_KEY_HERE");
​
// NOTE: This assumes the user is logged in
const { accessToken } = await picket.authState();
​
await fetch("myapi.com", {
method: "GET",
headers: {
// Use the access token as a bearer auth token
Authorization: `Bearer ${accessToken}`
}
});
curl myapi.com -H "Authorization: Bearer ${ACCESS_TOKEN}"

2. Validate the Access Token Server-Side

Server-side libraries, like picket-node, require a secret API key and must only be used in a secure, server-side environment.
Node
Curl
import Picket from "@picketapi/picket-node";
​
const picket = new Picket("YOUR_SECRET_KEY_HERE");
​
// REPLACE code to get access token from client request
const accessToken = "";
​
try {
// REPLACE with the requirements you used in login()
const requirements = {
allowedWallets: ["0xYOUR", "0xWALLET", "0xADDRESSES","0xHERE"]
};
const { walletAddress } = await picket.validate(accessToken, requirements);
// save user's wallet address to the DB
} catch (err) {
console.error("invalid access token!");
}
​
curl https://picketapi.com/api/v1/auth/validate \
-X POST \
-u PROJECT_SECRET_KEY \
-H 'Content-Type: application/json' \
-d '{
"accesssToken": "${ACCESS_TOKEN}",
"allowedWallets": ["0xYOUR", "0xWALLET", "0xADDRESSES","0xHERE"],
}'
Copy link
On this page
Get your API Key
Install the Picket SDK
Restrict Access to Specific Wallets
Login User w/ a Allowed Wallet List
Re-Validate an Authenticated User
Using Access Tokens