Skip to main content

Creating Passes

To create a pass, you will need to call the POST /v0/passes with a signed message, and some related information.

Prerequisites​

Before calling the POST /v0/passes endpoint, it is necessary to first obtain a signature from the user's wallet.

This can be done through the use of any JSON RPC provider that has a connected wallet. Additionally, we have integrated solutions such as Crossmint and Magic Link for custodial wallet solutions. The following are examples of how to generate a signature:

Wagmi Example​

Using the wagmi useSigner React hook: View sample integration.

import { useSigner } from "wagmi";

export const Example = () => {
  const { data: signer } = useSigner(); // NOTE: wallet must already be connected

  const getSignature = async () => {
    const signatureMessage = `Sign this message to generate a test pass with ethpass.xyz\n${Date.now()}`;

    const signature = await signer.signMessage(signatureMessage);
    // if successful, call /api/ethpass/create to create the pass
  };

  return <div>Your user interface here</div>;
};

Crossmint Example​

Using @crossmint/connect library. View sample integration.

import { BlockchainTypes, CrossmintEVMWalletAdapter } from "@crossmint/connect";

export const Example = () => {
  const _crossmintConnect = new CrossmintEVMWalletAdapter({
    apiKey: process.env.NEXT_PUBLIC_CROSSMINT_API_KEY,
    chain: BlockchainTypes.ETHEREUM, // BlockchainTypes.ETHEREUM || BlockchainTypes.POLYGON. For solana use BlockchainTypes.SOLANA
  });

  const getSignature = async () => {
    const signatureMessage = `Sign this message to generate a test pass with ethpass.xyz\n${Date.now()}`;

    const signature = await _crossmintConnect.signMessage(signatureMessage);
    // if successful, call /api/ethpass/create to create the pass
  };

  return <div>Your user interface here</div>;
};

Using magic-sdk library. View sample integration.

import { ConnectExtension } from "@magic-ext/connect";
import { Magic } from "magic-sdk";
import { ethers } from "ethers";

export const Example = () => {
  const _magic =  new Magic(process.env.NEXT_PUBLIC_MAGIC_LINK_API_KEY, {
        network: "mainnet",
        locale: "en_US",
        extensions: [new ConnectExtension()],
      } as any)

  const getSignature = async () => {
    const signatureMessage = `Sign this message to generate a test pass with ethpass.xyz\n${Date.now()}`;

    const provider = new ethers.providers.Web3Provider(magic.rpcProvider);
    const signer = provider.getSigner();
    const signature = await signer.signMessage(signatureMessage);
    // if successful, call /api/ethpass/create to create the pass
  };

  return <div>Your user interface here</div>;
};

Creating a Pass from an NFT​

Once you have obtained a signature and relevant information about their NFT, you can use the POST /v0/passes endpoint to create a pass.

You can use any language, but here is an example in Javascript:

const payload = {
  signature:
    "0x71147d2b97a397061e6dbd82351867a7057bdb4d9566a8ac2d618e1a3e62d43c722245fb4e6a8e9ee814348bdd5c433224c8c10f9fadf7fd154b44c17056109f1c",
  signatureMessage: "Sign this message to generate a pass with ethpass.xyz",
  platform: "apple",
  chain: {
    name: "evm",
    network: 1,
  },
  nft: {
    contractAddress: "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3",
    tokenId: "443",
  },
  image: "https://ipfs.io/ipfs/QmYyXcVMgny4BJYiaUyTU46HX7seFNgnvte2eoL2fN2PXf",
};

const response = await fetch("https://api.ethpass.xyz/api/v0/passes", {
  method: "POST",
  body: JSON.stringify(payload),
  headers: new Headers({
    "content-type": "application/json",
    "X-API-KEY": "YOUR_SECRET_API_KEY",
  }),
});

ethpass will use the signature to confirm that the NFT belongs to the owner of the wallet, and will respond with a URL to download the pass.

Creating a Pass without an NFT​

In addition to creating a pass that is tied to a specific NFT, it is also possible to create a pass that is linked to a user's wallet. This can be useful if you want to enforce multiple conditions on the wallet, such as holding a certain amount of ETH or having an ENS.

To issue this type of pass, simply follow the same process as above but omit the nft parameter. The signature obtained from the user will confirm that they are the owner of the wallet.

NOTE: In order to check certain conditions, the logic must be implemented in your application. It is also recommended to verify these conditions again when scanning the pass. This is because, the ethpass API does not track changes to assets or automatically invalidate passes. Therefore, it is important to ensure that the pass is still valid before using it.

const payload = {
  signature:
    "0x71147d2b97a397061e6dbd82351867a7057bdb4d9566a8ac2d618e1a3e62d43c722245fb4e6a8e9ee814348bdd5c433224c8c10f9fadf7fd154b44c17056109f1c",
  signatureMessage: "Sign this message to generate a pass with ethpass.xyz",
  platform: "apple",
  chain: {
    name: "evm",
    network: 1,
  },
  image: "https://ipfs.io/ipfs/QmYyXcVMgny4BJYiaUyTU46HX7seFNgnvte2eoL2fN2PXf",
};

const response = await fetch("https://api.ethpass.xyz/api/v0/passes", {
  method: "POST",
  body: JSON.stringify(payload),
  headers: new Headers({
    "content-type": "application/json",
    "X-API-KEY": "YOUR_SECRET_API_KEY",
  }),
});

Preventing the Creation of Duplicate Passes​

The ethpass API is designed to be flexible and non-custodial, meaning it will not restrict the creation of passes with duplicate parameters. To avoid creating duplicate passes, it is recommended to implement a check in your creation process to check if a pass with the same parameters already exists.

You can find more details on how to do that here.