Guides
Changelog

Common Flows

Step-by-step walkthroughs for our most popular API use cases

Suggest Edits

1. Display a POAP Collection

You can easily fetch and display a user’s POAPs and have them available in your application for any use case.

Prerequisites

  • An API key to access POAP’s API, apply for one here
  • A user's Ethereum address, ENS, or email

Flow

  1. Use GET /actions/scan/{address} to fetch a user's POAP collection, where address is the Ethereum address, ENS, or email of the user you are trying to display the POAPs for.

📘

Artwork available in various sizes

You can now view and link POAP art in extra small, small, medium, large, and extra large file sizes, in addition to the original size.

To use this, you can request a different resolution version of the image, simply append "?size=small" to the end of the image_url field value. For example, "https://poap.xyz/image.png?size=small".

Result

When a user logs in to your application you will be able to display their POAPs.


2. Token Gating With POAPs

By leveraging POAP, you can implement token gating using POAPs by specific Event ID. This allows only users with a POAP from a specific event to access your app, functionality, or content.

Prerequisites

  • An API key to access POAP’s API, apply for one here
  • An auth token to generate an access token, apply using the same link here
  • A POAP event ID.

Flow

Result

If a user has logged in with their Ethereum wallet that has a POAP from POAP event ID specified, you can grant them access.


3. Creating an Event, submitting a request and checking the status of a request

🚧

Currently available for internal use only

Example: Building a solution for your internal team.

If you are considering providing "create POAP" via your UI, this use case is currently not supported.

❗️

Mandatory: Follow testing etiquette

When testing, ensure you follow testing etiquette outlined in this article.

Testing Checklist

If you are creating a drop for testing purposes, follow this checklist:

  • Mark the event as a private drop
    Since we don’t have a test environment and are testing directly in production, we ask that the event be set to "private". There’s a checkbox for this on the bottom left-hand side, above the save button.
  • Include the word "test" in your title
  • Include additional context in description
  • Include the word test and detail around what type of test this is, and any additional context.**
  • Mark artwork as test
  • Mark artwork as a test. Please avoid any artwork that is a stock image or could be copyright infringement. Do not reuse artwork intended for your actual drop as part of your test.
    Request a minimal number of mint links
  • While testing, we generally suggest requesting a minimal amount of mint links (less than 10). If your test needs more, please explain why in the description.
  • Use a real email address
    In case we have questions about this test and need to reach out.

Conducting multiple tests (above instructions still apply)

  • Title For multiple tests, include test 1 of 3, 2 of 3, 3 of 3 in the title.
  • Description Also indicate the number of tests in the description: 1 of 3, 2 of 3, 3 of 3. If multiple devs are doing tests, please also include that in the description.
  • Artwork Okay to reuse the image for test purposes.
  • Email Use the same email (not just the same domain, but the same user email) for all tests in case we have any questions about your tests and need to reach out.

You can programmatically create an event on your own behalf using the API. This event will still need to be reviewed by the POAP Curation Body and follow curation guidelines.

🚧

Creating POAPs on behalf of your users

Are you considering creating POAPs from your UI on behalf your users because you want them to have a one-stop shop experience? Review the requirements for this to help you decide if this is the right fit for you.
Through our work with hundreds of integrations, we’ve found a phased approach to be the most effective for this use case.

  • Phase 1: Allow the user to bring in an already created POAP and edit code. This is intended to be a super lightweight approach while you get more familiar with the nuances required to make the ideal approach more successful over time.
  • Phase 2: Requires successful completion and demonstration of Phase 1 over a period of time - Currently not supported

Prerequisites

  • An API key to access POAP’s API, apply for one here
  • An auth token to generate an access token, apply using the same link here
  • Details of your event (you can check required fields here)

Flow

  1. Create an event using POST /events by providing the details of the event you’d like to create.
    1. You can define a six-digit secret_code value when creating the event. Please store this code as you'll need it once your request is approved.
    2. Ensure you are adding the content-type: multipart/form-data header.
    3. If you will be using mint links as a distribution method, you can use the requested_codes fields to select how many mint links you need. If you will be using another distribution method, assign a value of 0 to the requested_codes field.
    4. If the creation is successful, you will receive an id in the response. Use this id to refer to your event when using other endpoints.
  2. Once you've created your event, you will need to submit a request for the distribution method of your choice. If you used a value different than zero for the requested_codes field, you can skip this step.
    1. You can have a pending request for each of the distribution methods at any given time. The POAP Curation Body will review all requests. After your request is reviewed, you can submit additional requests if needed.
  3. After submitting a request, The POAP Curation Body will review it. Reviews can take up to 24 hours.
    1. Your request will be in the pending state until it is reviewed. To find out whether your request is still pending or not, use the GET /redeem-requests/active/count endpoint. A result of 0 means that there are no pending requests. Any other value indicates that your requests have not been reviewed yet.
    2. The POAP Curation Body may request additional information or changes to your event or request. You will receive an email from [email protected] to the email address provided when creating your event if that is the case. Follow the instructions in that email to communicate with the Curation Body.
    3. Your request may be either approved or rejected. If your request is rejected, you will receive an email with the rejection reason and tips to improve your requests. You can create another event or submit additional requests applying these tips.
  4. If your request is approved, use POST /event/{id}/qr-codes with the event_id obtained after creating your event (step 1) and the secret_code you entered in step 1 to retrieve the mint links for your drop. The mint links will also be sent via email.
  5. Each mint link has one use. The endpoint will provide the status of each mint link to indicate if it has already been used or not.

Optional: Requesting additional mint links as a top-up

  1. To request additional mint links as a top-up, use POST /redeem-requests with the event_id associated to the drop you are requesting additional mint links for and requested_codes as the amount of top-up you are requesting, along with secret_code created when the original drop was created.

This goes back to Step 3 (above) - After submitting a request, The POAP Curation Body will review it. Reviews can take up to 24 hours.

Creating a POAP on behalf of your users has different requirements.

Are you considering creating POAPs from your UI on behalf your users because you want them to have a one-stop shop experience? Review the requirements for this to help you decide if this is the right fit for you.
Through our work with hundreds of integrations, we’ve found a phased approach to be the most effective for this use case.

  • Phase 1: Allow the user to bring in an already created POAP and edit code. This is intended to be a super lightweight approach while you get more familiar with the nuances required to make the ideal approach more successful over time.
  • Phase 2: Currently not supported
    Prerequisite: Successful completion of Phase 1 is required for anyone considering Phase 2.
    Ensure that you have read and understood the Issuer Guidelines for creating quality POAP drops and are able to ensure compliance with these guidelines
    • Issuer Email: You must provide the issuer's email! The issuer is the person creating the POAP drop. This email is used to communicate with the issuer when the Curation Body might need additional context.
    • Curation review may take 24-48 hours. You should manage expectations for users and encourage them to not submit drops starting in less than 48 hours.
    • When requesting access, you will be required to provide the pre-curation steps you are taking to filter out low-quality drop petitions before submitting the drop to the POAP Curation Body
    • Speak to the Integration team to explore pricing.

Please note that every drop is reviewed by Curation and is expected to follow Curation Guidelines (which may be subject to change). Receiving general approval as an integrator to create POAPs on behalf of your users does not mean that all or any drops will be automatically approved. Each drop is still reviewed one-by-one at the discretion of the Curation Body.


4. Minting a POAP directly to a wallet

Prerequisites

  • An API key to access POAP’s API, apply for one here
  • An auth token to generate an access token, apply using the same link here
  • An event has been created
  • A user's Ethereum address, ENS, or email

Flow

  1. Use POST /event/{id}/qr-codes to get a qr_hash (claim codes) for your event.
  2. Use GET /actions/claim-qr and pass in a qr_hash from the previous step to get the claim secret.
  3. Once you have the qr_hash and the secret, you can mint the POAP to your user's Ethereum address, ENS, or email using POST /actions/claim-qr.

If you need additional claim codes, use the POST /redeem-requests endpoint.


Updated 6 months ago